2.4.x to 2.5.0 Migration Notes
The version 2.5.0 of iTop is fully backward compatible with the previous 2.x versions (2.4.2, 2.4.1, 2.4.0, 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.
For a focus on new features check iTop 2.5 Community
For an exhaustive list of changes check the Change Log
To check before upgrading
Meta tag for Designer
For Combodo customers which do have a tag <meta> in their XML (ask Combodo, if you have a doubt), that tag has been added to the Standard Datamodel. As a result, the _delta=“define” in your delta XML must be replaced by _delta=“must_exist”. Combodo must do it for you.
New PHP and MySQL requirements
Minimum PHP 5.6, recommended PHP 7.1 (PHP 7.2 is also supported)
Minimum MySQL 5.5.3 (or MariaDB 5.5), recommended MySQL 5.7
Here an example with a Date-time bulk SQL update:
UPDATE IGNORE MyClass SET date_field = NULL WHERE MyClass.date_field = '0000-00-00 00:00:00'
Those requirements are listed in the Installation Guide
you have defined in your datamodel attributes of type AttributeEncryptedString (There is none in iTop Standard)
and you are using mcrypt
and you want to upgrade to a PHP7.2,
Then be aware that before upgrading you must:
CSV or excel export the values (in clear text) contained in those attributes.
upgrade your system de PHP7.2 (which does not support mcrypt)
CSV import again the values (without mcrypt their encoding will be different and not as strong)
New DB charset and collation
In order to be able to use characters outside of the BMP, iTop now uses the utf8mb4 MySQL charset that was introduced in version 5.5.3.
During the migration processus, iTop will:
drop all varchar indexes with a max length > 95 chars
re-create varchar indexes defined in the datamodel with a max length of 95 chars.
This mean that:
At migration, setup will take extra time in order to create the new indexes
on huge databases, this could take several minutes.
It is recommended that you use a testing environment in order to know the duration.
in most case this should end in greater performance for queries using those shorter indexes.
if you had created extra indexes “by hand” they may be lost each time you run the setup
the solution is obviously to define your indexes in the datamodel
/log/setup-queries-xxxxxxx.sql, to migrate the production database independently before migrating to 2.5.
More technical details: Oldest MySQL version have trouble managing indexes on columns varchar in utf8mb4: automatic index would be greater than the maximum allowed (4*255 +2 which is greater than the support index size: 767 bytes). To prevent this, iTop will now force a max length for indexes on varchar columns. This max length is 95 chars.
REST Web services
The access to the REST web services is now restricted to the
users having the profile REST Services
User (having the Administrator profile is not enough
to access the REST Web services, you must have also the REST
Services User profile).
Make sure that your scripts call REST web services with a user having that profile.
Administratorprofile don't have access by default to REST webservices without
REST Services Userprofile
secure_rest_servicesand set it to
Backup parameter change
check_backup.phpwith this parameter
check_ticket_itop, it will break!
For security reasons, the “check_ticket_itop” parameter should not be used anymore.
This URL must now be stored in the module parameters, in the config file, under the “itop_root” key.
In iTop 2.5.2 there was a param
itop_rootwhich is now
Remove the param
check_ticket_itopfrom the “param file” used in your cron when calling
and put the value previously located in
check_ticket_itop, into the Configuration file
Warning : the parameter
itop_rootis renamed “itop_backup_incident” starting from 2.6.0.
Search default criterion
If you have customize your datamodel and created new classes
from scratch, then you will need to specify
search criterion. Those
criterion are inherited from parent classes if not defined at the
child class level.
For standard classes, default
search fields have been defined. Ensure that those fields have
not been removed from your own datamodel, otherwise redefined this
part of the
presentation in the XML.
refis now checking an exact match (equal and no more contains). This change improve greatly performance on large database (> 50K Tickets). Nevertheless, you may restore the previous behavior by removing the index defined in XML on this field.
Index on Ticket ref
A datamodel defined index was added on Ticket
ref, if you have already done so in a customization of
your datamodel, remove it before upgrading, or Setup will fail with
this error message:
Failed to issue SQL query: query = ALTER TABLE `ticket` ADD INDEX `ref` (`ref`), mysql_errno = 1061, mysql_error = Duplicate key name 'ref'
Remove obsolescence criteria on ticket
Because of performance issue we have removed the obsolescence
Ticket class, by default.
Search & performance
By default, the new search, automatically run the search each time a user set a search criteria. If you have some classes with large amount of data, this can be an issue, in that case you can disable the default behavior for one or multiples classes with a Configuration parameter:
'high_cardinality_classes' => array ( 0 => 'Contact', 1 => 'Person', 2 => 'UserRequest', ),
You can also instead, force this behavior for all classes at once, using this:
'search_manual_submit' => true, ),
In this example, for UserRequest, users must explicitly press the search icon to get the resulting list aligned with the set criterion. There is a warning message to remind users about this different behavior.
Mobile Phone of the
class Person were changed in the standard Datamodel to use the new
AttributePhoneNumber which allows smooth
integration with IP phone applications, such as Skype
Check the 3 new Configuration parameters to fine-tune the desired behavior.
|Parameter||Type||Visible ?||Description||Default Value|
|phone_number_validation_pattern||string||No||Regular expression to validate/detect the format of a phone number||[0-9.\-\ \+\(\)]+|
|phone_number_url_pattern||string||No||Format for phone number url, use %1$s as a placeholder for the value. eg. “tel:%1$s” for regular phone applications or “callto:%1$s” for Skype. Default is “tel:%1$s”||tel:%1$s|
|phone_number_decoration_class||string||No||CSS class(es) to use as decoration for the HTML rendering of the attribute. eg. “fa fa-phone” will put a phone icon||fa fa-phone|
If your users have no IP phone on their PCs, you can set this value to disable the link (but this will turn off click to call for every user).
'phone_number_url_pattern' => '#',
Adding Services, Contacts and Documents to a Contract
prefill feature was mainly developed to address the particular
issue of the
Contract class. Thanks to this we have
modified the default behavior of the search of
Contract related objects:
Servicesare now those from the Provider (and no more the Customer)
Documentsare those belonging to the Customer or the Provider
By default on
Closed requests, portal users can now export in excel their User Requests limited to the fields which they can see on the screen.
Ongoing requestshas been slightly changed in the way the tabs are displayed.
iTop detect columns removed from the datamodel but still present in database. Since it is hazardous to drop them, iTop only changes their table definition to make those columns nullable. This is still true, but, in addition, iTop's Toolkit will now suggest to remove them :
-- Recommended action: ALTER TABLE `Foo` DROP `Bar`";
This feature is brought by iTop core and so is available with Toolkit 2.3.
Default sender email
When the iTop sends email with no defined sender, it will pretends that the sender is the destination user. The drawback of such mechanism is that some email servers will drop those messages as spam. To workaround this, we have added 2 new parameters in the Configuration file:
This is the case when iTop sends a forgotten password, a test notification or an error report when synchro is failing.
Loosing in-line images
By default, if an object with attachment and/or inline images, is not saved within 1h, then the attachments and in-line images will be lost. That 1h delay was hardcoded and from 2.5.0 it is a Configuration parameter:
'draft_attachments_lifetime' => 3600,
It's useless to set less, as the garbage collector process which delete those temporary files is a Background task running hourly.
If you have created your own classes, define
/presentation/defaut_search with the default
search criterion on those classes.
With 2.5.0 there is a new method
CountExceeds($iLimit) on class
which for some purpose is much more efficient than
This method shall be used to check if the count of a set of object is higher than a parameter $iLimit. Check if the count exceeds a given limit without fetching the whole list of data from database. This is useful when the purpose of counting is just to know if we will display a drop-down list or an auto-complete form.