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.

• For a focus on new features check What's New
• For an exhaustive list of changes check the Change Log
• For the list of Known Issues in 3.1 Beta version
• Combodo 3.1 compatible extensions versions

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.

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

The following PHP extensions are now mandatory:

• cURL

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

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:

For MySQL

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

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

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

New modules includes in iTop Community and iTop Products

• Password Expiration Enforcement
• User authentication by token

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

        <uniqueness_rules>
          <rule id="no_duplicate">
            <attributes>
              <attribute id="key1_id"/>
              <attribute id="key2_id"/>
            </attributes>
            <filter><![CDATA[]]></filter>
            <disabled>false</disabled>
            <is_blocking>true</is_blocking>
          </rule>
        </uniqueness_rules>

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

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

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.

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

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

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

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

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.

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

• 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

• 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

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"?>
<installation>
    <selected_modules type="array">
        <item>itop-structure</item>
        <item>itop-bridge-cmdb-ticket</item>
        ...
    </selected_modules>
        ...
</installation>

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

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.

email_transport_smtp.allow_self_signed

• Add summary and Complementary name on your own objects
• Add rank on your own enumerations attributes
• Order objects transitions

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