Data Synchronization Reference
If you are not familiar with the concept, start by the Overview
Data Source Definition
The Data Sources are defined using the menu Admin Tools/Synchronization Data Sources.
Each data source defines:
The target class of the objects to be synchronized
The list of attributes/fields of the objects to synchronize
How to search/reconcile the objects with the objects already existing in iTop
The rules of synchronizing/updating and possibly deleting objects in iTop
How the synchronized objects behave for the iTop end-users (which fields are read-only, are users allowed to delete the objects…)
An optional hyperlink and icon to refer iTop users to the corresponding object in the external application
This section of the Properties defines some general parameters for this Synchro Data Source
|The name which refers to this data source
|Servers synchro from SCCS
|An additional description, for information only
|implementation, production or obsolete: for filtering/classifying the data sources
|The class of objects to synchronize
|The user allowed to execute this synchro
|Contact to notify
|The contact to notify (by email) of the results when the synchronization is executed and contains at least one error
|The hyperlink (URL) to an image representing this data source. This icon is shown instead of the default icon in the tooltip appearing on the “Lock” symbol next to the title of the synchronized object in iTop
|The hyperlink (URL) to the remote application
from which the synchronized data comes from. The hyperlink can
contain placeholders such as
will be replaced by the value of the attribute of the current
$replica->column_name$ (which will be
replaced by the value of the named column from the replica)
|The name of the MySQL table in which the replica information will be stored. If omitted, the system will generate a unique name for you.
Because it was required to be able through synchro import to empty fields such as date, the format of date column was changed in release 2.3.4 from
Search & reconciliation
This section of the properties defines
How the information contained in the replica table is matched against the content of the iTop database
What is the behavior of this synchro data source concerning the creation of new iTop objects.
Use the attributes: when a new
replica is created, the system will search for a matching object in
iTop based on the list of Synchro attributes with the flag
Reconciliation set to
Use primary_key: the column
of the replica is expected to contain the identifier of the object
|Action on zero
|What to do when the reconciliation did not find
any object in iTop.
Create instructs the system to create a new object of
the Target Class.
Error will cause the system to report this case as an
error (i.e. this synchro data source is supposed to only update
|Action on one
|What to do when the reconciliation found exactly
one matching object in iTop.
Update instructs the system to update this object.
Error will cause the system to report this case as an
error (i.e. this synchro data source is supposed to create objects
and never update existing objects).
|Action on many
|What to do when the reconciliation found several
matching objects in iTop.
Create instructs the system to create another
Error will cause the system to report this case as an
Take the first one instructs the system to pick the
first object in the list and to update it.
This section defines how the deletion of the synchronized objects are handled:
by the end-users in iTop,
by the synchronization system itself.
|Which end-users are allowed to delete synchronized
objects in iTop.
Nobody when an object is synchronized, nobody is
allowed to delete it in iTop. only the synchronization system can
Administrators only only administrators are allowed to
delete a synchronized object.
Everybody allowed to delete such objects the normal
access rules apply to such synchronized objects.
|Full load interval
|The duration between two executions of the synchronization which are considered as having loaded (touched) all replicas. When a replica has not been touched for a duration greater than this value, it is considered as obsolete.
|What to do when a replica becomes obsolete.
Ignore do nothing, the associated object remains as is
Delete Delete the associated object in iTop (and the
replica in the data table).
Update Update the associated object as specified by
Update rules (see below).
Update then Delete Update the associated object as
specified by the
Update rules (see below), then after
Retention Duration, delete the object (and the
|A list of values separated by semi-colons, of the
attribute_code:value to specify which attribute
of the associated object to set and to which value. Example:
|The duration between the update of the associated
object and its deletion when the
Delete Policy is set
Update then delete.
The Attributes tab
The “Attributes” tab defines:
How to determine whether a new object must be created in iTop or an existing object must be associated with the replica (if the reconciliation rule is “Use Attributes” in the properties)
Which attribute(s) of the associated object must be updated, and how
When a new record appears in the
table, the synchronization mechanism will try to associate this
record with an existing iTop object. If one or more Attribute is
marked as “Yes” in the “Reconciliation ?” column, these
columns/attributes will be used to search for an iTop object that
matches all these values. If one object is found, it will become
associated with this record. If no object is found, a new iTop
object will be created.
The Update column
The Update column defines if the attribute must be updated or not.
Checked = Yes: the attribute will be set/updated
Unchecked = No: the external source information for this attribute will be ignored, the existing value on the iTop object will be kept as is.
The Update Policy column
The column Update Policy defines the behavior of the updated attribute. The possible values are:
Locked: the attribute will be completely driven by the data synchronization and will appear as read-only (with a small lock icon next to it) in the iTop user interface,
Unlocked: the attribute will be updated by the synchronization (whenever the source data changes) but end-users can still modify the attribute in parallel inside iTop,
Initialize if empty: the synchronization will only set a value of this attribute if the value is empty in iTop. The attribute remains modifiable inside iTop.
The Reconcialiation key column
Finally, the Reconciliation key column defines
how to process attributes which are references to another iTop
object (i.e. Foreign keys). The supplied data can contain either
the actual value of the foreign key (
id) or another
attribute such as the
name of the object; which must
uniquely identify the object.
If such a need arises, then you must use an ETL or a script to
perform the desired reconciliation before providing the
id to iTop.
The status tab
The Status tab displays information about the execution of the synchronization. If the synchronization has never been run, the tab displays the following message:
This synchro was never run. No log yet.
Otherwise the tab displays a schema similar to the one below:
On the left of the screen, each execution of the synchro is displayed in an historical list, showing the overall status, the start date and time of the execution.
Click on an element of this list to show the corresponding status in detail, displayed in the two columns on the right.
The column at the left displays the status for the records in
Newrecords are records which were added in the table since the previous execution of the synchro,
Existingrecords are records which were existing before and have been loaded again since the previous execution of the synchro,
Disappearedrecords are records which were not loaded since more than the
Ignoredrecords corresponds to objects no longer existing in iTop.
The column at the right displays the consequences of the synchro, in terms of modifications on the associated objects in iTop.
Newrecord, the consequences can be either:
The creation of the new object in iTop (
The update of an already existing object in iTop (
The simple association with an object in iTop, which is already up-to-date (
Errorwhen trying to either create or update an object in iTop (most probably because of inconsistent data).
Existingrecord, the consequences can be either:
The update of the associated object (
No change at all (
Or an error when trying to update the associated object (
Disappearedrecord, the consequences (depending on the “Deletion rules”) can be either:
The associated object in iTop has been deleted (
The associated object in iTop has been updated (
The associated object in iTop was left unchanged (
Or an error occurred when trying to update or delete the associated object in iTop (
In iTop, the Replicas are used to store the status
information and the relation between the raw data loaded in the
synchro_data_xxx table and the associated iTop
The Replicas for a given data synchronization source can be displayed by clicking on the links at the top of the status tab. A Replica is displayed as shown below:
The content of the replicas is useful to understand the behavior of the data synchronization mechanism (and to get more information about the errors), but its data are maintained by the synchronization and should never be modified manually.
Using MySQL statements to populate the synchro_data_xxxx table
If you populate the table
SQL commands (either with an ETL or a home made script), you
must take care of never creating duplicate
records. Remember that each record in the
synchro_data_xxx table corresponds to exactly one
object in iTop.
In order to avoid such duplicates, you must
first query for an existing record before inserting a new record
into the table. To speedup this query you can either construct a
value that uniquely identifies the “source” object and store this
value in the “primary_key” column of the table (which has a unique
index), or use any combination of the record's column and alter the
definition of the
synchro_data_xxxx table to add your
INSERT … ON DUPLICATE KEY UPDATE
to insert records in the
synchro_data_xxx table. This
is not supported by the internal iTop mechanism which relies on the
“BEFORE INSERT” trigger.
synchro_data_xxxx table, do not use
the MySQL statement
TRUNCATE TABLE, since this
statement will actually drop and reconstruct the table… but not its
triggers! Instead use
Using synchro_import to populate the synchro_data_xxxx table
How to specify a list of related objects (link set)
Some classes have attributes called Link Sets. Example: UserLocal.profile_list
You can synchronize those lists by writing all the information in the corresponding column:
Here is an example specifying that the login will have one profile: 'Portal User'
INSERT login, profile_list INTO data_synchro_userlocal_1 VALUES ('johndoe', 'profileid->name:Portal User;reason:Customer')...;
You can also specify several links (several profiles).
More information in Import a link set