You are browsing the documentation for iTop 2.3 which is not the current version.

Consider browsing to iTop 3.2 documentation

iTop 1.x to 2.0 migration instructions

Data migration versus iTop upgrade

iTop 2.0 ships with two data-models:

  • The 1.3 data model which is fully compatible with iTop 1.x. The only differences are a few bug fixes and the support of user-editable dashboards.
  • The 2.0 data model which uses quite different concepts and was designed to be cleaner and more modular, but not necessarily aligned with the 1.x data model.

When upgrading the application using the setup process of iTop, the data-model of a previous (non-customized) 1.x instance is automatically migrated to the 1.3 data-model.

The “core” engine of iTop is upgraded to the 2.0 codebase and provides all the enhancements and bug fixes of the new version (user configurable lists and dashboards, shortcuts, etc.)

A “data migration”, on the other hand, consists in transforming the data stored in the database using the iTop 1.x data-model into the new 2.0 data model. Since the two models are significantly different, this process cannot be completely automated.

Do I need to migrate my data to the 2.0 data-model?

If you are happy with the data model of iTop 1.2 and don’t plan to document pieces of your IT infrastructure that are only covered by the 2.0 data-model, you don’t need to “migrate” your data to 2.0.

You need to migrate your data only if you want to use (some part of) the new data-model of iTop 2.0. In all other cases you can rely on the automatic upgrade.

User configurable dashboards and customized 1.x data-models

This is a special case for those who customized their 1.x data model and want to benefit from user editable dashboards without migrating to the 2.0 data model.

When upgrading iTop, the setup compares the signature of all the data model files of the previous instance (located in the “modules” directory) with the signature of a corresponding 1.x genuine version. If any modification is detected in one of these files, the end-user is prompted whether or not to preserve the modifications. If the user answers to keep the modifications, then the whole “modules” folder will be used as the data-model definition. Otherwise a standard 1.3 model is used.

Since the User Editable dashboards are a special kind of Menu Node they are part of the data-model definition. You can benefit from the new feature by replacing the TemplateMenuNode instances by DashboardMenuNodes in your customized 1.x data-model.

  • On a development machine, install your customized 1.x iTop instance
  • Use the standard upgrade procedure to upgrade it with the 2.0 iTop package
  • When prompted to keep or discard your modifications, tell the setup to keep them
  • Install the 2.0 toolkit on this new instance of iTop
  • Edit the data model to add a new “empty” DasbhoardMenuNode menu item. Run the toolkit to apply your modifications
  • Use the interactive editor dashboard editor to design your dashboard, as any user would be when customizing her/his own dashboard
  • Save the customized dashboard using the menu “Export to file…”
  • Copy/paste the resulting XML in the definition of the DashboardMenuNode in your new data model.
  • Use the toolkit to apply the modifications.
  • Connect to iTop and select “Revert to Original Version…” to check that the customization is now part of your data model.
  • Remove the un-needed TemplateMenuNode from your data model
  • Upgrade your production instance with newly customized data model

Migration scenario overview

Be aware that the migration scenario supports neither the Tickets nor the Attachments yet!

Overall Migration Process

If you want to migrate your 1.x iTop instance to the new 2.0 data model, here is an overview of the process:

  • Upgrade your “old” iTop instance to 2.0. This will upgrade the data-model schema to 1.3 and bring to your iTop instance all the benefits of the code enhancements and bug fixes (especially in terms of data export capabilities).
  • On the same database server, but in a different database, install a brand new instance of iTop that will receive your migrated data with the desired combination of modules from the 2.0 data-model. Don’t install the “Demo” data on this instance.
  • Use the SQL script (see below) to transfer the Organizations, Documents, Contacts and User records from the old instance to the new instance. The SQL script will also create all the new Typology for you.
  • For the remaining classes: Servers, PCs, Network Devices, Services, Contracts, etc… use the CSV export and CSV import features to transfer the data in the order explained below.

Common migration pitfalls

Why is there no simple mapping between iTop 1.2.1 and iTop 2.0?

There are several cases where the two data models (1.x and 2.0) are significantly different and where a simple automated mapping is not possible. The major cases where such a manual intervention is required are listed below:

Split of classes

Some concepts were absent from the 1.x data model. For example in iTop 1.2.1 there was no such thing as a “Virtual Machine”. In many cases the Virtual Machines were just documented using the “Server” object. Now that the “Virtual Machine” object exists in iTop 2.0, migrating from the old data-model to the new one requires distinguishing between servers and virtual machines. The way to perform this “split” depends on the data you entered in iTop. You may be fortunate enough to have used a strict naming convention that distinguishes servers from VMs, in which case a simple sort/filter in Excel can do the trick. In other cases you may need to review the data one by one (either in Excel or by creating two groups in iTop for instance).

Typology

Some of the fields that were either closed enumerated lists or plain-text fields have been turned into configurable enumeration, grouped together under the “Typology” umbrella.

Example: Brand and Model.

The transformation of such fields is handled by the SQL script provided below. You may still need to review and cleanup the data for near duplicates like “Hewlett Packard”, “Hewlett-Packard” or, even worse, “HP”.

Limitations / no more supported features

A number of features were removed from the 2.0 data-model: either because there are other (better?) ways of documenting the same kind of information or because they were useless and too confusing in most cases. In such case, migrating to the standard 2.0 data-model will result in a loss of data.

Examples:

  • A Team can no longer be a member of another Team.
  • Locations are no longer in a hierarchy (there is no parent location anymore)

Duplicate names

If you have several objects of the same class that have the same name, be aware that the re-import of other objects that point to such “duplicates” can be challenging.

Different structure

The structure for documenting some information changed with the 2.0 data-model. In some cases there is no simple one to one mapping between the elements in 1.x and the elements in 2.x. for example, in 1.x the network connections were documented by connecting interfaces together. Since this was confusing (and hard to document) for most of the users, a simpler, direct relation between the devices was introduced in the 2.0 data-model. It is however possible to transfer the network topology between both models, but this requires some non-trivial processing of the data.

Order of operations

Once your two instances are ready for the migration, proceed as follows:

  • Download the SQL script below and use find/replace in your favorite text editor to ajust the names of the source and destination databases. The source database is named itop1x in the SQL below and the destination database is named itop20.
1x_to-20_migration.sql
/**
 * Organization
*/
TRUNCATE TABLE itop20.organization;
INSERT INTO itop20.organization (id, name, code, STATUS, parent_id, parent_id_left, parent_id_right)
  SELECT id, name, code, STATUS, parent_id, parent_id_left, parent_id_right FROM itop1x.organization;
 
 
/**
 * Typology
*/
TRUNCATE TABLE itop20.typology;
 
/**
 * Typology - DocumentType
*/
INSERT INTO itop20.typology (name, finalclass)
 SELECT DISTINCT TYPE, 'DocumentType' FROM itop1x.document WHERE TYPE IS NOT NULL;
 
TRUNCATE TABLE itop20.documenttype;
INSERT INTO itop20.documenttype (id)
 SELECT id FROM itop20.typology WHERE finalclass = 'DocumentType';
 
/**
 * Document
*/
TRUNCATE TABLE itop20.document;
/**
 * Document - DocumentFile
*/
INSERT INTO itop20.document (id, name, org_id, documenttype_id, description, STATUS, finalclass)
SELECT 
    SOURCE.id,
    SOURCE.name,
    SOURCE.org_id,
    typo.id,
    SOURCE.description,
    SOURCE.status,
    'DocumentFile'
FROM
    itop1x.document AS SOURCE
        LEFT JOIN
    itop20.typology AS typo ON SOURCE.type = typo.name
WHERE SOURCE.finalclass = 'FileDoc';
 
TRUNCATE TABLE itop20.documentfile;
INSERT INTO itop20.documentfile (id, file_data, file_mimetype, file_filename)
SELECT id, contents_data, contents_mimetype, contents_filename FROM itop1x.filedoc;
 
/**
 * Document - DocumentNote
*/
INSERT INTO itop20.document (id, name, org_id, documenttype_id, description, STATUS, finalclass)
SELECT 
    SOURCE.id,
    SOURCE.name,
    SOURCE.org_id,
    typo.id,
    SOURCE.description,
    SOURCE.status,
    'DocumentNote'
FROM
    itop1x.document AS SOURCE
        LEFT JOIN
    itop20.typology AS typo ON SOURCE.type = typo.name
WHERE SOURCE.finalclass = 'Note';
 
TRUNCATE TABLE itop20.documentnote;
INSERT INTO itop20.documentnote (id, text)
SELECT id, note FROM itop1x.note;
 
/**
 * Document - DocumentWeb
*/
INSERT INTO itop20.document (id, name, org_id, documenttype_id, description, STATUS, finalclass)
SELECT 
    SOURCE.id,
    SOURCE.name,
    SOURCE.org_id,
    typo.id,
    SOURCE.description,
    SOURCE.status,
    'DocumentWeb'
FROM
    itop1x.document AS SOURCE
        LEFT JOIN
    itop20.typology AS typo ON SOURCE.type = typo.name
WHERE SOURCE.finalclass = 'WebDoc';
 
TRUNCATE TABLE itop20.documentweb;
INSERT INTO itop20.documentweb (id, url)
SELECT id, url FROM itop1x.externaldoc;
 
/**
 * Location
*/
TRUNCATE TABLE itop20.location;
INSERT INTO itop20.location (name, STATUS, org_id, address, postal_code, city, country)
SELECT name, STATUS, org_id, address, postal_code, city, country FROM itop1x.location;
 
/**
 * Contact
*/
TRUNCATE TABLE itop20.contact;
 
/**
 * Contact - Person
*/
INSERT INTO itop20.contact (id, name, STATUS, org_id, email, phone, finalclass)
SELECT
    id, name, STATUS, org_id, email, phone, 'Person'
FROM
    itop1x.contact
WHERE finalclass = 'Person';
 
TRUNCATE TABLE itop20.person;
INSERT INTO itop20.person (id, first_name, employee_number, location_id)
SELECT p.id, p.first_name, p.employee_id, c.location_id FROM itop1x.person AS p JOIN itop1x.contact AS c ON c.id = p.id;
 
/**
 * Contact - Team
*/
INSERT INTO itop20.contact (id, name, STATUS, org_id, email, phone, finalclass)
SELECT
    id, name, STATUS, org_id, email, phone, 'Team'
FROM
    itop1x.contact
WHERE finalclass = 'Team';
 
TRUNCATE TABLE itop20.team;
INSERT INTO itop20.team (id)
SELECT id FROM itop1x.team;
 
/**
 * Person to Team
*/
INSERT INTO itop20.typology (name, finalclass)
 SELECT DISTINCT ROLE, 'ContactType' FROM itop1x.lnkteamtocontact WHERE ROLE !='';
 
TRUNCATE TABLE itop20.contacttype;
INSERT INTO itop20.contacttype (id)
 SELECT id FROM itop20.typology WHERE finalclass = 'ContactType';
 
TRUNCATE TABLE itop20.lnkpersontoteam;
INSERT INTO itop20.lnkpersontoteam (team_id, person_id, role_id)
 SELECT l.team_id, l.contact_id, t.id
 FROM itop1x.lnkteamtocontact AS l LEFT JOIN itop20.typology AS t ON l.ROLE = t.name;
 
/**
 * User management
*/
TRUNCATE TABLE itop20.priv_user;
INSERT INTO itop20.priv_user SELECT * FROM itop1x.priv_user;
TRUNCATE TABLE itop20.priv_internaluser;
INSERT INTO itop20.priv_internaluser SELECT * FROM itop1x.priv_internaluser;
TRUNCATE TABLE itop20.priv_user_local;
INSERT INTO itop20.priv_user_local SELECT * FROM itop1x.priv_user_local;
TRUNCATE TABLE itop20.priv_urp_userorg;
INSERT INTO itop20.priv_urp_userorg SELECT * FROM itop1x.priv_urp_userorg;
TRUNCATE TABLE itop20.priv_urp_profiles;
INSERT INTO itop20.priv_urp_profiles SELECT * FROM itop1x.priv_urp_profiles;
TRUNCATE TABLE itop20.priv_urp_userprofile;
INSERT INTO itop20.priv_urp_userprofile SELECT * FROM itop1x.priv_urp_userprofile;
  • Connect to the MySQL server and run the SQL script. This will import the Organizations, Documents, Contacts, Locations, Users and will create all the Typology (not yet all FIXME) objects in the new database.
  • Use the CSV export (either interactive or scripted) to export the following data from the “old” instance.
  • Use the CSV import (preferably scripted to avoid timeouts) on the new instance to import the data in the following order, and with the following field mapping:

Organization

Fields Mapping

Source Field Destination Field
name name
code code
status status
parent_id parent_id

Location

Fields Mapping

Source Field Destination Field
name name
status status
org_id org_id
address address
postal_code postal_code
city city
country country
Locations are not longer part of a hierarchy.

Person

Fields Mapping

Source Field Destination Field
name name
status status
org_id org_id
email email
phone phone
first_name first_name
employee_id employee_number
location_id location_id

Team

Fields Mapping

Source Field Destination Field
name name
status status
org_id org_id
email email
phone phone

DocumentNote

Fields Mapping

Source Field Destination Field
name name
org_id org_id
description description
status status
note text

DocumentWeb

Fields Mapping

Source Field Destination Field
name name
org_id org_id
description description
status status
url url

NetworkDevice

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance business_criticity
serial_number serialnumber
location_id location_id
status status
brand (*) brand_id
model (*) model_id
asset_ref asset_number
management_ip managementip
type (*) networkdevicetype_id
ios_version (*) iosversion_id
ram ram
SNMP read/write, default_gateway and location_details are no longer part of the standard model.

Server

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance business_criticity
serial_number serialnumber
location_id location_id
status status
brand (*) brand_id
model (*) model_id
asset_ref asset_number
management_ip managementip
os_family (*) osfamily_id
os_version (*) osversion_id
cpu cpu
ram ram

PC

Fields Mapping

Source Field Destination Field
name name
org_id org_id
importance business_criticity
serial_number serialnumber
status status
brand (*) brand_id
model (*) model_id
asset_ref asset_number
os_family (*) osfamily_id
os_version (*) osversion_id
cpu cpu
ram ram

Printer

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance business_criticity
serial_number serialnumber
location_id location_id
status status
brand (*) brand_id
model (*) model_id
asset_ref asset_number

MobilePhone

Fields Mapping

Source Field Destination Field
name name
org_id org_id
importance business_criticity
serial_number serialnumber
status status
brand (*) brand_id
model (*) model_id
asset_ref asset_number
number phonenumber
imei imei
hw_pin hw_pin

ApplicationSolution

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance business_criticity
status status

BusinessProcess

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance business_criticity
status status

DBServer

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance business_criticity
device_id system_id
software_id software_id
licence_id softwarelicence_id
status status

OtherSoftware

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance business_criticity
device_id system_id
software_id software_id
licence_id softwarelicence_id
status status

DatabaseSchema

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance business_criticity
db_server_instance_id dbserver_id

SoftwareLicence

Fields Mapping

Source Field Destination Field
name name
description description
org_id org_id
importance usage_limite
start_date start_date
end_date end_date
licence_key licence_key
usage_limit usage_limit

lnkContactToFunctionalCI

Fields Mapping

Source Field Destination Field
ci_id functionalci_id
contact_id contact_id
No more role in 2.0 version

lnkDocumentToFunctionalCI

Fields Mapping

Source Field Destination Field
ci_id functionalci_id
document_id document_id

Subnet

Fields Mapping

Source Field Destination Field
description description
org_id org_id
ip ip
ip_mask ip_mask

PhysicalInterface

Fields Mapping

Source Field Destination Field
name name
ip_address ipaddress
mac_address macaddress
serial_number comment
ip_mask ipmask
speed speed
device_id connectableci_id

lnkConnectableCIToNetworkDevice

Fields Mapping

Source Field Destination Field
source(if_dev)→device_id networkdevice_id
source(if_ci)→device_id connectableci_id
source(if_dev)→name network_port
source(if_ci)→name device_port
source(if_dev)→link_type connection_type

lnkApplicationSolutionToFunctionalCI

Fields Mapping

Source Field Destination Field
solution_id applicationsolution_id
ci_id functionalci_id

lnkApplicationSolutionToBusinessProcess

Fields Mapping

Source Field Destination Field
solution_id applicationsolution_id
process_id businessprocess_id

lnkPersonToTeam

Fields Mapping

Source Field Destination Field
team_id team_id
contact_id person_id

Group

Fields Mapping

Source Field Destination Field
name name
status status
org_id org_id
description description
type type
parent_id parent_id

lnkGroupToCI

Fields Mapping

Source Field Destination Field
group_id group_id
ci_id ci_id
reason reason

CustomerContract

Fields Mapping

Source Field Destination Field
name name
org_id org_id
description description
start_date start_date
end_date end_date
cost cost
cost_currency cost_currency
billing_frequency billing_frequency
cost_unit cost_unit
provider_id provider_id

ProviderContract

Fields Mapping

Source Field Destination Field
name name
org_id org_id
description description
start_date start_date
end_date end_date
cost cost
cost_currency cost_currency
billing_frequency billing_frequency
cost_unit cost_unit
provider_id provider_id
sla sla
coverage coverage

lnkContactToContract

Fields Mapping

Source Field Destination Field
contact_id contact_id
contract_id contract_id

lnkContractToDocument

Fields Mapping

Source Field Destination Field
document_id document_id
contract_id contract_id

Service

Fields Mapping

Source Field Destination Field
name name
org_id org_id
description description
status status

lnkDocumentToService

Fields Mapping

Source Field Destination Field
document_id document_id
service_id service_id

lnkContactToService

Fields Mapping

Source Field Destination Field
contact_id contact_id
service_id service_id
Role is no more used in 2.0 data model

ServiceSubcategory

Fields Mapping

Source Field Destination Field
name name
description description
service_id service_id
'incident' request_type
'production' status

SLA

Fields Mapping

Source Field Destination Field
name name
1 org_id

SLT

Fields Mapping

Source Field Destination Field
name name
ticket_priority priority
metric metric
value value
value_unit unit

lnkSLAToSLT

Fields Mapping

Source Field Destination Field
sla_id sla_id
slt_id slt_id

lnkCustomerContractToService

Fields Mapping

Source Field Destination Field
source(lnk)→contract_id customercontract_id
source(sla)→service_id service_id
source(lnk)→sla_id sla_id

lnkCustomerContractToProviderContract

Fields Mapping

Source Field Destination Field
customer_contract_id customercontract_id
provider_contract_id providercontract_id

Problem

Fields Mapping

Source Field Destination Field
ref ref
org_id org_id
agent_id agent_id
title title
description description
start_date start_date
last_update last_update
close_date close_date
status status
service_id service_id
servicesubcategory_id servicesubcategory_id
product product
impact impact
urgency urgency
priority priority
related_change_id related_change_id
assignment_date assignment_date
resolution_date resolution_date

RoutineChange

Fields Mapping

Source Field Destination Field
ref ref
org_id org_id
agent_id agent_id
title title
description description
start_date start_date
end_date end_date
last_update last_update
close_date close_date
status status
reason reason
requestor_id requestor_id
creation_date creation_date
impact impact
supervisor_group_id supervisor_group_id
supervisor_id supervisor_id
manager_group_id manager_group_id
manager_id manager_id
outage outage
fallback fallback

NormalChange

Fields Mapping

Source Field Destination Field
ref ref
org_id org_id
agent_id agent_id
title title
description description
start_date start_date
end_date end_date
last_update last_update
close_date close_date
status status
reason reason
requestor_id requestor_id
creation_date creation_date
impact impact
supervisor_group_id supervisor_group_id
supervisor_id supervisor_id
manager_group_id manager_group_id
manager_id manager_id
outage outage
fallback fallback
approval_date approval_date
approval_comment approval_comment
acceptance_date acceptance_date
acceptance_comment acceptance_comment

EmergencyChange

Fields Mapping

Source Field Destination Field
ref ref
org_id org_id
agent_id agent_id
title title
description description
start_date start_date
end_date end_date
last_update last_update
close_date close_date
status status
reason reason
requestor_id requestor_id
creation_date creation_date
impact impact
supervisor_group_id supervisor_group_id
supervisor_id supervisor_id
manager_group_id manager_group_id
manager_id manager_id
outage outage
fallback fallback
approval_date approval_date
approval_comment approval_comment

lnkContactToTicket

Fields Mapping

Source Field Destination Field
role role
ticket_id ticket_id
contact_id contact_id

lnkFunctionalCIToTicket

Fields Mapping

Source Field Destination Field
impact impact
ticket_id ticket_id
ci_id functionalci_id

KnownError

Fields Mapping

Source Field Destination Field
name name
org_id org_id
problem_id problem_id
symptom symptom
root_cause root_cause
workaround workaround
solution solution
error_code error_code
domain domain
vendor vendor
model model
version version

lnkErrorToFunctionalCI

Fields Mapping

Source Field Destination Field
error_id error_id
infra_id functionalci_id
reason reason

lnkDocumentToError

Fields Mapping

Source Field Destination Field
error_id error_id
doc_id document_id
link_type link_type

UserRequest

Fields Mapping

Source Field Destination Field
ref ref
org_id org_id
caller_id caller_id
agent_id agent_id
title title
description description
start_date start_date
last_update last_update
close_date close_date
status status
request_type request_type
impact impact
priority priority
urgency urgency
service_id service_id
servicesubcategory_id servicesubcategory_id
assignment_date assignment_date
resolution_date resolution_date
tto_escalation_deadline tto_escalation_deadline
ttr_escalation_deadline ttr_escalation_deadline
resolution_code resolution_code
solution solution
user_satisfaction user_satisfaction
2_3_0/install/1_to_2_upgrade.txt · Last modified: 2018/12/19 11:40 (external edit)
Back to top
Contact us