:: Version 3.1.0 ::

3.0.x to 3.1.0 Migration Notes

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

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

Impact on Users

The 3.1 version of iTop has a small impact on user habits, as it does not change 3.0 behavior, but it greatly improved the user experience, by simplifying access to the information as well as the edition of relationships.

To check before upgrading


PHP version

  • New PHP min version: 7.4.0
  • New PHP max version: 8.1.x

PHP extensions

The following PHP extensions are now mandatory:

  • cURL

MySQL / Maria DB version

  • New MariaDB min version: 10.3.7
  • MySQL min version remains the same (5.7)


New column in tables with BLOB columns

With N°2889 - Add counter & triggers on file attributes / attachments downloads a new downloads_count column is added for file attributes of the datamodel, which in the standard datamodel means Attachment:contents, DocumentFile:file and Person:picture.

Adding these columns should not increase the setup time even on large databases unless you match one of the following:


  • Running MySQL 5.6 or older, which is not supported
  • Having changed the default value of the ''ALGORITHM'' parameter.
    • If you changed it to ALGORITHM=INPLACE it will be OK, this is preferred (and default) value to avoid impact when adding columns in tables with BLOBs.
    • If you changed it to ALGORITHM=COPY, the setup will run OK but it could take a long time to complete depending on your DB size.

For MariaDB

  • Running MariaDB older than 10.3.7; which is not supported
  • Having changed the default value of the ''ALGORITHM'' parameter.
    • If you changed it to ALGORITHM=INPLACE it will be OK, this is preferred (and default) value to avoid impact when adding columns in tables with BLOBs.
    • If you changed it to ALGORITHM=COPY, the setup will run OK but it could take a long time to complete depending on your DB size.

Custom code / extension

If you have developed custom extensions with XML and custom code, check: Developer check-list

Extensions to upgrade

Check for each of your Combodo extensions the 3.1 compatible version that you need to install, before upgrading.

The 3.1 compatible versions are available for Combodo's customers.
They will be released by October 2023, on iTop Hub.

Included in iTop

New modules includes in iTop Community and iTop Products

XML Datamodel

Because of the new possibility of relationship creation, the control of duplicates is no more ensured, so you should create a uniqueness rule on all the n:n relationships that you have created, on which duplicates are not expected to be created.

For each of the relationship that you have created

  • Create a uniqueness rule on both external keys of the relation
    • If you set the rule id=“no_duplicate”, then the generic error should do the job and you don't have to create them
    • Replace key1_id and key2_id in the XML below with the relationship key codes
itop-design / classes / class@MyClassLink / properties
          <rule id="no_duplicate">
              <attribute id="key1_id"/>
              <attribute id="key2_id"/>
  • Check how you have identify the relationship
    • Rather than using key1_id and key2_id it's more user friendly to use External Field such as key1name and key2name or key1_id_friendlyname which is less efficient when used on key such as functionalci_friendlyname as this generate a lot of joins with each of the FunctionalCI sub-classes and sometimes exceeds the 61 joined tables limit of a MySQL query
  • You can force the relationship friendlyname format with an single EN US dictionary entry (no translation in other language required in general)
  'class:MyClassLink/Name' => '%1$s / %2$s', 

For Combodo's customers Designer Power User can do this in the ITSM Designer.

New attribute on Organization class

A new logo attribute is now present on the Organization class, this is mostly used to display a different branding logo on the end-users portal depending on the connected user.

  • logo is an AttributeImage append at the end of the details zlist
  • If you have customized the display of an Organization, then you will need to add it manually, if you want to use it.


  • Field customercontracts_list was changed from AttributeLinkedSetIndirect to AttributeLinkedSet and is no more editable from the SLA site
  • Remove useless CheckToWrite method on SLA class. It was used to avoid duplicates, but the relationship is now read only from that side.

covered by Migration Audit 107

  • Default search criterion where defined for classes SLA and SLT, there was none before

covered by Migration Audit 106

  • Add a field slas_list on SLT class and display, to see the SLAs using a particular SLT.

covered by Migration Audit 105

Rank on enum

Enumeration attributes can specify how to order its values (XML tag sort_type):

  • code or not provided: the order of an enum is using the alphabetical order of the values codes (behavior before iTop 3.1.0)
  • label: the order is the alphabetical order of the labels, so it's language dependent.
  • rank: the order relies on an explicit rank on each value, values with no rank defined are at the end in alphabetical order of their codes

If you have

  • added states to Ticket lifecycle,
  • added values to standard enumeration attributes
  • created new enumeration attributes

Then you can use/set those new XML tags to force the display order of enumeration attribute.

When is this order used or not?

  • Used: when editing an enumeration of an object using drop-down list, then values are displayed using the defined order.
  • Used: in dashlet headerstatistics, selected values are displayed using the defined order (XML provided order is now ignored).
  • Used: in transitions actions and buttons ordering (see below)
  • Not used: when setting a search criterion on an enumeration attribute, the proposed values are always in alphabetical order of the labels.

Standard ranking

All enumeration attributes with more than 3 values within the standard iTop datamodel have been changed with a sort_type to order their values

  • UserRequest, Incident, Problem, Change - status: rank
  • UserRequest, Incident, Problem - origin: label
  • UserRequest, Incident, Problem - resolution_code: label
  • Change - category: label
  • Service - status: rank
  • ServiceSubcategory - status: rank
  • Contract - status: rank
  • FunctionalCI - business_criticity : rank
  • Document - status: rank
  • PhysicalDevice - status:rank
  • Software - type: label
  • Model - type: label
  • Group - status: rank
  • VirtualDevice - status: rank
  • KnownError - domain : label

Values renamed

Because some values started with capital letter and other low letter, label ordering was not correct. To fix this we have changed values of the above enumerations attributes in EN and FR language with capital letter.

  • UserRequest, Incident, Problem - origin, impact, urgency, priority

FR status > état

For historical reason status was wrongly translate in french into “statut” while the correct word is “état”. This was changed on all standard classes

Import, Export and treatments can be impacted by those renaming!

Order transitions

Transitions order is visible on object with lifecycle and transitions available from its current state.

  • In read mode, it's the order of the drop-down transitions menus
  • In edit mode, it's the order of the transitions buttons

Now you can choose between 4 itop global options using a configuration parameter lifecycle.transitions_sort_type

  • alphabetical: alphabetical order of the transition labels
  • fixed: transitions are ordered based on the rank of their arrival state
  • relative default: transitions are ordered based on the rank of their arrival state, but taking into account the rank of the current state
    • it proposes first the transition going to a state with a rank equal or superior to the current state rank, considered as logical future states
    • then it proposes those going to a state with a rank strictly below current state rank, considered as past states, less logical/frequent than going forward
  • xml: the old logic, also we are not sure that it will be exactly the same in all cases.
States = 1:New, 2:Dispatch, 3:Assign, 4:Resolve, 5:Close
Using relative transition_sort_type, transitions order are the following by state:
  • New: Dispatch, Assign, Resolve, Close
  • Dispatch: Re-dispatch, Assign, Resolve, Close
  • Assign: Re-assign, Resolve, Close, Re-dispatch
  • Resolved: Close, Re-open

Transitions order before 3.1 was the order of XML declaration, something which was impossible to control.


  • Add an org_id field on those 5 classes: PhysicalInterface, LogicalInterface, FiberChannelInterface, LogicalVolume, NASFileSystem
  • Add a location_id field on PhysicalInterface, FiberChannelInterface, LogicalVolume & NASFileSystem

Those are external fields from another object.

covered by Migration Audit 165

Service & Contract

  • ServiceFamily menu was added

Not covered by any Migration Audit

  • Services tab was added on Provider Contract details
  • status added to default search criterion of Contract abstract class

covered by Migration Audit 170

  • Provider and Customer Contract display changed with fieldset, if you have customized them on top, you won't see those changes

covered by Migration Audit 169

Other changes

  • New reserved XML tag “edit_mode” on AttributeLinkedSetIndirect
  • New reserved XML tag “with_php_constraint” on AttributeLinkedSetIndirect

They should be used by iTop 3.1.1


Unattented install

Before running unattended installation you have to list the “additional modules to select” inside the XML file provided to the unattended_install.php script.

Additionnal XML configuration for unattended installation
<?xml version="1.0" encoding="UTF-8"?>
    <selected_modules type="array">

For more information regarding unattended installation: https://wiki.combodo.com/doku.php?id=latest:advancedtopics:automatic_install&s[]=unattended#unattended_installat

Configuration file

Breaking changes

As we had to change the mailing library to Laminas, we have to cope with its limitation:

email_transport_smtp.host no more supports IP address, you must provide an FQDN


Below is a list of the deprecated configuration parameters, this mean that they will no longer have any effect in the application.


To check / do after upgrading

Improve users productivity

X-Content-Type-Options HTTP header and CORB protection

Since iTop 2.7.10 / 3.0.4 / 3.1.2 / 3.2.0, the X-Content-Type-Options HTTP header is sent with the nosniff value. This could trigger CORB protection for certain resources, preventing them from loading (see https://chromium.googlesource.com/chromium/src/+/master/services/network/cross_origin_read_blocking_explainer.md#determining-whether-a-response-is-corb_protected).

To mitigate the issue, sending this HTTP header is disabled on corresponding resources in iTop core.
As some extensions can be impacted, the security.enable_header_xcontent_type_options config parameter can be set to false to prevent the header to be sent.


Nothing special to downgrade from 3.1.0 to a 3.0 iTop version

  • Downgrade the package
  • Run Setup
3_1_0/install/migration_notes.txt · Last modified: 2024/01/05 12:13 (external edit)
Back to top
Contact us