You are browsing the documentation for iTop 2.5 which is not the current version.

Consider browsing to iTop 3.2 documentation

2.3.x to 2.4.0 Migration Notes

The version 2.4.0 of iTop is fully backward compatible with the previous 2.x versions (2.3.4, 2.3.3, …, 2.2.1, 2.2.0, 2.1.0, 2.0.3, 2.0.2…), however this version introduces quite a few significative changes.

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

To check before upgrading


A new capability has been added to iTop core to improve search performance when your outdated data start to represent much more than the active ones.

It is not enabled by default on iTop. It has to be activated by a module.

More on Archiving


By default user preference have been set to not show obsolete data

Many objects will disappear from user screen and it may confuse them. If you want to minimize users' question on this, you can set your iTop to have a different default by adding a line in the Configuration file

   'obsolescence.show_obsolete_data' => true,
This version brings a set of default obsolescence criteria. If you have customized your datamodel, that may break during setup, if the below rule is broken:
Obsolescence criteria on a CI cannot depends on a parent class of the current CI

Example: changing DatabaseSchema dbserver_id from a DBServer ExternalKey to a FunctionalCI ExternalKey, because we want the server to be either a DBServer or ClusterServer, leads to an infinite loop in the DatabaseSchema obsolescence computation.

More on obsolescence

Overriden DisplayBareRelations method

If the DisplayBareRelations method is overriden to display tabs containing lists with counts, the counts will not be correct if the user does not display the obsolete data. In order to display a correct count, the DBObjectSet used for the count should be aware of the user choice on obsolescence display. To do so insert the following code snippet:


For example :

$oSet = new CMDBObjectSet(DBObjectSearch::FromOQL($sOQL));
// Add the obsolescence filter here
// End of patch
$iCount = $oSet->count();
if ($iCount > 0)
    $oPage->SetCurrentTab($sClassName." ($iCount)");
self::DisplaySet($oPage, $oSet);

Flags on transition

Standard Data Model of iTop 2.4 is using the new capability to define flags on transitions. Changes were made on class UserRequest (and Incident)

  • on a re-assign transition from assigned to assigned state, agent_id is required to be changed.
  • on an assigned state, the agent_id is read only.

portal: forms en transition

As part of the default Portal, the re-open transition now prompts the user to provide information in the Caselog. It's optional, as the user may have provided it already in the Ticket form before re-opening.

New Backup format

zip library for php is limited to 4Gb backup size.
As a result, if your iTop database backup file exceed 4Gb, you will never be able to restore your data as the generated backup file is unreadable. So to address this known issue, we have decided to switch to tar.gz format which has no size limitation. This means that you will have to install phar and zlib on your iTop server.

It seems to be part of php package on Windows and of php7 on Ubuntu 0.16.04. It can be a library to add or may require a new php version.

Your existing backup files smaller than 4Gb and using zip format, can still be restored by iTop. But new backup file will be generated with tar.gz by defaut.

Also note that \DBBackup::CreateZip is kept in the code but marked as deprecated. It will be removed in 2.7.0.

Legacy portal

Legacy portal is now deprecated and will be removed as of iTop 2.7.0.

Enhanced portal

User Profile Brick

Available from PHP 5.5.16 ONLY, you can hide parts of the form such as preferences, password and profile picture

New Search Brick


Some extensions providing new bricks or extending native bricks have been merged into iTop and are now obsolete. Using them in iTop 2.4 and above could result in a conflit. Here are the concerned extensions:

  • itop-portal-create-brick-extended
  • itop-portal-filter-brick



A new verb on DBObject is available. GetDefaultValue($sAttCode) is overridable and allows to change the default value of an attribute for an object. (One of its use case could be to set default values when creating a new object)


DBObject::Get on an attribute of type “link set” now returns an object of the class ormLinkSet whereas it used to return an object of class DBObjectSet.

DBObject::Set accepts either an object of class ormLinkSet (preferred!) or DBObjectSet (deprecated, but kept for backward compatibility).

Here is the supported (though deprecated) pattern:

$oCurrentSet = $oObject->Get('person_list');
$oNewSet = DBObjectSet::FromScratch('lnkSomeClassToPerson');
// Copy the current set
while ($oSomeLink = $oCurrentSet->Fetch())
        $oNewLink = MetaModel::NewObject('lnkSomeClassToPerson');
        $oNewLink->Set('name', $oSomeLink->Get('name'));
        $oNewLink->Set('firstname', $oSomeLink->Get('firstname'));
// Add an item
$oNewLink = MetaModel::NewObject('lnkSomeClassToPerson');
$oNewLink->Set('name', 'Doe');
$oNewLink->Set('firstname', 'John');
$oObject->Set('person_list', $oNewSet);

Here is the recommended (simpler and more efficient) pattern:

$oCurrentSet = $oObject->Get('person_list');
$oNewLink = MetaModel::NewObject('lnkSomeClassToPerson');
$oNewLink->Set('name', 'Doe');
$oNewLink->Set('firstname', 'John');
$oObject->Set('person_list', $oNewSet);


In iTop 2.4.x, UILinksWidget::Display and UILinksWidgetDirect::Display methods have not been updated according to the new ormLinkSet object, it only accepts DBObjectSet as $oValue parameter.

This means that you can use a ormLinkSet object (eg. from a DBObject::Get on a link set attribute like said on the previous point) directly, you have a convert it to the legacy DBObjectSet format. To do so, just use the ormLinkSet::ToDBObjectSet method.

Here is an example of a non working code:

// Prepare links widget
$oWidget = new UILinksWidget(...);
// Retrieve links
$oSet = $oObject->Get('person_list');
// Display widget
$oWidget->Display(..., $oSet, ...);

Here is the correction for the example above:

// Prepare links widget
$oWidget = new UILinksWidget(...);
// Retrieve links
$oSet = $oObject->Get('person_list');
$oLegacySet = $oSet->ToDBObjectSet(utils::ShowObsoleteData());
// Display widget
$oWidget->Display(..., $oLegacySet, ...);


An object can be archived before it is used by a module. As archiving is equivalent to a “soft deletion”, by default an archived object won't be returned by MetaModel::GetObject when archive mode is disabled. If it is enabled, then all archived objects are visible and there are no change to the previous behavior.

Here are the different behaviors depending on the $mustBeFound parameter values, when archive mode is disabled :

Object type $mustBeFound value return
Non archived object true object
Non archived object false object
Archived object true ArchivedObjectException
Archived object false null
Non existing object true CoreException
Non existing object false null
Before 2.4 the method was already throwing a CoreException. As ArchivedObjectException extends this object, then you don't have to modify your existing catch statements.
If you need to get the object even if it is archived, then you should use the new method MetaModel::GetObjectWithArchive.


DBBackup::CreateZip is deprecated (remains available for a while) in favor of DBBackup::CreateCompressedBackup which produces a tar.gz.

DBRestore::RestoreFromZip is deprecated (remains available for a while) in favor of DBRestore::RestoreFromCompressedFile (which autodetects the format for backward compatibility).

Details: keep existing value

When a field A (model) is dependent on a field B (brand) and there is a filter on A (SELECT Model WHERE brand=this→brand), when you edit the object:

  • if the existing value of A is not coherent with the filter and the B value, it is no more removed
This new behavior is on purpose. Exemple: Parent ticket was lost if the parent was closed and closed status is not allowed in the filter
  • if the field B is modified, A is reset as before


On 'resolved' ticket on Portal the caller can only Re-open or Close, no more modify by default


New parameters available in Configuration File, to prevent adding/removing attachment on closed ticket.

Data Synchro

Starting with version 2.3.4, the Replica Table created by a dataSynchro, use a VARCHAR(10) format instead of DATE for date columns.

This change was made to enable the possibility to empty a date column using synchro_import when MySQL setup does not accept 0000-00-00 date value.

In the Replica Table

  • a NULL value has the meaning Ignore this column so don't update the destination object.
  • an empty string means empty the destination object field (force a reset of a value),
  • a 0000-00-00 date value meant reset the date value, but this does not work with many MySQL setup (so we switch to string format)
2_5_0/install/230_to_240_migration_notes.txt · Last modified: 2020/04/06 18:04 (external edit)
Back to top
Contact us