Advanced topics

A CMDB is rarely a stand-alone application. In order to integrate iTop with the rest of your infrastructure, three powerful mechanisms are available:

• An Export page than can be used either as a web service or from the command line. The page allows to export in XML, CSV or HTML format any set of iTop objects that can be described by an OQL query.
• A scripted Import page available as a web service or from the command line to import or update iTop objects from a CSV file
• A Data Synchronization engine that enables iTop to federate data from various sources

All these services work on virtually any object in iTop: Devices, Contacts, Tickets, User Accounts…

Data synchronization is meant to import data into iTop, from another system, in a recurring manner. It can be run from the command line or from a web service, but not interactively. Data Synchronization is optimized for large volume of data that do not change very often. For example you may synchronize 10,000 contacts from an LDAP server, in iTop, once per day. Everyday probably only a small percentage of the users' records will be modified. This is efficiently handled by iTop.

When synchronizing data, iTop keeps track of the relationship between the iTop object and the source of the data. Therefore it is possible to prevent the users from modifying the synchronized objects (partially or totally) in iTop and to tell them where the data comes from. This is useful for “federating” several sources of data in iTop.

The CSV import (which can run interactively or from the command line) is more targeted towards “one shot” import. It can be used from a script (using the command line interface or the webservice) or interactively. When performing a CSV import, iTop does not record information about the source of the data. Once the data have been loaded into iTop, the objects can be modified by the authorized users, without any reference to the original source.

To summarize:

CSV import is good for:

• importing initial data in iTop
• performing bulk transformations on the data (sometimes it's easier to export / modify in Excel / reimport than to edit the objects directly in iTop)

Synchronization is good for:

• federating data between different systems in iTop
• importing data via some scheduled mechanism
• preventing users from modifying the imported data

The import, export and data synchronization pages can be run either as REST web services or from the Command-Line Interface (CLI). Since the CLI mode can only be used by scripts running on the iTop server itself it is considered as safer and generally runs with less limitations compared to the web pages (on most system the CLI mode has its own php.ini configuration). For example:

• CLI mode can benefit from longer timeout or no timeout at all (useful for running big imports)
• The memory_limit setting may be set to a bigger value for PHP scripts running in CLI mode.

In CLI mode, the arguments to iTop pages are always given with the prefix -- (two consecutive hyphens).

Example (on Windows):

php.exe -q c:\inetpub\itop\synchro\synchro_exec.php --auth_user=john --auth_pwd=trust,no1

Same example (on Linux):

php -q /var/www/itop/synchro/synchro_exec.php --auth_user=john --auth_pwd=trust,no1

or, even better, using a parameters file:

php -q /var/www/itop/synchro/synchro_exec.php --param_file=/etc/itop/params.foo

For security reasons it is always better to avoid passing credentials (user names and passwords) on the command line (the command lines corresponding to the processes running on the system are generally visible to all users logged-in). iTop offers the alternative to pass all command-line parameters inside a file, called the “parameters file” via the argument param_file . This argument can be used with most of the REST/CLI web services, it must contain the path to a parameters file.

Make sure that the parameters file is readable by the process that will run the PHP page, and that it cannot be accessed through the web server.

A parameters file contains key/value pairs and always uses the same format. It can be commented: any character found after # on a given line will be ignored

Example:

params

# This is a parameter file
#
# If a parameter is given both in the file and in the arguments,
# then the value given as argument is retained
#
 
# Authentication
auth_user = qwertyuiop
auth_pwd = ded!catedL0g1n
 
# My web service
size_min = 20 # Megabytes
time_limit = 40 # Minutes

• cron.php: the heartbeat of iTop, enables some features like asynchronous emails
• synchro_exec.php: trigger the synchronization of a list of data sources
• synchro_import.php: in one single operation, import data and trigger the synchronization process
• import.php: import data from CSV files
• export.php: export data in various formats

REST/JSON services are generic services. The APIs are low-level operations (search objects, create/update/delete objects) that will be the building bricks allowing any kind of integration.

Furthermore, a custom module can provide higher level operations that will be delivered through this same entry point.