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

Consider browsing to iTop 3.2 documentation

Adding a new field to the Server class

This document explains, step by step, how to create your own iTop module in order to add a new field to an existing iTop object.

Goals of this tutorial

In this step-by-step tutorial you will learn to:

  • create your own extension module for iTop 2.0
  • add a new field to an existing class of object

For the purpose of this tutorial we will add a text field labeled Additional Notes to the Server object.

Customized Server

What you will need

  • iTop installed on a development machine, on which you can easily access/edit the files.
  • A text editor capable of editing PHP and XML file and supporting UTF-8. On Windows you can use Wordpad (Notepad does not like Unix line endings) or one of the excellent free development IDEs like PSPad or Notepad++.

Customization process

The customization process is the following:

  1. Install a development instance of iTop. It is always better not to experiment in production !!
  2. Install the toolkit to assist you in the customization
  3. Create a new (empty) module using the module creation wizard
  4. Copy this new module in the extensions folder on iTop and run the setup again to install the empty module
  5. Modify the module in extensions and use the toolkit to check your customizations

Repeat the last point until you are satisfied with your customization. When you are done, your new module is ready to be deployed. Copy the module folder in the extension directory on your production iTop instance and run the setup to install it.

Step by step tutorial

Create your customization module

Use the module creation wizard. Fill the form with the following values:

Label Value Remarks
Module name sample-add-attribute Names starting with itop- and combodo- are reserved for use by Combodo. It is recommended not to put spaces or accentuated characters in the name of the module. Two modules with the same name cannot co-exist in the same iTop instance.
Module Label Add Attribute Sample This label will be displayed in the setup wizard. Localized characters and spaces are allowed
Module Version 1.0.0 The convention is to use a 3 digits numbering scheme: X.Y.Z
Category business Modules that provide modifications to the data model should be in the category 'business'
Dependencies itop-config-mgmt/2.0.0 Our customization module depends on the module iTop Configuration Management version 2.0.0 in which the Server class is defined

Click Generate ! to download the empty module as a zip file.

When a module modifies an existing class, it must be loaded after the module that declared the class to be modified. To achieve this, make sure that the first module is listed in the dependencies of your new module.

For example if you want to alter the definition of the VirtualMachine class, your custom module must depend on itop-virtualization-mgmt/2.0.0

Install the empty module

Expand the content of the zip into the extensions folder of your development iTop instance. You should now have a folder named sample-add-attribute inside the extensions folder. this folder contains the following files:

  • datamodel.sample-add-attribute.xml
  • module.sample-add-attribute.php
  • en.dict.sample-add-attribute.php
  • model.sample-add-attribute.php

Make sure that the file conf/production/config-itop.php is writable for the web server (on Windows: right click to display the file properties and uncheck the read-only flag; on Linux change the rights of the file), then launch the iTop installation by pointing your browser to http://your_itop/setup/

Launching the re-install

Click “Continue »” to start the re-installation.

Make sure that “Update an existing instance” is selected before clicking “Next »”.

Continue to the next steps of the wizard…

Your custom module should appear in the list of “Extensions”. If it's not the case, check that the module files were copied in the proper location and that the web server has enough rights to read them.

Select your custom module before clicking “Next »” and complete the installation.

Add a new field to the Server class

Using you favorite text editor, open the file datamodel.sample-add-attribute.xml.

Remove the tags <menus></menus> since the module will not contain any menu definition.

Inside the classes tag, add the following piece of code:

    <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
     </class>

This instructs iTop to modify the existing class “Server” by adding a new field (notice the _delta=“define” on the field tag) of type AttributeText. This new field is named notes (since it is defined with id=“notes”). The corresponding values will be stored in the database in the column notes (thanks to the definition <sql>notes</sql>).

For more information about the meaning of the various parameters of the field tag (and also for the list of all possible types of fields) refer to the XML reference documentation.

You should now have the following XML file:

datamodel.sample-add-attribute.xml
<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <classes>
    <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
     </class>
  </classes>
</itop_design>

Check your modification by running the toolkit. Point your browser to http://your_itop/toolkit.

Checking the modifications with the toolkit

If any error is reported at this stage, fix them by editing the XML file and check again your modifications by clicking on the “Refresh” button in the toolkit page.

Once all the errors have been fixed, you can apply the modifications to iTop by using the second tab of the toolkit:

Applying the modifications to iTop

Click on the button Update iTop Code to:

  1. Compile the XML data model to PHP classes
  2. Update the database schema to add the new text column.

At this point, if you look at the schema of the MySQL database, you can see the additional “notes” column added to the “server” table. However if you navigate to a Server in iTop, nothing has changed.

The udpated database schema in phpMyAdmin

This is because iTop was not instructed how to display the added field. So the field exists but is not displayed in iTop.

Make the new field visible

Let's add the new field to the “details” of the Server object, just below the “Description”. This can be achieved by redefining the way the “details” of a Server are displayed.

Using your text editor, open the file datamodels/2.x/itop-config-mgmt/datamodel.itop-config-mgmt.xml.

Search for the string <class id="Server" to locate the definition of the Server class.

Scroll down to the <presentation> tag and copy the whole content of the <details>…</details> tag.

Paste this whole definition in datamodel.sample-add-attribute.xml after the closing </field> tag, and enclose it in <presentation>…</presentation> tags.

Change the opening tag <details> to <details _delta=“redefine”> in order to instruct iTop to redefine the presentation for the “details”.

Insert the 3 lines:

                    <item id="notes">
                      <rank>40</rank>
                    </item>

Just after the lines:

                    <item id="description">
                      <rank>30</rank>
                    </item>

You should now obtain the following XML file:

datamodel.sample-add-attribute.xml
<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <classes>
    <class id="Server">
      <fields>
        <field id="notes" xsi:type="AttributeText" _delta="define">
          <sql>notes</sql>
          <default_value/>
          <is_null_allowed>true</is_null_allowed>
        </field>
      </fields>
      <presentation>
        <details _delta="redefine">
          <items>
            <item id="softwares_list">
              <rank>10</rank>
            </item>
            <item id="contacts_list">
              <rank>20</rank>
            </item>
            <item id="documents_list">
              <rank>30</rank>
            </item>
            <item id="tickets_list">
              <rank>40</rank>
            </item>
            <item id="physicalinterface_list">
              <rank>50</rank>
            </item>
            <item id="fiberinterfacelist_list">
              <rank>60</rank>
            </item>
            <item id="networkdevice_list">
              <rank>70</rank>
            </item>
            <item id="san_list">
              <rank>80</rank>
            </item>
            <item id="logicalvolumes_list">
              <rank>90</rank>
            </item>
            <item id="providercontracts_list">
              <rank>100</rank>
            </item>
            <item id="services_list">
              <rank>110</rank>
            </item>
            <item id="col:col1">
              <rank>120</rank>
              <items>
                <item id="fieldset:Server:baseinfo">
                  <rank>10</rank>
                  <items>
                    <item id="name">
                      <rank>10</rank>
                    </item>
                    <item id="org_id">
                      <rank>20</rank>
                    </item>
                    <item id="status">
                      <rank>30</rank>
                    </item>
                    <item id="business_criticity">
                      <rank>40</rank>
                    </item>
                    <item id="location_id">
                      <rank>50</rank>
                    </item>
                    <item id="rack_id">
                      <rank>60</rank>
                    </item>
                    <item id="enclosure_id">
                      <rank>70</rank>
                    </item>
                  </items>
                </item>
                <item id="fieldset:Server:moreinfo">
                  <rank>20</rank>
                  <items>
                    <item id="brand_id">
                      <rank>10</rank>
                    </item>
                    <item id="model_id">
                      <rank>20</rank>
                    </item>
                    <item id="osfamily_id">
                      <rank>30</rank>
                    </item>
                    <item id="osversion_id">
                      <rank>40</rank>
                    </item>
                    <item id="oslicence_id">
                      <rank>50</rank>
                    </item>
                    <item id="cpu">
                      <rank>60</rank>
                    </item>
                    <item id="ram">
                      <rank>70</rank>
                    </item>
                    <item id="nb_u">
                      <rank>80</rank>
                    </item>
                    <item id="serialnumber">
                      <rank>90</rank>
                    </item>
                    <item id="asset_number">
                      <rank>100</rank>
                    </item>
                  </items>
                </item>
              </items>
            </item>
            <item id="col:col2">
              <rank>130</rank>
              <items>
                <item id="fieldset:Server:Date">
                  <rank>10</rank>
                  <items>
                    <item id="move2production">
                      <rank>10</rank>
                    </item>
                    <item id="purchase_date">
                      <rank>20</rank>
                    </item>
                    <item id="end_of_warranty">
                      <rank>30</rank>
                    </item>
                  </items>
                </item>
                <item id="fieldset:Server:otherinfo">
                  <rank>20</rank>
                  <items>
                    <item id="powerA_id">
                      <rank>10</rank>
                    </item>
                    <item id="powerB_id">
                      <rank>20</rank>
                    </item>
                    <item id="description">
                      <rank>30</rank>
                    </item>
                    <item id="notes">
                      <rank>40</rank>
                    </item>
                  </items>
                </item>
              </items>
            </item>
          </items>
        </details>
      </presentation>
    </class>
  </classes>
</itop_design>

Check your modification by running the toolkit. Point your browser to http://your_itop/toolkit.

Checking the modifications with the toolkit

If any error is reported at this stage, fix it by editing the XML file and check again your modifications by clicking on the “Refresh” button in the toolkit page.

Once all the errors have been fixed, you can apply the modifications to iTop by using the second tab of the toolkit:

Applying the modifications to iTop

If you now navigate to the details of a Server in iTop you should see the following: New field with missing dictionary

Add a label for the new field

Notice that the label of the new field is iTop is notes (by default it is equal to the name of the field). In order to change this to Additional Notes we have to add an entry in the dictionary.

Using you text editor, open the file en.dict.sample-add-attribute.php.

Insert the line:

  'Class:Server/Attribute:notes' => 'Additional Notes',

Just below the comment:

  // Dictionary entries go here

You should obtain the following file:

en.dict.sample-add-attribute.php
<?php
/**
 * Localized data
 *
 * @copyright   Copyright (C) 2013 Your Company
 * @license     http://opensource.org/licenses/AGPL-3.0
 */
 
Dict::Add('EN US', 'English', 'English', array(
        // Dictionary entries go here
        'Class:Server/Attribute:notes' => 'Additional Notes',
));
?>

One more time, check your modification by running the toolkit.

Checking the modifications with the toolkit

If errors are reported at this stage, fix them by editing the PHP file and check again your modifications by clicking on the “Refresh” button in the toolkit page.

Once all the errors have been fixed, you can apply the modifications to iTop by using the second tab of the toolkit:

Applying the modifications to iTop

If you navigate to the details of a Server in iTop, you should now see the following:

Customized Server

Final Customization Module

The final result of the customization is available in the zip file below:

sample-add-attribute.zip

Next Steps

You can use the same process to add more fields to the same object, or to alter other objects in iTop.

If you want the added fields to appear either in the default “list” view or “search” form for the modified class of objects, the corresponding “presentation” list must be redefined as well.

To deploy your customization to another iTop server, simply copy the folder “sample-add-attribute” to the extensions folder of iTop and run the setup again.

2_3_0/customization/add-attribute-sample.txt · Last modified: 2018/12/19 11:40 by 127.0.0.1
Back to top

Table of Contents

Contact us
Contact us