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

Consider browsing to iTop 3.2 documentation

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.

To check before upgrading

New PHP and MySQL requirements

Requirement for MySQL and PHP have changed:
  • 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
When migrating to MySQL 5.6 and above, there is now by default a STRICT_MODE which prevents for example value such as 0000-00-00 to be used as a valid date. You will have to bulk modify your data for this.
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:

  1. CSV or excel export the values (in clear text) contained in those attributes.
  2. upgrade your system de PHP7.2 (which does not support mcrypt)
  3. 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 MySQL 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
If your databases are strictly identical, you can reuse the SQL queries logged while migrating your test machine and stored in /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.

If you have created indexes directly in MySQL, be aware that they will be deleted by the upgrade to 2.5.0

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 using REST web services have that profile.

Even the Administrator profile does not have access by default to REST webservices without that profile
If you want to keep the previous behavior (i.e. allow any user to access REST web services), then add the Configuration parameter secure_rest_services and set it to false.

Datamodel changes

Search default criterion

If you have customize your datamodel and created new classes from scratch, then you will need to specify default search criterion. Those default search 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.

Resistance to change on the New Search, can be reduced by displaying useful criterion, so set them carefully on your own classes.
The default search on Ticket ref is 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 criteria on Ticket class, by default.

You may define one again if you want but remember that any criteria based on a date function, invalidate the query caching mechanism and affect badly performance.

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.


The Phone and 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' => '#',
To guarantee that phone numbers with invalid format, will not prevent Person object modification, look for them with an audit

Adding Services, Contacts and Documents to a Contract

Form 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:

  • Services are now those from the Provider (and no more the Customer)
  • Contacts and Documents are those belonging to the Customer or the Provider

Portal changes

  • By default on Ongoing and Closed requests, portal users can now export in excel their User Requests limited to the fields which they can see on the screen.
  • The Ongoing requests has 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:

  • email_default_sender_address
  • email_default_sender_label

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.

After migration

If you have created your own classes, define /presentation/defaut_search with the default search criterion on those classes.

For Developers

Improve performance

With 2.5.0 there is a new method CountExceeds($iLimit) on class DBOjectSet which for some purpose is much more efficient than Count().

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.

2_5_0/install/240_to_250_migration_notes.txt · Last modified: 2023/03/15 11:31 (external edit)
Back to top
Contact us