:: Version 3.0.0 ::

2.7.x to 3.0.0 Migration Notes

The version 3.0.0 of iTop is roughly backward compatible with previous 2.x versions, except extensions bringing specific displayed pages.

This document highlights issues which can occur while migrating your iTop to this version.

Impact on Users

This version has a major impact on users habits. Check the What's new document for all the changes impacting the ways things used to be done in the past and how they should be done in 3.0.

  • Change on WorkOrder behavior: 'ticket' and 'end date' are now optional, 'end date' if empty is set automatically on closure.
  • Change on external keys autocomplete: Max. number of displayed results now uses the max_autocomplete_results configuration parameter in both the backoffice and the end-users portal where it was previously hardcoded to respectively 150 and 20 items.

Notification & OQL queries

  • On Setup (new installation or version upgrade), a set of OQL queries usable in Notifications are automatically loaded.
  • Queries label and description are in iTop default language, when translation exist (EN US and FR FR today)

To check before upgrading

Before migrating, be aware that a lot of iTop extensions are not yet compatible with the version 3.0.0

System

  • There is a new “node_modules” folder under the iTop root folder. Mind to update your migration / backup scripts if necessary.
  • A new log was added to allow module developers to track calls to iTop core deprecated files of PHP methods. See What's new : Log calls to deprecated files / PHP methods.

Database

We have added a field user_id in table CMDBChange to identify users who made the change.

  • In the past we were just keeping the person friendlyname, so we were exposed to name changes and homonyms.
  • Of course previously created entries in the Change History, will not contain information in that new field.
  • This table can be huge, so the migration can take time, the good news is that it can be anticipated and done anytime before the migration. For this:
    • Here is the SQL query to perform in advance: FIXME
    • This is an estimate of how long it will take depending on the table volume (entries count): FIXME
  • 937 000 lines of priv_change, it took 5 sec to add user_id to the table during upgrade setup.
  • FIXME Provide a script to try to set priv_change.user_id on previous values, so the display of caselog uses the avatar for old entries.

Extensions

Extensions

Here is the compatibility status of the Hub Premium extensions

In April 2021, all published versions of those extensions, are not compatible with 3.0:

  • Project management extended
  • Customized request forms
  • Time tracking
  • Calendar view
  • Follow-up forms without authentication
  • Attributes visual beautifier → but it is integrated in 3.0
  • Enhanced global search
  • Hyperlinks configurator
  • Kanban

All versions of those extensions are compatible with 3.0:

  • Auto dispatch ticket to a team
  • Calendar invitations
  • Location Hierarchy
  • Multiple email per contact
  • Notify on expiration
  • Simple Stock Management

For non-premium, chances to be compatible:

  • Admin Tools Delegation → compatible
  • Approval process automation → maybe compatible, but not aligned to the new look
  • Approval process light → probably compatible
  • Assign to Me → probably compatible
  • Attributes description tooltip → Included in 3.0
  • Autoclose Ticket → probably compatible
  • Bubble caselogs → Included in 3.0
  • Communications to the Customers → probably compatible
  • Component details from OCS → compatible
  • Customer Survey → → maybe compatible, but not aligned to the new look
  • Data archiver simple → probably compatible
  • Data Collectors (LDAP, OCS, vsphere) → compatible
  • Data synchronization dashboard → probably not compatible and not aligned to the new look
  • Database maintenance tools → probably compatible
  • Dispatch Incident to a team → compatible
  • Dispatch Incident to a team → compatible
  • Gantt view → compatible but not aligned to the new look
  • … Work in progress…

Some will have to be updated PRIOR to your iTop upgrade, but this is not yet known: FIXME

For custom extensions

Font awesome icons

In 3.0, we have removed the Font Awesome v4 compatibility bridge, therefore only Font Awesome v5 icons are available now. As some names have changed since v4, check is the ones you used are concerned: https://fontawesome.com/how-to-use/on-the-web/setup/upgrading-from-version-4#name-changes

If you developed an extension that hooked the global search field in the backoffice, you might need to adjust your code as its HTML markup has changed in iTop 3.0.

To hook up with the global search input, you should target the JS selector

[data-role="ibo-global-search--head"]

Images

We removed a bunch of images from iTop, if you used them you'll need to replace them.

  datamodels/2.x/
             itop-attachments/icons/
                                   doc.png
                                   document.png
                                   html.png
                                   image.png
                                   movie.png
                                   odb.png
                                   odg.png
                                   odp.png
                                   ods.png
                                   odt.png
                                   one.png
                                   pdf.png
                                   ppt.png
                                   txt.png
                                   xls.png
                                   zip.png

PHP APIs

cmdbAbstractObject::DisplayBareHeader

This function changed a bit in order to use the new UIBlock system.

Before, you could manipulate the current page ($oPage) to:

  • Add resource files such as JS, CSS, …
  • Add inline JS and CSS
  • Add HTML markup directly in the header
  • And even in any tab of the object as the API is very permissive…

Now, the object page is made of UIBlock objects. FIXME Mettre une image qui montre le block du panel, du header, du titre, soustire, toolbar, …

You can still use all of the PHP methods you used to in iTop 2.7 and older, but there is a slight change regarding the HTML markup.

  • Adding HTML using the WebPage::add() method (eg. $oPage→add(“

    Hello world!

    ”);) will put that markup before the object panel, not directly in the header anymore. FIXME Mettre une image pour montrer le comportement avant de migrer le code.

  • FIXME Expliquer comment faire un bloc et le mettre au choix dans le titre, soustitre, toolbar, …

Also, you should add the new optional parameter to the method signature to avoid warnings.

iTop 2.7
public function DisplayBareHeader(WebPage $oPage, $bEditMode = false)
{
    ...
iTop 3.0
public function DisplayBareHeader(WebPage $oPage, $bEditMode = false, $sMode = self::ENUM_OBJECT_MODE_VIEW)
{
    ...
Custom exports

The BulkExport::DisplayFormPart() has been deprecated and will be removed in a future version. You should rather use the new BulkExport::GetFormPart() method. The migration is pretty easy, all you have to do is return a UIBlock instead of: - Returning a string - Adding HTML directly into the page using the $oP parameter

iTop 2.7
class CustomExport extends BulkExport
{
        public function DisplayFormPart(WebPage $oP, $sPartId)
        {
                switch($sPartId)
                {
                        case 'interactive_fields_zip':
                                $this->GetInteractiveFieldsWidget($oP, 'interactive_fields_zip');
                                break;
 
                        case 'zip_options':
                                $sHtml = <<<HTML
<fieldset>
        <legend>Options</legend>
        Some options for the exporter
</fieldset>
HTML;
                                $oP->add($sHtml);
                                break;
 
                        default:
                                return parent::DisplayFormPart($oP, $sPartId);
                }
        }
}
iTop 3.0
use Combodo\iTop\Application\UI\Base\Component\Html\Html;
 
class CustomExport extends BulkExport
{
        public function GetFormPart(WebPage $oP, $sPartId)
        {
                switch($sPartId)
                {
                        case 'interactive_fields_zip':
                                return $this->GetInteractiveFieldsWidget($oP, 'interactive_fields_zip');
                                break;
 
                        case 'zip_options':
                                $sHtml = <<<HTML
<fieldset>
        <legend>Options</legend>
        Some options for the exporter
</fieldset>
HTML;
                                return new Html($sHtml);
                                break;
 
                        default:
                                return parent::DisplayFormPart($oP, $sPartId);
                }
        }
}

If you want your exporter to be compatible with both iTop 2.7 and iTop 3.0+, you can keep the 2 methods (and refactor the code in protected methods to avoid maintaining it twice).

iTop 3.0 with backward compatiblity with iTop 2.7
// Will work with iTop 2.7 even if the class does not exists
use Combodo\iTop\Application\UI\Base\Component\Html\Html;
 
class CustomExport extends BulkExport
{
        // Not used in iTop 3.0
        public function DisplayFormPart(WebPage $oP, $sPartId)
        {
                switch($sPartId)
                {
                        case 'interactive_fields_zip':
                                $this->GetInteractiveFieldsWidget($oP, 'interactive_fields_zip');
                                break;
 
                        case 'zip_options':
                                $oP->add($this->GetZipOptionsAsHtml());
                                break;
 
                        default:
                                return parent::DisplayFormPart($oP, $sPartId);
                }
        }
 
        // Not used in iTop 2.7
        public function GetFormPart(WebPage $oP, $sPartId)
        {
                switch($sPartId)
                {
                        case 'interactive_fields_zip':
                                return $this->GetInteractiveFieldsWidget($oP, 'interactive_fields_zip');
                                break;
 
                        case 'zip_options':
                                return new Html($this->GetZipOptionsAsHtml());
                                break;
 
                        default:
                                return parent::DisplayFormPart($oP, $sPartId);
                }
        }
 
        protected function GetZipOptionsAsHtml()
        {
                $sHtml = <<<HTML
<fieldset>
        <legend>Options</legend>
        Some options for the exporter
</fieldset>
HTML;
                return $sHtml;
        }
}

JS widgets

FIXME Essayer de faire un autre widget (legacy) qui herite du widget 3.0, mettre des methodes a surcharger la ou il faut. Exemple ext. Kanban

Dictionnaries

Remove entries

FIXME

Put the list of the dict entries codes that have been removed in this version so people can ensure that they don't overload it in the XML.

  • 'UI:YourSearch'
  • 'UI:Dashboard:Edit' replaced by 'UI:Dashboard:CreateCustom'
  • 'UI:Dashboard:Revert' replaced by 'UI:Dashboard:DeleteCustom'
  • 'PageTitle:ClassProjections'
  • 'UI:UserManagement:Profile'
  • 'UI-ChangeManagementMenu-ChangesByWorkgroup'
  • 'UserLDAP/Attribute:password'

XML Datamodel

Slight modification on theme customization XML, see Theme Customization, especially imports>import>xsi:type 2.7 theme customization variables are probably obsolete, see above page to migrate your theme.

Breaking changes

FIXME

Put the list of breaking changes including the deprecations that are finally removed

Removal of the display templates in classes

This was an old and unused feature from iTop 2.0 which we decided to completely remove during the backoffice rework. It means that if you used the `display_template` property of a (PHP or XML) class to display its form differently, it won't work anymore in iTop 3.0, the standard form will be displayed instead.

To ease the migration, the application will upgrade safely if the property is still present in the XML / PHP (it will be silently ignored). Even though it is not mandatory for the migration, we recommend that you remove any usage of this feature.

Example of customization in an XML class in iTop 2.7 and older
<itop_design>
  <classes>
    <class id="UserRequest">
      <properties>
        <display_template _delta="redefine">my-module/my-template.html</display_template>
      </properties>
    </class>
  </classes>
</itop_design>

UserRequest:OnInsert

If your iTop is in Request Management Full ITIL mode, and you have created a Ticket:OnInsert() method, it was by mistake not called for UserRequest creation, it is now, so check any adverse impact due to this correction.

DBObject::GetRelationQueries

The method (deprecated since 2.2) has been removed. if you find <method id=“GetRelationQueries”> in your XML, you have to replace this method by a itop_design/classes/class/relations tag.

Tag Usage Description
<class id="name"> mandatory Declaration of class
<relations> optional Relations between the object of the current class and objects of other classes. Supported only since iTop 2.2.0.
<relation id="impacts"> zero or more A given relation. Today "impacts" is the only value supported by iTop, but a module could use other values
<neighbours> mandatory Neighbour classes
<neighbour id="name"> zero or more Name is usually the neighbour class name. Either an attribute must be specified, or a pair of queries (downward and upward)
<query_down>SELECT SoftwareInstance AS s WHERE s.system_id = :this->id</query_down> optional The OQL query that defines the related objects, following the relation flow (downstream)
<query_up>SELECT System AS s JOIN SoftwareInstance AS si ON si.system_id = s.id WHERE si.id = :this->id</query_up> optional The OQL query that defines the related objects, going backward in the relation flow (upstream)
<attribute>something_list</attribute> optional An alternative to the OQL query is to specify an attribute (an external key or a link set)
<direction>both</direction> optional Set to "down" to restrict the browsing. Defaults to "both"

Person

The dependencies node of the manager_id has been removed as there was no usage of org_id in the default OQL filter. It's probably from a time where Manager was limited to the organization of the Person. If you removed or redefined it, you will need to adapt your XML.

Datamodel in iTop 2.7 and older
<itop_design>
  <classes>
    <class id="Person">
      <fields>
        <field id="manager_id"xsi:type="AttributeExternalKey">
          <filter><![CDATA[SELECT Person]]></filter>
          <dependencies>
            <attribute id="org_id"/>
          </dependencies>
        </field>
      </properties>
    </class>
  </classes>
</itop_design>

Deprecations

FIXME

Put the list of the new deprecations in iTop 3.0.0

Setup: Unattented install

Breaking changes

Additional modules to select

Before running unattended installation you have to adapt the XML file you intend to provide to dedicated script unattended_install.php.

Additionnal XML configuration for unattended installation
<?xml version="1.0" encoding="UTF-8"?>
<installation>
    <selected_modules type="array">
        <item>itop-structure</item>
        <item>itop-bridge-cmdb-ticket</item>
        ...
    </selected_modules>
        ...
</installation>

For more information regarding unattended installation: https://wiki.combodo.com/doku.php?id=latest:advancedtopics:automatic_install&s[]=unattended#unattended_installat

PHP APIs

Breaking changes

FIXME

Put the list of breaking changes including the deprecations that are finally removed

Automatic history generation

At the very beginning of iTop API, it was the developper job to fill the history by creating CMDBChange objects. Then the API was modified so that the history objects are created automatically (CMDBChange and CMDBChangeOp* objects). The old methods were kept for existing code, but renamed with the suffix Tracked : DBObject::DBInsertTracked, DBObject::DBInsertTrackedNoReload, DBObject::DBUpdateTracked, DBObject::DBDeleteTracked.

In 2.7.0 those DB*Tracked methods were deprecated, and are now removed in 3.0.0.

In consequence, you must replace your old code with the new one.

Example of old code pattern :

$oMyChange = MetaModel::NewObject('CMDBChange');
$oMyChange->Set('date', time());
$oMyChange->Set('userinfo', CMDBChange::GetCurrentUserName());
$this->DBUpdateTracked($oMyChange);

If you don't need to have a proper CMDBChange object, then you can simply replace this code by :

$this->DBUpdate();

The API will automatically create a CMDBChange object and persist it.
All the subsequent modifications done in objects (DBInsert, DBUpdate, DBDelete) will use the same CMDBChange.
By default the fields will be initialized to :

  • date : current time
  • userinfo : current user login (get by calling CMDBChange::GetCurrentUserName())
  • origin : interactive

For reference, this is done in \CMDBObject::CreateChange.

The values can be modified by calling, before doing any CRUD operation (DBInsert, DBUpdate, DBDelete) :

  • \CMDBObject::SetTrackInfo
  • \CMDBObject::SetTrackOrigin

At any moment the current change can be replaced by calling \CMDBObject::SetCurrentChange. This could be necessary for example in a background process class : you could need to have a CMDBChange for every object the task is processing. But beware that this CMDBChange must be persisted before : indeed it will be used by the API when creating new CMDBChangeOp (change attribute), so the current change MUST has a valid key attribute (> 0).
Note that since 2.7.2 the change can be reset by passing null, so that a new change will automatically be created by the API.

Changes on API methods

Some APIs have evolved, check the list below FIXME

MetaModel::GetStateAttributeCode($sClass)

In iTop 2.7 and older, this method used to return the state attribute code only for a class with a lifecycle and an empty string for a class without.
Since the introduction of the fields semantic, it now also returns the state attribute code for class that have a state attribute but no transition like Person, Team, PhysicalDevice, …

What to check:

  • OK If you use this function to only get the state attribute code, it's fine there is nothing to do.
  • KO If you use this function to check if a class has a lifecycle or transtions, you might face issues and should use the new MetaModel::HasLifecycle($sClass) method instead.

A new optional parameter $sDecorationClasses has been introduced in third position, before other existing ones. This parameter allows you to define which CSS classes will be used to decorate the menu group in the backoffice, typically some FontAwesome classes to show an icon, but you could also use your own CSS classes to display something totally custo.

Why did we put that new parameter in third position instead of the last one to keep backward compatiblity?

  • When auditing the code base of iTop and its extensions, it appear that other optional parameters where almost never used, whereas this one is on almost every call. It seemed easier / cleaner (in the long term) to migrate a few entries than to fill every optional parameters with a dummy value on all the existing calls.
  • If not migrated, the application does not crash, the menu group only disappears which seemed acceptable as it should seen on staging
iTop 2.7 and older
// Menu group without optional parameters
$oMenuGroup = new MenuGroup('DataAdministration', 10 /* fRank */);
 
// Menu group with optional parameters
$oMenuGroup = new MenuGroup('DataAdministration', 10 /* fRank */, 'SomeClass' /* sEnableClass*/, UR_ACTION_READ /*iActionCode */);
iTop 3.0
// Menu group without optional parameters
$oMenuGroup = new MenuGroup('DataAdministration', 10 /* fRank */, 'fas fa-folder' /* sDecorationClasses */);
 
// Menu group with optional parameters
// Mind that the 'fas fa-folder' has been inserted in third position
$oMenuGroup = new MenuGroup('DataAdministration', 10 /* fRank */, 'fas fa-folder' /* sDecorationClasses */, 'SomeClass' /* sEnableClass*/, UR_ACTION_READ /*iActionCode */);

Changes on triggers

Trigger on object update

The triggers are now called AFTER the database update (instead of before). The requests used to filter the triggers may behave differently than in iTop 2.7.

Changes on internal methods

Some internal methods (not meant to be used in customizations) have been removed or renamed in iTop 3.0.0, they should not be present in your customizations (snippets, extensions, …) but you should check to be sure.

In the table below we described each of those changes. For each, search for the string in the What to search for column in your customizations and proceed as described in the What to do if found column.

Mind that for some strings to search, there is no ending parenthesis. This is not a mistake, it's because we cannot anticipate the parameters name.
What changed Why was it removed What to search for What to do if found
MetaModel::GetDisplayTemplate($sClass) Since the removal of the “display_template” property in classes, the corresponding method in the MetaModel has been removed as well MetaModel::GetDisplayTemplate( No alternative, you cannot use those template anymore
MetaModel::GetNextKey($sClass) Deprecated since 2.7 MetaModel::GetNextKey( Use ItopCounter::incRootClass( instead
CMDBSource::GetNextInsertId($sTable) Deprecated since 2.7 CMDBSource::GetNextInsertId( use method in ItopCounter instead
iTopWebPage::IsMenuPaneVisible() Refactored in the new NavigationMenu component iTopWebPage::IsMenuPaneVisible() Use iTopWebPage::GetNavigationMenuLayout()→IsExpanded() instead
iTopWebPage::AddToMenu() Refactored in the new NavigationMenu component iTopWebPage::AddToMenu( No alternative, you cannot add content to the menu yet
ApplicationMenu::DisplayMenu($oPage, $aExtraParams) Refactored due to the new backoffice UI ApplicationMenu::DisplayMenu( Use ApplicationMenu::GetMenuGroups() instead and refactor your code to use the new returned structure
ApplicationMenu::DisplaySubMenu($oPage, $aMenus, $aExtraParams, $iActiveMenu) Refactored due to the new backoffice UI ApplicationMenu::DisplaySubMenu( Use ApplicationMenu::GetSubMenuNodes() instead and refactor your code to use the new returned structure

Deprecations

Put here the list of the new deprecations in iTop 3.0.0

FIXME

All SetupPage::log* methods are deprecated. Replace them by same methods in the SetupLog class:

  • SetupPage::log_error ⇒ SetupLog::Error
  • SetupPage::log_warning⇒ SetupLog::Warning
  • SetupPage::log_info ⇒ SetupLog::Info
  • SetupPage::log_ok ⇒ SetupLog::Ok
  • SetupPage::log ⇒ SetupLog::Ok

All of the “old” history APIs are deprecated due to the introduction of the “activity panel”, they will be removed in iTop 3.1:

  • cmdbAbstractObject::DisplayBareHistory()
  • HistoryBlock class
  • 'history' operation of the ajax.render.php endpoint
  • 'history_from_filter' operation of the ajax.render.php endpoint

Other deprecated methods :

  • CMDBObject::CheckUserRights: legacy method that wasn't used anymore
  • DBObject::GetName: legacy method used prior to the friendlyname introduction, use it and its dictionary format instead
  • Config 'skip_strong_security'
  • require or include of the core/coreexception.class.inc.php file : CoreException class was moved to application/exceptions, and is now loaded using the autoloader (see commit b85b4d00)

JS APIs

Deprecations

Tooltips libs

Up until iTop 2.7, several tooltip libs were used (qTip 1.0 and jQuery tooltip in the backoffice, Bootstrap's tooltip in the portal). with iTop 3.0 they are now deprecated as we decided to switch to a more modern one; they will be completely removed in a future version.

The new tooltip lib is now Tippy which allows the tooltips to be placed perfectly especially when near the screen limits. It is used in both the backoffice and the portal.

For a better DX, we decided to make an abstraction layer to manipulate the tooltips so the code is the same no matter the third-party lib used as it is most likely to be changed (again) in the future.

Deprecated calls in the backoffice
// Call to qTip 1.0
xxx.qtip(...
 
// Call to jQuery tooltip
xxx.tooltip(...
Deprecated calls in the portal
// Call to Bootstrap tooltip
xxx.tooltip(...

FIXME Put here how a tooltip should be prepared with HTML markup

FIXME Put here which functions are available for manipulation

Other deprecated methods:

  • DisplayHistory (utils.js)

To check / do after upgrading

Caselogs ordering

The selected caselog when opening/editing an object is always the first one. We have changed the datamodel to reflect this, but if you have overwritten the XML presentation of the UserRequest or the Incident classes, you won't get our fix, and most probably you will have to reorder the caselogs this way:

itop_design / classes / class@UserRequest / presentation / details
          <items>
            <item id="public_log">
              <rank>100</rank>
            </item>
            <item id="private_log">
              <rank>110</rank>
            </item>  
          </items>

The same applies to the presentation of the Incident class.

If you have access to the ITSM Designer, check the details presentation and add the caselogs to it, in the desired order.

Extensions

FIXME

Put the list of extensions that need to be updated AFTER the upgrade if necessary. Typically extensions that would not be compatible with the previous version.

3_0_0/install/270_to_300_migration_notes.txt · Last modified: 2021/07/06 15:44 (external edit)
Back to top
Contact us