Add a field to the Server class

Prerequisite: None, this tutorial is the first one that you must follow to understand the mechanism of creating an iTop extension.

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.

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

• create your own extension module for iTop
• 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.

• 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++.

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.

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

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

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/

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.

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" _delta="if_exists">
      <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>).

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.

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:

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.

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

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.

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:

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

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.

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:

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

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

sample-add-attribute.zip

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.