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
3.0.x to 3.0.3 Migration Notes
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)
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_prompt
on the transition. As before, an empty mandatory field, is automatically prompted, even without an explicit flagmust_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.
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 (
EN US
,FR FR
andDE DE
)
To check before upgrading
If you have custom extension(s), read how to migrate an extension to 3.0
System
-
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.
Database
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 adduser_id
to the table during upgrade setup.
Extensions
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
Extension | Comment |
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
global_search.enabled so included in iTop Community
3.0 |
Multiple LDAP | Module included in iTop Community 3.0 |
XML Datamodel
Custom theme
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
-
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>
Person
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>
Mailbox access
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
).
display templates
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>
Setup
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"?> <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.
-
The
Database integrity
tool will reports those objects having an invalid value on one of their enum
-
Changing Ticket criticality from
low,medium,high
into1-high,2-medium,3-low
to 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 -
Run the
Database integrity
menu to ensure you have completed the data migration
Configuration file
Deprecations
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.
Images
Breaking changes
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
Deprecations
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
During upgrading
Known error n°1
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>
Known error n°2
/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>
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 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.
Filter
on your Trigger On Object
Update
if it uses a condition on an updated
fieldExample, 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.
Branding
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
Class Icon
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.
Caselogs ordering
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.
Activity panel
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.
CMDBChange origins
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_SCHEMA>
and
<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)';
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.
Downgrade
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