2.7.x to 3.0.0 Migration Notes
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
Impact on Users
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_prompton the transition. As before, an empty mandatory field, is automatically prompted, even without an explicit flag
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.
Notification & OQL queries
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 (
To check before upgrading
If you have custom extension(s), read how to migrate an extension to 3.0
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_idto the table during upgrade setup.
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.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.
Included in iTop
Those features are now included in iTop 3.0 so in general no more needed as additional standalone extensions
|Menu Finder||Function mirrored and included in iTop Community 3.0|
|Attributes visual beautifier||Feature provided in 3.0 for console only, extension still required on portal(s)|
|Attribute tooltip||Function mirrored and included in iTop Community 3.0|
|Bubble caselogs||Function mirrored and included in iTop Community 3.0|
|Disable Global Search||Function mirrored with a Configuration parameter
|Multiple LDAP||Module included in iTop Community 3.0|
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
If you have created a new theme from scratch in XML, then
you must remove that theme, before upgrading to iTop 3.0 as none of the 2.7.x variables are available in 3.0.
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>
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
- 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:EmailReplica are now by default not visible to
non-administrator, unless explicitly granted with read access,
through a profile (internally, category was changed from
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
- 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
Enum values modification
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.
Database integritytool will reports those objects having an invalid value on one of their enum
Changing Ticket criticality from
1-high,2-medium,3-lowto get a nice automatic order in list and dashlets
Define the same labels for both set of values
Change as well any methods using those values
Install your extension and run a Setup
CSV export your objects fields:
id (primary key)and the enum label
No mapping required if you defined the exact same labels, otherwise transform the old values into new values
CSV import the
id (primary key)and the enum label
Database integritymenu to ensure you have completed the data migration
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
Match better with the new UI
Most of them can be found
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
To check / do after upgrading
Trigger on object update
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
fields is used in the where condition of the OQL
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.
Trigger On Object Updateif it uses a condition on an updated field
Example, where the field “priority” is used in the WHERE clause
Filter and is part of the
On such Trigger, the
Filter must be changed,
because it won't be triggered in the same situation as before
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.
Menu Group icon
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
Ticket Status and Priority
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_limitto go back to previous absolute format for every entries.
activity_panel.show_author_name_below_entriesallows 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, …)
CSV import in the backoffice
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.
Mail to ticket automation
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.
<DB_TABLE_PREFIX>by the values used in your iTop configuration before running the query.
UPDATE <DB_SHEMA>.<DB_TABLE_PRFIX>priv_change SET origin = 'email-processing' WHERE userinfo = 'Mail to ticket automation (background process)';
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%';