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
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 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
-
/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 using REST web services have that
profile.
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.
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.
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:
- 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.
Click-to-call
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' => '#',
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
andDocuments
are those belonging to the Customer or the Provider
Portal changes
-
By default on
Ongoing
andClosed 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.
Toolkit
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:
- 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.
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.