iTop Customization

iTop is built on top of an ORM (Object Relational Mapper) abstraction layer that relies on the definition of a “Meta Data Model” made of PHP classes. Starting with iTop 2.0 the Meta Data Model can be described in XML which is then “compiled” into PHP classes during the setup of the application.

The iTop architecture can be depicted as the schema below:

The orange boxes on the schema above are the parts of the application that can be customized.

The layout of the iTop files and folders can be depicted as below:

The following folders have a special usage in iTop:

• conf: contains the configuration files, with one sub-folder per environment (see Environments below).
• data: contains application generated data, like the image for the object life-cycle (if graphviz is available on the system)
• datamodels: contains the meta data model definitions, with one sub-folder per major version of iTop.
• env-xxxx: these folders (one per environment) contain the “compiled ” data model. The env-production folder is completely re-created each time the application is re-installed or upgraded. If you edit its content, be aware that your modifications will be lost upon re-install or upgrade.
• extensions: this folder is the place where to copy extensions modules that are not part of the standard distribution of iTop.
• log: contains the log files of the application: setup.log and error.log

All the other folders should be considered as part of the source code of the application and should generally not be modified. The application never writes to these folders, they can be marked as read-only for the web server process.

A new concept introduced by iTop 2.0 is the notion of “environment”. An environment is an instance of iTop running the same code base but with potentially its own data model and configuration file. An environment is made of:

• A configuration file stored in conf/name_of_the_environment/config-itop.php.
• A data model runtime, stored in env-name_of_the_environment

The toolkit automatically creates a separate environment (named toolkit) in order to compile the XML data model and test its consistency without affecting the “production” environment. When the changes are Ok, you can instruct the toolkit to apply the validated changes to the “production” environment.

The basic unit of data model definition in iTop is called a module. The installation process of iTop considers each module as a whole.

A module groups together all the files needed to deliver a given feature: data model definitions in XML, PHP classes, Javascript and CSS files, PHP pages, images, etc… A module contains at least one file: the module definition file, always named module.name_of_the_module.php.

Though you can always patch the source code, the best way to customize iTop consists in writing your own module. This creates a clean packaging of the customization and allow an easy (re)installation for your deployment or in case of upgrade.

The concept of extension is introduced with iTop 2.4. An extension is an assembly of one or more module(s). The installation options proposed to the end-user during the setup are based on the extensions found in the “extensions” folder of iTop; For backward compatibility, if a module is found outside of an extension, this module will be directly listed as an installation option.

Extensions are identified by the extension.xml file found in the root folder of each extension.

When an extension is made of one single module, the expected structure is one single folder with all the files extension.xml, module.xxxx.php, datamodel.xxxx.xml, etc. at the same level.

When an extension is made of several modules, the expected structure is one single root folder containing only the extension.xml file, with one subfolder per module (with module.xxxx.php, datamodel.xxxx.xml, etc)

If several extensions contain the same module (identified by its code), the installation process will install only one copy of the module: the highest version.

In iTop versions 1.x, the data model definition was written as a plain PHP classes. iTop version 2.0 support both PHP and XML definitions for the data model.

XML definitions have one major advantage over PHP definitions: the XML definition in one module can alter the data model defined in another module. For example, it is possible to create an extension module that will - when installed - add an attribute to the standard class “Server”, which is defined in the standard iTop data model. The extension module does not need to replace the whole “itop-config-management” module (where the Server class is defined), it can just alter the definition of a class defined elsewhere.

In order to achieve the same effect in PHP, the only solution consists in cloning the whole itop-config-mgmt module and replacing it with your own patched version. When a new version of the module is released, you have to redo this diff & patch work again to produce a new version of your own module. Since an XML definition is directly defined as a difference, the upgrade is automatic.

If my-module is the name of your module, the module folder will contain the following files:

All strings should be contained in dictionnary files.

Please see the dedicated wiki page : How to translate

Fill the form below and click on “Generate” to generate an empty extension as the starting point for your customization:

datamodel.sample-extension.xml

<?xml version="1.0" encoding="UTF-8" ?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.0">
  <classes>
  ...

When your module alter a class defined by another module, then that other module must be present and processed first in the Setup and Toolkit XML compilation, which will perform the PHP code generation.

The XML datamodel tree is build step by step, adding module one after the other, so an XML tag with a _delta=“redefine” instruction will fail if that tag is not yet present in the tree.

1. First search the tags you want to alter or graft onto, in the modules under <my-itop>/datamodels/2.x/. Your module will be dependent on those found modules.
2. Then retrieve for the modules you depends on: name and version in the file module.xxxx.php. For modules which are part if iTop Community, the module version follows the major iTop version

• Download the toolkit zip file: https://github.com/Combodo/itop-toolkit-community/releases
• Expand the content of the zip file to create a directory “toolkit” at the root of the your development iTop instance.
• Point your browser to http://<your_itop>/toolkit

1. Create an empty module
2. Install a development instance of iTop, including your empty module in the “extensions” folder
3. Install the toolkit on your developement instance
4. Edit your extension module and validate it with the toolkit
5. Apply the changes made to your extension module to the “production” environment
6. Test your module with some sample data. In case of troubles, fix them by iterating at point 4.

When your extension is completed you can deploy it on your production system by:

1. Copying the folder containing your extension module to the “extensions” folder on the production system
2. Marking the configuration file as read/write
3. Running the setup again and selecting your module in the list of “extensions” at the end of the interactive setup

Once the toolkit is installed, point your browser to: http://<your_itop>/toolkit.

The first tab performs some basic consistency checks and validation of the data model definition. You can use the “Refresh” button to perform the validation again each time the data model definition has changed. The checks performed in this tab work on the specific “toolkit” environment and thus have no effect on the actual iTop instance that uses the “production” environment.

When the first tab does not show any error, you can move to the second tab to:

• check the change to the database schema
• apply the changes of the database schema and data model definitions to the “production” iTop environment by clicking on “Udpate iTop Code”

The third tab of the toolkit can be used to update the Data Synchronization sources (if there are any that was impacted by the changes to the data model), and to check if there are any discrepencies in the internal data maintained for hierachical keys. This tab directly operates on the “production” environment.

A graphical representation of the object's life-cycle is displayed in the “Data Model” page of iTop (tab “Life-cycle”). If you modify an object's life-cycle, then you'll need to have Graphviz installed on the web server to get this images re-computed. See Installing iTop for more information about installing Graphviz.