Customizing iTop 1.

0
(Draft)

© 2010 Combodo. All rights reserved

1 Table of content

1  Table of content ...............................................................................................................................................2 
2  What can be customized in iTop .......................................................................................................................3 
3  Data Model ........................................................................................................................................................3 
Overview ................................................................................................................................................................3 
Change the model, step by step ...........................................................................................................................3 
Class defintion ......................................................................................................................................................3 
Available attributes ...............................................................................................................................................4 
4  Change the appearance ....................................................................................................................................5 
New menus ...........................................................................................................................................................5 
Templates ..............................................................................................................................................................6 
Overview ................................................................................................................................................................6 
Step by step ......................................................................................................................................................6 
itopblock ...........................................................................................................................................................6 

2
2 What can be customized in iTop
The iTop application was designed to be fully customizable. The data model of the application is fully
configurable. The user interface is "generic" and adapts automatically to the underlying data model.
There are two kind of things you can customize in iTop : the data model, and the appearance of data.
Adapt the data model if you want to add attributes to the existing objects or create your own objects
from scratch.
Change the appearance if the default appearance does not feet your need (e.g. need to strongly
differentiate between two kinds of objects, or need to display a powerful dashboard)

3 Data Model
Overview
The iTop Data Model is based on PHP classes. Each class of object manipulated by iTop corresponds to
a valid PHP class.
In order to be stored/maintained in the MySQL database by the iTop "ORM" (Object Relational Mapper)
layer, the definition of such classes uses a specific API, provided by the static "MetaModel" class.

Since release 1.0, classes delivered with iTop are defined in the files
/modules/mymodule/model.mymodule.php (e.g. /modules/itop-config-mgmt-1.0.0/model.itop-config-
mgmt.php).
The data model definition files are listed in the module definition files:
/modules/mymodule/module.mymodule.php.

Change the model, step by step

To adapt the data model to your needs you can either modify existing definitions or create your own
classes from scratch.

In both cases follow the process below:

1. Modify the PHP classes definitions - /modules/mymodule/model.mymodule.php.

2. Make sure that the file is listed in the module definition file:
/module/mymodule/module.mymodule.php
3. Run the setup program (do not forget to select the module)
4. Optional: edit or create the corresponding dictionnary file (see existing dictionnaries named
after '/modules/mymodule/en.dict.mymodule.php', where 'en' could be replaced by 'fr', etc.)
and make sure that this file is declared in config-itop.php.

When you're done you can use the iTop application with your new/modified data model, create new
instances of your objects, edit them, etc...

Class defintion
A class definition occurs, for each class, inside the method Init. This definition defines 5 types of
information:
1. Basic information about the class: name, label, table to use in the database, template for

3
 the display...
2. The list of Attributes (i.e. members of the class)
3. The list of Search Criteria for the class. (i.e. which attribute will be search-able – note that
in iTop 1.0 this list is obsolete, all attributes are search-able by default).
4. The life cycle for this class, if the class is state based (e.g. Incident Tickets).
5. Lists (called Zlists) defining the appearance of the object inside list of results or details...

Check the numerous examples in the “model.xxx” files (especially \modules\itop-config-mgmt-

1.0.0/model.itop-config-mgmt.php) for examples of what can be done with an iTop object.
class Organization extends cmdbAbstractObject
{
public static function Init()
{
$aParams = array
(
"category" => "bizmodel,searchable,structure",
"key_type" => "autoincrement",
"name_attcode" => "name",
"state_attcode" => "",
"reconc_keys" => array("name"),
"db_table" => "organization",
"db_key_field" => "id",
"db_finalclass_field" => "",
"display_template" => "",
);
MetaModel::Init_Params($aParams);
MetaModel::Init_InheritAttributes();

MetaModel::Init_AddAttribute(new AttributeString("name",
array("allowed_values"=>null, "sql"=>"name", "default_value"=>"", "is_null_allowed"=>false,
"depends_on"=>array())));
MetaModel::Init_AddAttribute(new AttributeString("code",
array("allowed_values"=>null, "sql"=>"code", "default_value"=>"", "is_null_allowed"=>true,
"depends_on"=>array())));
MetaModel::Init_AddAttribute(new AttributeEnum("status",
array("allowed_values"=>new ValueSetEnum('active,inactive'), "sql"=>"status",
"default_value"=>"active", "is_null_allowed"=>true, "depends_on"=>array())));
MetaModel::Init_AddAttribute(new AttributeExternalKey("parent_id",
array("targetclass"=>"Organization", "jointype"=>null, "allowed_values"=>null,
"sql"=>"parent_id", "is_null_allowed"=>true, "on_target_delete"=>DEL_MANUAL,
"depends_on"=>array())));
MetaModel::Init_AddAttribute(new AttributeExternalField("parent_name",
array("allowed_values"=>null, "extkey_attcode"=>"parent_id", "target_attcode"=>"name",
"is_null_allowed"=>true, "depends_on"=>array())));

MetaModel::Init_SetZListItems('details', array('name', 'code', 'status',

'parent_id'));
MetaModel::Init_SetZListItems('advanced_search', array('name', 'code',
'status'));
MetaModel::Init_SetZListItems('standard_search', array('name', 'code',
'status'));
MetaModel::Init_SetZListItems('list', array('status', 'parent_id'));
}
}

Available attributes
Here is the list of attributes that you can use. Please see existing examples to know more about the
options available on each type of attribute.
4
Type
AttributeString
AttributeText
AttributeEmailAddress
AttributeIPAddress
AttributeEnum
AttributeInteger
AttributeBoolean
AttributeDate
AttributeDateTime
AttributeBlob
AttributePropertySet
AttributeTable
AttributeExternalKey
AttributeExternalField
AttributeLinkedSet
AttributeLinkedSetIndirect
Description
String of 255 characters
Long string (depends on the length of TEXT columns on you MySQL
server)
String with format checking
String with format checking
Enumeration of values
Integer value
Boolean value
Date
Date and time
Document contents
A custom table of properties: no search possible, no rule on
formatting, no specific tracking of changes
A table of data: no rule at all, just a table
Link to an object of a given class
View an attribute of an object (given by the corresponding External
Key)
List of objects of a class having an external key on the current class
(1-N link)
List of objects of a class being linked through an intermediate class
(N-N link)

Once data model had been modified, just re-install this new version of iTop.

4 Change the appearance

New menus
Edit the data model file: /modules/mymodule/model.mymodule.php
Assuming you have created the class MyClass, you can add the following directives:

$oMyGroup = new MenuGroup('My data', 123 /* fRank */);

new NewObjectMenuNode('New data', 'MyClass', $oMyGroup->GetIndex(), 1 /* fRank */);
new SearchMenuNode('Search my data', 'MyClass', $oMyGroup->GetIndex(), 2 /* fRank */);
new OQLMenuNode('Some data', 'SELECT MyClass WHERE name LIKE \'foo\'', $oMyGroup-
>GetIndex(), 2 /* fRank */, true /* bSearch */);
Then you will have to create the corresponding entries into the dictionnary:
Dict::Add('EN US', 'English', 'English', array(
'Menu:My data' => 'My data',
'Menu:New data' => 'New data',
'Menu:Search my data' => 'Search my data',
'Menu:Some data' => 'Some data',

5
));
Note: there is an issue related to the value of fRank. The symptom is: a popup window displays
“assertion failed”. The workaround is to define another value for fRank (check especially with the first
entry (MenuGroup).
This customization does not require re-installation of iTop. You just have to reload your web browser.

Templates
Overview
Templates allow you to design a custom dashboard (or to customize an existing one).
A template is an html file which accepts tags recognized by iTop: <itopblock>. The tags defines
contents computed by itop: a list of objects, a pie chart or a bar chart.

Step by step
Create a template file (see existing HMTL files in /modules/ directories)
Declare the template in a data model file (see explanations above)
$oCINode = new TemplateMenuNode('My dashboard', '../modules/mymodule/mytemplate.html',
$oMyGroup->GetIndex(), 5 /* fRank */);

itopblock
An itopblock is the combination of an OQL query, a grouping criteria and a type of graphic. There are 3
types of itopblock:
• Bar chart
• Pie chart
• Display list

Syntax for an itopblock:

<itopblock BlockClass="DisplayBlock" objectclass="MyClass" type="type of graphics"
parameters="parameters for graphic" asynchronous="false" encoding="text/oql">OQL
query</itopblock>

Parameters for graphic correspond to information for defining a graph:

• chart_type:pie;group_by:<object attribute to use for group by>;chart_title:<Title> for pie chart
• chart_type:bars;group_by:<object attribute to use for group by>;chart_title:<Title> for bar chart
• group_by: :<object attribute to use for group by> for tables

See OQL reference guide for more details

Here is an example of menu definition for “MyClass”:

<h1><itopstring>DictionaryID</itopstring></h1>
<table border="0" padding="5" class="layout" width="100%">
<tr>
<td class="dashboard">
<itopblock BlockClass="DisplayBlock" type="open_flash_chart"
parameters="chart_type:bars;group_by:someattribute;chart_title:DictionaryID"
asynchronous="false" encoding="text/oql">SELECT MyClass</itopblock>
</td>

6
 <td class="dashboard">
<itopblock BlockClass="DisplayBlock" type="open_flash_chart"
parameters="chart_type:pie;group_by:someattribute;chart_title:DictionaryID"
asynchronous="false" encoding="text/oql">SELECT MyClass</itopblock>
</td>
</tr>
<tr>
<td class="dashboard">
<h2><itopstring>DictionaryID</itopstring></h2>
<itopblock BlockClass="DisplayBlock" type="list" parameters="dashboard:true"
asynchronous="false" encoding="text/oql">SELECT MyClass WHERE age = 30</itopblock>
</td>
<td class="dashboard">
</td>
</tr>
</table>

DicionaryID could be either a label, or a placeholder for the label found in a dictionary. The use of a
disctionary is a must if localization is needed.