The version 3.0.0 of iTop is roughly backward compatible with previous 2.x versions, except extensions bringing specific displayed pages.

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.0 Beta version

In the 3.0.3 release, the functions get_config_parameter() and get_module_setting() are no more available in Twig files (portal or console)

This version has a major impact on users habits. Check the What's new document for all the changes impacting the ways things used to be done in the past and how they should be done in 3.0.

• Change on WorkOrder behavior: 'ticket' and 'end date' are now optional, 'end date' if empty is set automatically on closure.
• Change on object edition: Form buttons (validation, transitions, cancel) can no longer be displayed at the bottom of the object's form; they are always at top-right.
• Transitions without prompted fields are no more displayed, the transition is executed without confirmation. To force the user confirmation just alter in XML the lifecycle to set at least one field in must_prompt on the transition. As before, an empty mandatory field, is automatically prompted, even without an explicit flag must_prompt.
• Object history is displayed differently than before, new activity_panel.xxx parameters allow to switch back to previous behavior
• Standard class icons have been changed in 3.0 and cannot be restored to the old icons which are no more included in iTop package, apart from manually loading them again through an extension or one by one in the ITSM Designer. Icons on classes that you have created, will have an icon which may not be in the new iTop style.
• Change on external keys autocomplete: Max. number of displayed results now uses the max_autocomplete_results configuration parameter in both the backoffice and the end-users portal where it was previously hardcoded to respectively 150 and 20 items.

• On Setup (new installation or version upgrade), a set of OQL queries usable in Notifications are automatically loaded.
• Queries label and description are in iTop default language, when translation exist (EN US, FR FR and DE DE)

• There is a new “node_modules” folder under the iTop root folder. Mind to update your migration / backup scripts if necessary.
• A new log was added to allow module developers to track calls to iTop core deprecated files of PHP methods. See What's new : Log calls to deprecated files / PHP methods.

We have added a field user_id in table CMDBChange to identify users who made the change.

• In the past we were just keeping the person friendlyname, so we were exposed to name changes and homonyms.
• Of course previously created entries in the Change History, will not contain information in that new field.
• This table can be big, so the migration can take time: with 937 000 lines of priv_change, it took 5 sec to add user_id to the table during upgrade setup.

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

Check for each of your Combodo extensions the 3.0 compatible version that you need to install, before upgrading.
Be cautious, the 3.0 compatible version may not be available yet, also the version number is already known.

Those features are now included in iTop 3.0 so in general no more needed as additional standalone extensions

If you have customized a theme in XML, you must change it to follow the new 3.0 standard: Theme Customization, especially imports>import>xsi:type 2.7 theme customization variables are probably obsolete, see above page to migrate your theme.

If you have created a new theme from scratch in XML, then

1. you must remove that theme, before upgrading to iTop 3.0 as none of the 2.7.x variables are available in 3.0.
2. Rewrite the theme to make it 3.0 compliant (see below the mandatory line to add) then add it back to your iTop 3.0

itop_design | branding | themes | theme@MyNewTheme

        <stylesheets>
          <stylesheet id="fullmoon" _delta="define">../css/backoffice/main.scss</stylesheet>
        </stylesheets>

The dependencies node of the manager_id has been removed as there was no usage of org_id in the default OQL filter. It's probably from a time where Manager was limited to the organization of the Person. If you removed or redefined it, you will need to adapt your XML.

Datamodel in iTop 2.7 and older

<itop_design>
  <classes>
    <class id="Person">
      <fields>
        <field id="manager_id"xsi:type="AttributeExternalKey">
          <filter><![CDATA[SELECT Person]]></filter>
          <dependencies>
            <attribute id="org_id"/>
          </dependencies>
        </field>
      </properties>
    </class>
  </classes>
</itop_design>

If you have a Combodo Product or installed Mail to Ticket Automation: check that Users which must be able to access the Mailbox, can still do it, and if not change their Profile(s)

class:MailInboxBase and class:EmailReplica are now by default not visible to non-administrator, unless explicitly granted with read access, through a profile (internally, category was changed from bizmodel to grant_by_profile).

This was an old and unused feature from iTop 2.0 which we decided to completely remove during the backoffice rework. It means that if you used the `display_template` property of a (PHP or XML) class to display its form differently, it won't work anymore in iTop 3.0, the standard form will be displayed instead.

To ease the migration, the application will upgrade safely if the property is still present in the XML / PHP (it will be silently ignored). Even though it is not mandatory for the migration, we recommend that you remove any usage of this feature.

Example of customization in an XML class in iTop 2.7 and older

<itop_design>
  <classes>
    <class id="UserRequest">
      <properties>
        <display_template _delta="redefine">my-module/my-template.html</display_template>
      </properties>
    </class>
  </classes>
</itop_design>

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

When you change the allowed values of an enum through an iTop extension while you have objects in your iTop instance which still used the old values, the Setup used to fail, with a Fatal Error.

But it is no more the case, because the database allowed values for the enum, is the union of the datamodel values and the values in use when the last Setup was performed. So as long as a value is in use, even if not in the datamodel defined values, it will be kept in database.

In the iTop User Interface,

• when viewing an object using a no more valid value for an enum, that value label will be correctly displayed.
• when editing that object, the invalid value is removed and only datamodel allowed values are proposed,
  • so if the field is mandatory, the user will have to select a value.
  • if it's not mandatory, it will be emptied, and the user will probably not notice it.
• when updating by CSV or REST, other fields of that object, this will be transparent and the invalid value will be kept.
• The Database integrity tool will reports those objects having an invalid value on one of their enum

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

• buttons_position: Object form buttons are now always at the top of it.

We removed a bunch of images from iTop, if you used them you'll need to replace them with their new SVG equivalent which are in the same folder.

  datamodels/2.x/
             itop-attachments/icons/
                                   doc.png
                                   document.png
                                   html.png
                                   image.png
                                   movie.png
                                   odb.png
                                   odg.png
                                   odp.png
                                   ods.png
                                   odt.png
                                   one.png
                                   pdf.png
                                   ppt.png
                                   txt.png
                                   xls.png
                                   zip.png

Some of the images included in the datamodel's modules have been replaced with new SVG files which:

• Scale better no matter the size
• Weight lighter
• Match better with the new UI

Most of them can be found images/icons. Icons specific to a class state can be found in the corresponding module's images folder.

The old PNG files are still present to ease the migration but will be removed in the next version.

  datamodels/2.x/
      itop-change-mgmt/images/*.png
      itop-change-mgmt-itil/images/*.png
      itop-config-mgmt-itil/images/*.png
      itop-datacenter-mgmt/images/*.png
      itop-endusers-devices/images/*.png
      itop-faq-light/images/*.png
      itop-incident-mgmt-itil/images/*.png
      itop-knownerror-mgmt/images/*.png
      itop-problem-mgmt/images/*.png
      itop-request-mgmt/images/*.png
      itop-request-mgmt-itil/images/*.png
      itop-service-mgmt/images/*.png
      itop-service-mgmt-provider/images/*.png
      itop-storage-mgmt/images/*.png
      itop-structure/images/*.png
      itop-tickets/images/*.png
      itop-virtualization-mgmt/images/*.png
      itop-welcome-itil/images/*.png
      

Example of Setup error after an upgrade:
“Failed to process class 'Server', from '/my-itop/datamodels/2.x/itop-config-mgmt': Field: 'save_flag', (type: AttributeEnum), missing (or empty) mandatory tag 'code' under the tag 'value'

Root cause, html tag id in 3.0 are not allowed to be empty as well as tag value cannot be empty

XML:1.7 itop_design / classes / class@Server / fields

  <field id="save_flag" _delta="define">
    <values>
      <value id=""/>
      <value id="n">n</value>
    </values>

to replace by

XML:1.7 itop_design / classes / class@Server / fields

  <field id="save_flag" _delta="define">
    <values>
      <value id=" "> </value>
      <value id="n">n</value>
    </values>

/fields_semantic at line 1110 could not be added : already exists in /itop_design/classes/class[cmdbAbstractObject]/class[Location]/properties/fields_semantic at line 205

Workaround, add this to the XML class redeclaration

XML:1.7 itop_design / classes

  <class id="Change" _created_in="itop-change-mgmt-itil" _delta="must_exist">
    <properties>
       <fields_semantic _delta="redefine">
         <state_attribute>change_status</state_attribute>
       </fields_semantic>
    </properties>

The triggers are now called AFTER the database update (instead of before). The requests used to filter the triggers will behave differently than in iTop 2.7, if one of the Target fields is used in the where condition of the OQL Filter.

Before the migration to 3.0, the current object was not yet saved in Database with its new values, so the filter was written to include the current object based on its previous values.

Example, where the field “priority” is used in the WHERE clause of the Filter and is part of the Target fields:

On such Trigger, the Filter must be changed, because it won't be triggered in the same situation as before migration.

In the console (backoffice):

• the main rectangle logo has since 3.0 a new optimal size of 310×70 pixels. If it is different, the browser will shrink/expend it, which could lead to an unclean effect.
• There is a new compact logo, displayed in the console when the menu bar is collapsed.

Here is how you can customize the logos.

You have created your new MenuGroup, you may want to set an icon. For Combodo's customer, this can be done in the ITSM Designer

You have created your own class, you may want to change the icon. For Combodo's customer, this can be done in the ITSM Designer

You have modified the possible values for User Request status and priority, you may want to highlight status for the new status (and the standard ones). For Combodo's customer, this can be done in the ITSM Designer.

The selected caselog when opening/editing an object is always the first one. We have changed the datamodel to reflect this, but if you have overwritten the XML presentation of the UserRequest or the Incident classes, you won't get our fix, and most probably you will have to reorder the caselogs this way:

itop_design / classes / class@UserRequest / presentation / details

            <!-- [...]-->
            <item id="col:col2">
              <items>
                <item id="fieldset:Ticket:relation">
                  <items>
                    <item id="parent_request_id">
                      <rank>10</rank>
                    </item>
                <!-- [...]-->
              </items>
              <rank>30</rank>
            </item>
            <item id="public_log">
              <rank>34</rank>
            </item>
            <item id="private_log">
              <rank>38</rank>
            </item>
            <item id="functionalcis_list">
              <rank>40</rank>
            </item>
            <item id="contacts_list">
              <rank>50</rank>
            </item>
            <!-- [...]-->

The same applies to the presentation of the Incident class.

If you have access to the ITSM Designer, check the details presentation and add the caselogs to it, in the desired order.

With the new activity panel came a few parameters to tune it:

• The history timestamps are relative when recent and absolute above a specified delay, which can be configured for your iTop.
• Set it to 0 the parameter activity_panel.datetimes_reformat_limit to go back to previous absolute format for every entries.
• The parameter activity_panel.show_author_name_below_entries allows to display the name of the author below the date. Otherwise, a tooltip over the user icon displays their name as well.
• Configure on mention parameter and triggers which allow to notify persons within caselog. It is configured by default, but you can change the rules and messages…
• You can expend this autocomplete of an object friendlyname within a log edition, to other classes than Person; for this you will have to assign a specific character for each class, with the Configuration parameter mentions.allowed_classes. You may create a Trigger to limit the proposed objects, but you aren't forced to define a notification for each trigger.

Since the introduction of the activity panel in the backoffice, the origin of the CMDBChanges (history entries) are now displayed when it wasn't done in a classic form in the GUI (eg. Webservices, email processing, custom extension, CSV import, …)

In iTop 2.7 and older, the origin of the CMDBChanges made through the CSV import in the backoffice were marked as “interactive” when they should actually be marked “csv-interactive”. This has been fixed in iTop 3.0 but only for the CMDBChanges made AFTER the migration, meaning that the old history entries made via the CSV import page won't appear like it.

Unfortunately there is no easy way to correct the previous entries on the DB.

In iTop 2.7 and older, the origin of the CMDBChanges made through the “Mail to ticket automation” extension were marked as “custom-extension” when they should actually be marked “email-processing”. This has been fixed in iTop 3.0 but only for the CMDBChanges made AFTER the migration, meaning that the old history entries made via the extension won't appear like it.

If you would like to the previous entries in the DB, you can run the following query, but keep in mind that it can take a very long time as this table is one of the most important in the DB.

UPDATE <DB_SHEMA>.<DB_TABLE_PRFIX>priv_change 
  SET origin = 'email-processing' 
  WHERE userinfo = 'Mail to ticket automation (background process)';

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.

Before downgrading from 3.0.0 to a 2.7 iTop version

• Delete TriggerOnMention objects if you have iTop access. Otherwise run 4 SQL queries to clean them

Rollback 3.0 upgrade

MariaDB [demo]> DELETE priv_link_action_trigger FROM priv_link_action_trigger 
                LEFT JOIN priv_trigger ON priv_link_action_trigger.trigger_id=priv_trigger.id 
                WHERE priv_trigger.realclass='TriggerOnObjectMention';
 
MariaDB [demo]> DELETE priv_trigger, priv_trigger_onobjmention FROM priv_trigger 
                INNER JOIN priv_trigger_onobjmention ON priv_trigger.id=priv_trigger_onobjmention.id;

• Downgrade the package
• Delete of priv_module_install 3.0

Rollback 3.0 upgrade

MariaDB [demo]> DELETE FROM priv_module_install WHERE name='datamodel' AND version LIKE '3.0%';

• Run Setup