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

  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

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

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.

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.

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.

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'

Because of performance issue we have removed the obsolescence criteria on Ticket class, by default.

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:

Configuration

    'high_cardinality_classes' => array (
      0 => 'Contact',
      1 => 'Person',
      2 => 'UserRequest',
    ),

You can also instead, force this behavior for all classes at once, using this:

Configuration

      '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.

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' => '#',

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

• 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.

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.

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:

Configuration

'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 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.