XML Data Model Reference

This document is the reference documentation for the format of the XML used in the datamodel.xxxx.xml files inside iTop modules. An XML data model file can be used to define:

classes - that will generate the actual PHP classes when “compiled” using either the setup program or the toolkit
menus - to be inserted in the application's menu on the left of the iTop pages
profiles - to manage the access rights to the iTop objects
branding

The versions 2.1, 2.2, 2.3 and 2.4 of iTop introduce a number of minor changes to the XML structure in order to ease the customization of iTop. iTop always supports older format (backward compatibility). The complete list of modifications introduced by the new formats are described in chapter Changes history.

In order to clarify the reference data model, a few parts have been changed in iTop 2.1.0. For more information, please read the 2.0.3 to 2.1.0 Migration Notes

Principles

An XML data model contains both initial declarations and/or alterations of declarations made in other XML files.

The iTop compiler works in two steps:

Load the XML data model files of the installed modules. The XML are combined into one single XML definition. It is important to figure out that, starting from an empty definition, iTop will merge each XML one by one,
Interpret the final combined definition.

The XML format reference described hereafter applies to the combined definition. Thus an XML may not contain all the mandatory nodes, but only those required to identify the path of an alteration and those required to (re)define items.

By default, the contents of a given XML are merged into the combined definition.

Alter node contents

You can define alterations using the attribute _delta. This attribute specifies how a given node must be considered, including its subnodes.

_delta can take the following values:

_delta	Meaning
merge (default)	Create this node if it does not exist already. Then examine the delta in its child nodes. This is mostly relevant for the structure nodes
must_exist	Ensure that this node already exists. Then examine the delta in its child nodes.
if_exists	New in 2.3.0 - Check if this node already exists. If so, examine the delta in its child nodes. Otherwise ignore this node. It is similar to must_exist, but it skips the current node instead of stopping the whole process.
define	This is the first definition of this node. No flag should be found into its child nodes.
define_if_not_exists	If the node does not already exist then define it. Ignore it otherwise.
redefine	The contents of this node must be replaced by the contents of the delta node.
delete	Delete this node. This node should not have child nodes (no contents)
force	Force the definition of this node, whether it exists or not

A node is identified by its tag name and the attribute id. If no id is given, then the node is identified as being the FIRST node being found having the same tag name.

When the compiler encounters define/redefine, it considers that the subtree is pure content definition. As a consequence, any attribute _delta or _rename_from found in that subtree will be ignored.

Rename a node

Another attribute is _rename_from. Use it to specify that the item (e.g. a class field) is in fact an existing item renamed from _rename_from to id.

XML general structure

Use the triangle arrow on the left of an item to expand/collapse its definition.

Tag	Usage	Description
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.2">	mandatory	Structural node. The version has been incremented to 1.4 due to minor changes in iTop 2.4.0
<classes>	mandatory	Declared classes
<class id="name">	zero or more	Declaration of class
<parent>cmdbAbstractObject</parent>	mandatory	Parent class
<properties>	mandatory
<is_link>1</is_link>	optional	Differentiate classes used for linking other classes together. Set to 1 for a linking class.
<comment>	mandatory	PHP comments added into the compile file, before the declaration of the class
<category>bizmodel,searchable,structure</category>	optional	Usages that will be made of this class.
<abstract>false</abstract>	mandatory	Abstract classes can not be instantiated.
<key_type>autoincrement</key_type>	mandatory	Always set to "autoincrement"
<db_table>name</db_table>	mandatory	Name of the MySQL table used for this class. The name given here will be automatically predended with the suffix provided at installation if any.
<db_key_field>id</db_key_field>	mandatory	Always setting the identifier field to "id" is fine
<db_final_class_field>finalclass</db_final_class_field>	mandatory	If the class is on top of a hierarchy of classes, then you must define which MySQL column will be used for keeping track of the real class of object instances. Setting this to "finalclass" is fine.
<naming>	optional	Define the attributes used to compose the friendly name of an object. By default, the friendly name will be rendered as a concatenation of the given attributes, separated by a white space. You can specify any other format by adding a dictionary entry 'Class:<myClass>/Name'. This format is given as a printf-like formatting expression (Only $s is supported. e.g. '%1$s of %2$s'). As such a format is located in the dictionary, it may be translated, and the friendly name would depend on the language of the end-user. Note that in iTop 2.0.3, a tag <format> was present in the XML files provided with iTop but it was not used, and that was misleading.
<attributes>	mandatory	List of attributes used to compose the friendly name. Note that the order matters.
<attribute id="name">	at least one
<order>	optional	Defines the default sort order for the class, if omitted the class is sorted on the friendly name
<columns>	mandatory
<column id="name" ascending="true\|false">	at least one	Either sort ascending or descending on this attribute. The order of the attributes is important.
<display_template>	optional
<icon>	optional	Specify an icon for your class
<reconciliation>	mandatory	Define the default reconciliation scheme for data import.
<attributes>	mandatory	List of attributes used for the reconciliation.
<attribute id="name">	at least one
<indexes>	optional	Define table indexes
<index id="name">	zero or more	To explicitly force a database index to be created with all specified attributes in the declared order.
<attributes>	mandatory	List of attributes used for the index. The order matters.
<attribute id="name">	at least one
<archive>	optional	Archival configuration.
<enabled>true</enabled>	mandatory	Applicable on root classes only. Set to true to make this class and all its descendant archivable (adds two magic attributes: archive_flag and archive_date). Attempting to set false when any of the parent has enabled=true will lead to an error at runtime
<obsolescence>	optional	Obsolescence configuration. As soon as the obsolescence is defined for a class, two magic attributes are added (obsolescence_flag and obsolescence_date), all classes in the hierarchy have the flag (defaulting to "No")
<condition><![CDATA[status='closed' AND closed_date < DATE_FORMAT(DATE_SUB(NOW(), INTERVAL 3 MONTH),'%Y-%m-%d 00:00:00')]]></condition>	mandatory	OQL expression that defines wether an object is obsolete or not. This condition will be inherited by child classes, unless it is redefined.
<fields>	mandatory	Declaration of attributes (cumulated with attributes inherited from a parent class, if any)
<field>	at least one	Declaration of an attribute. See the various types of attributes in section Fields
<lifecycle>	optional	Lifecycle: states and transitions
<highlight_scale>	optional	A list of highlight codes defining the display of the object (background color in lists and icon)
<item id="warning">	at least one	Definition of a new higlight code
<rank>1</rank>	mandatory	The rank (or weight) of this highlight code
<color>HIGHLIGHT_WARNING</color>	mandatory	The color scheme for this code: HIGHLIGHT_NONE (tranparent), HIGHLIGHT_WARNING (orange), HIGHLIGHT_CRITICAL (red) or HIGHLIGHT_OK (green)
<icon>	mandatory	The icon for the object in this state
<attribute>name</attribute>	mandatory	Attribute used for the state (must be declared as AttributeEnum, can be inherited from a parent class)
<stimuli>	mandatory	List of events to which the object will be sensitive
<stimulus>	at least one	Declaration of a stimulus. See the various types of stimuli in section Stimuli
<states>	mandatory	Possible states. The list of states must be a subset of the values defined for the "state" attribute.
<state id="name">	at least one	The complete definition of a state: name, attribute flags and transitions to other states
<initial_state_path>	optional	An ordered list of states through which the object will go when it is created
<state_ref>new</state_ref>	mandatory	A state
<inherit_flags_from>another_state</inherit_flags_from>	optional	The name of a state to inherit the flags from. Note: must_change and must_prompt flags are never inherited
<highlight>	optional	Highlight definition for this state
<code>name</code>	mandatory	The highlight code
<flags>	mandatory	Define here how the attributes will be shown in the GUI, for the given state
<attribute id="name">	at least one	Combination of flags interpreted by the GUI
<hidden>	optional	The attribute is hidden in this state
<read_only>	optional	The attribute is shown and cannot be modified
<must_prompt>	optional	The GUI must prompt the user when the object is entering the state
<must_change>	optional	The attribute must be changed by the user when the object is entering the state
<mandatory>	optional	The attribute must be defined when entering this state. This overrides the definition of the attribute (tag "is_null_allowed")
<transitions>	mandatory	List of possible transitions from this state to another
<transition id="name">	at least one	For a given stimulus, defines the target state and the actions to perform. If the identifier is omitted the name of the stimulus will be used.
<stimulus>name</stimulus>	mandatory	Event triggering this transition
<target>name</target>	mandatory	State reached after the transition
<flags>	mandatory	Define here how the attributes will be shown in the GUI, for that transition
<attribute id="name">	at least one	Combination of flags interpreted by the GUI
<mandatory>	optional	The attribute must be defined to complete the transition. This overrides the definition of the attribute (tag "is_null_allowed")
<must_change>	optional	The attribute must be changed by the user to complete the transition
<must_prompt>	optional	The attribute is displayed in edit mode during the transition
<read_only>	optional	The attribute is shown, but cannot be modified
<actions>	mandatory	Ordered list of actions to perform during the transition
<action>	at least one	A single action
<verb>name</verb>	mandatory	Name of the method that will be called (see the tag "methods" hereafter)
<params>	mandatory	List of the method parameters
<parameter xsi:type="string\|int\|float\|reference">	zero or more	The value of the parameter
<methods>	mandatory	Additional function declarations. The function will be declared within the class. This is the mean to overload some functions of DBObject or cmdbAbstractObject. Use with care.
<method id="name">	zero or more	A function
<comment>	optional	PHP comment. Will be predended to the declaration of the class into the generated (compiled) PHP code.
<static>false</static>	mandatory	Set to true if you need to declare a static function, false otherwise.
<access>public</access>	mandatory	Set to public, protected or private (See the documentation of PHP)
<type>Overload-DBObject</type>	mandatory	Use one of the following values: LifecycleAction, Overload-cmdbAbstractObject, Overload-iDisplay, Overload-DBObject, Overload-ExNihilo, Custom
<arguments>	optional	Declare the type of the arguments for lifecycle actions
<argument>current_stimulus_code</argument>	zero or more	The type of an argument. Use one of the following values: attcode, class, current_stimulus_code, int, reference, string
<code>	mandatory	PHP code. Must include the function prototype. It is higly recommended to put it within a CDATA to avoid the need for escaping xml entities within your code.
<relations>	optional	Relations between the object of the current class and objects of other classes. Supported only since iTop 2.2.0.
<relation id="impacts">	zero or more	A given relation. Today "impacts" is the only value supported by iTop, but a module could use other values
<neighbours>	mandatory	Neighbour classes
<neighbour id="name">	zero or more	Name is usually the neighbour class name. Either an attribute must be specified, or a pair of queries (downward and upward)
<query_down>SELECT SoftwareInstance AS s WHERE s.system_id = :this->id</query_down>	optional	The OQL query that defines the related objects, following the relation flow (downstream)
<query_up>SELECT SoftwareInstance AS s WHERE s.system_id = :this->id</query_up>	optional	The OQL query that defines the related objects, going backward in the relation flow (upstream)
<attribute>something_list</attribute>	optional	An alternative to the OQL query is to specify an attribute (an external key or a link set)
<direction>both</direction>	optional	Set to "down" to restrict the browsing. Defaults to "both"
<presentation>	mandatory
<details>	mandatory	Defines the presentation for both the vizualisation and the edition form of an object. Can be overriden by the lifecycle flag "hidden"
<items>	at least one	Refer to Presentation (details)
<search>	mandatory	Ordered list of attributes shown in the 'Most popular' section of the 'Add new criteria' menu of search screens
<items>	at least one	Refer to Presentation (search, default-search or list)
<default_search>	optional	Ordered list of default search criteria shown in search screens. This parameter is inherited from parent class if left empty or not existing.
<items>	at least one	Refer to Presentation (search, default-search or list)
<list>	mandatory	Ordered list of attributes shown by default in result lists
<items>	at least one	Refer to Presentation (search, default-search or list)
<menus>	mandatory	Declaration of the menus shown in the main GUI (left pane)
<menu>	at least one	Declaration of a menu. See the various types of menus in section Menus
<user_rights>	mandatory	Implementation of the user rights policy: users will have one or more profiles, granting them access rights.
<groups>	mandatory	Groups are sets of classes. Grants are given based on this grouping - see "profiles"
<group id="name">	at least one	A set of classes.
<classes>	mandatory	List of classes found in the group
<class id="name">	zero or more
<profiles>	mandatory	Profiles that will be listed in the application. A user can have one or more profiles. The profile "administrator" is always present and cannot be redefined.
<profile id="123">	at least one	A usage profile.
<name>Configuration Manager</name>	mandatory	Name of the profile as it will be shown in the application. No translation is possible.
<description>Person in charge of the documentation of the managed CIs</description>	mandatory	Description of the profile (one line) as it will be shown in the application. No translation is possible.
<groups>	mandatory	Grants associated to the profile
<group>	at least one	Group for which grants must be defined
<actions>	mandatory	Allowed actions for the profile/group
<action>	at least one	See the various types of grant in section Action grants
<files>	optional	For embedding binary files (like icons) in the XML. Supported only since iTop 2.0.1
<file>	at least one	Declaration of file, see details in the section Files
<dictionaries>	optional	For adding localizations into the XML. Supported only since iTop 2.0.1
<dictionary>	at least one	Declaration of dictionary for a given language, see details in the section Dictionaries
<branding>	optional	Appearance of the GUI.
<main_logo>	optional	Logo for the main GUI (top left corner). Defined as a PNG file (path relative to the modules root directory = env-production), or fileref tag
<login_logo>	optional	Logo for the login page. Defined as a PNG file (path relative to the modules root directory = env-production), or fileref tag
<portal_logo>	optional	Logo for the customer portal (top left corner). Defined as a PNG file (path relative to the modules root directory = env-production), or fileref tag
<constants>	optional	Constants to be compiled as PHP defines.
<constant id="name" xsi:type="string\|integer\|bool\|float">	at least one	Constant. Put it within a CDATA to avoid the need for escaping xml entities. Boolean type 'true' and 'false'.
<portals>	optional	Definition of entry points for the user interface. Supported only since iTop 2.2.0.
<portal id="Unique identifier of this portal">	at least one	A portal: i.e. an entry point for the user interface.
<rank>	mandatory	The order of precedence for the initial routing. Lower numbers are tried first.
<url>	mandatory	The (relative) URL to the portal entry page.
<handler>	optional	The name of a class derived from PortalDispatcher that will handle the dispatching between the different possible portals. Defaults to PortalDispatcher is not specified.
<allow>	optional	A list of profiles that the user must have in order to be allowed to access this portal
<profile id="Name of the profile for allowing access">	zero or more
<deny>	optional	A list of profiles that deny access this portal. If the user has at least one of these profiles she/he will be banned from this portal
<profile id="Name of the profile for denying access">	zero or more
<module_parameters>	optional	Definition of module specific parameters. Supported only since iTop 2.2.0.
<parameters id="module_unique_id">	at least one	Contains the module specific parameters, for example default configuration values, stored as subtags. See the section Modules parameters.
<module_designs>	optional	Module specific design data. Supported only since iTop 2.3.0.
<module_design id="??">	at least one	Container node for a set of design data. The identifier must be unique. It can match the name of the module, but any string is allowed provided that it does not contain slashes or backslashes
<snippets>	optional	Snippets of PHP code to be injected in the PHP model files. Supported only since iTop 2.2.0.
<snippet id="unique identifier for this snippet">	at least one	A snippet of PHP code
<placement>	mandatory	The placement of the PHP code: either 'module' or 'core'.
<module>	optional	if placement == module, the identifier of the module.
<rank>	mandatory	The order of the snippet (if there are several snippets to be injected in a given module). The lower numbers are injected first. Negative ranks are injected before the compiled model, positive ranks are injected after.
<content>	mandatory	The actual PHP code to inject.
<meta>	optional	Root for storing meta information about the XML definition, ignored by the compiler. More details in section Meta

Fields

The fields (also called attributes) are the actual data members of the objects. A field generally corresponds to one (or more) columns(s) in one table in the database. The different types of fields are listed in the table below:

Use the triangle arrow on the left of an item to expand/collapse its definition.

Tag	Usage	Description
<field id="name" xsi:type="AttributeString">	zero or more	A string, limited to one line of 255 characters
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<validation_pattern>^[a-z]*\d+$</validation_pattern>	optional	Enforce a format based on a regular expression (slashes must be escaped)
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeEnum">	zero or more	A string that can take its value out of a fixed set of possible values
<values>	mandatory	List of possible values
<value id="name">name</value>	at least one	Value. Must be made of alphanumeric characters. Other authorized characters: '_', '-'. The id is used solely for identifying the XML node
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (must be in the list of possible values)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<display_style>list</display_style>	optional	Style of display when editing this field: 'list', 'select' (same as list), radio_horizontal', 'radio_vertical' or 'radio' (same as radio_vertical)
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeMetaEnum">	zero or more	A string computed after other enumeration fields that can be defined in subclasses. Supported only since iTop 2.3.0
<values>	mandatory	List of possible values
<value id="name">name</value>	at least one	Value. Must be made of alphanumeric characters. Other authorized characters: '_', '-'. The id is used solely for identifying the XML node
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (must be in the list of possible values).
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<mappings>	mandatory	Rules to compute the value of the AttributeMetaEnum. Define maximum one per sub-class. Depending on the object class, the best matching rule class will be used. The meta value defaults to <default_value> if no class matches the object class.
<mapping id="name">	at least one	Rule class name for which the following mapping applies.
<attcode>name</attcode>	mandatory	The source AttributeEnum, from which the raw value will be read. Must be a valid attribute of the rule class
<metavalues>	mandatory	Data mapping table. If the raw value is not found, then the meta value defaults to <default_value>
<metavalue id="name">	at least one	Meta value, which will be used for all raw values defined below.
<values>	mandatory	Raw values that will map to the meta value.
<value id="name">	at least one	A raw value specified as the tag id.
<field id="name" xsi:type="AttributeEmailAddress">	zero or more	An email address
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<validation_pattern>[a-z]+@[a-z]+</validation_pattern>	optional	Enforce a format based on a regular expression (slashes must be escaped). Defaults to the global setting 'email_validation_pattern'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributePhoneNumber">	zero or more	A phone number
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<validation_pattern>[0-9.\-\ \+]+</validation_pattern>	optional	Enforce a format based on a regular expression (slashes must be escaped). Defaults to the global setting 'phone_number_validation_pattern'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeExternalKey">	zero or more	An external key: a pointer to an object of the given class
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<on_target_delete>DEL_AUTO</on_target_delete>	mandatory	Define how the deletion of the target object will impact the current object. Allowed values are 'DEL_MANUAL' and 'DEL_AUTO'
<target_class>name</target_class>	mandatory	The class of the objects to which the external key is pointing
<filter>SELECT Location AS L WHERE L.org_id = :this->org_id</filter>	optional	OQL query to define a set of object to which the external key can point to. Use :this->name to refer to a value in the current object
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<max_combo_length>50</max_combo_length>	optional	The maximum number of elements in a drop-down list. If more then an autocomplete will be used. Defaults to the value given in the configuration file.
<min_autocomplete_chars>3</min_autocomplete_chars>	optional	The minimum number of characters to type in order to trigger the "autocomplete" behavior. Defaults to the value given in the configuration file.
<allow_target_creation>true</allow_target_creation>	optional	Displays the + button on external keys to create target objects. Defaults to the value given in the configuration file.
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<display_style>list</display_style>	optional	Style of display when editing this field: 'list', 'select' (same as list), radio_horizontal', 'radio_vertical' or 'radio' (same as radio_vertical)
<field id="name" xsi:type="AttributeHierarchicalKey">	zero or more	An external key pointing to the same class, in order to build hierarchies of objects
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<on_target_delete>DEL_AUTO</on_target_delete>	mandatory	Define how the deletion of the target object will impact the current object. Allowed values are 'DEL_MANUAL' and 'DEL_AUTO'
<filter>SELECT Location AS L WHERE L.org_id = :this->org_id</filter>	optional	OQL query to define a set of object to which the key can point to. Use :this->name to refer to a value in the current object
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<max_combo_length>50</max_combo_length>	optional	The maximum number of elements in a drop-down list. If more then an autocomplete will be used. Defaults to the value given in the configuration file.
<min_autocomplete_chars>3</min_autocomplete_chars>	optional	The minimum number of characters to type in order to trigger the "autocomplete" behavior. Defaults to the value given in the configuration file.
<allow_target_creation>true</allow_target_creation>	optional	Displays the + button on external keys to create target objects. Defaults to the value given in the configuration file.
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<field id="name" xsi:type="AttributeExternalField">	zero or more	An alias to an attribute hold by another object (see "ExternalKey")
<extkey_attcode>name</extkey_attcode>	mandatory	External key pointing to the remote class. This attribute must be defined in the current class.
<target_attcode>name</target_attcode>	mandatory	The attribute of the remote class. Only some attribute types are supported. CaseLog, LinkedSet, LinkedSetIndirect amougst others aren't supported.
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeObjectKey">	zero or more	A flexible external key: a pointer to an object of any class. The main use case is to implement generic extensions, working with any type of object. As a consequence, it is aimed at being used programmaticaly, and no GUI has been developped for the end-user to select an object. Experimental and supported only since iTop 2.2.0.
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<class_attcode>name</class_attcode>	mandatory	The attribute which value gives the class of the objects to which the key is pointing for the current record. That attribute can be any type of attribute provided that its representation is a string (AttributeString, AttributeEnum, AttributeClass)
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeText">	zero or more	A multi-line text (limited to 64 Kb)
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<width>800px</width>	optional	New in 2.2.0 Width of the edition area. Possible values: 200px, 70em. Defaults to ''
<height>200px</height>	optional	New in 2.2.0 Height of the edition area. Possible values: 100px, 30em. Defaults to ''
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeLongText">	zero or more	A huge text (limited to 4 Gb)
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<width>800px</width>	optional	New in 2.2.0 Width of the edition area. Possible values: 200px, 70em. Defaults to ''
<height>200px</height>	optional	New in 2.2.0 Height of the edition area. Possible values: 100px, 30em. Defaults to ''
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeHTML">	zero or more	An HTML text (limited to 4 Gb)
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<width>800px</width>	optional	New in 2.2.0 Width of the edition area. Possible values: 200px, 70em. Defaults to ''
<height>200px</height>	optional	New in 2.2.0 Height of the edition area. Possible values: 100px, 30em. Defaults to ''
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeCaseLog">	zero or more	A case log is a discussion thread. Each message is labelled with the name of the talker and the current time
<sql>name</sql>	mandatory	Prefix of the columns (2) used to store the data into the MySQL database
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeLinkedSet">	zero or more	A set of objects pointing to the current object
<linked_class>name</linked_class>	mandatory	A class of objects having an external key pointing to the current object
<filter>SELECT Person AS P WHERE P.category = :this->category</filter>	optional	Not used by iTop for now! OQL query to define objects to which the current object can be linked. It's the counterpart of the //filter// on the corresponding ExternalKey.
<ext_key_to_me>name</ext_key_to_me>	mandatory	An external key attribute, defined on the linked class
<tracking_level>list</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, list (track added and removed items), details (track modified items), all. Defaults to 'list'
<edit_mode>actions</edit_mode>	optional	Define the type of GUI for editing this link set. Possible values: none, add_only, add_remove, actions, in_place. Defaults to 'actions'
<count_min>0</count_min>	optional	unused yet
<count_max>0</count_max>	optional	unused yet
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeLinkedSetIndirect">	zero or more	A set of objects related to the current object by the mean of a "link class"
<linked_class>name</linked_class>	mandatory	A class of objects having an external key pointing to the current object
<ext_key_to_me>name</ext_key_to_me>	mandatory	An external key attribute, defined on the linked class
<ext_key_to_remote>name</ext_key_to_remote>	mandatory	An external key attribute, defined on the linked class, and pointing to the remote object
<tracking_level>list</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, list (track added and removed items), details (track modified items), all. Defaults to 'all'
<duplicates>true</duplicates>	optional	Set to 'true' to allow duplicates. Defaults to 'false'
<count_min>0</count_min>	optional	unused yet
<count_max>0</count_max>	optional	unused yet
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeBlob">	zero or more	A blob, i.e. a binary string (limited to 4Gb). The name of the attribute is used as the prefix to name the columns used for storing the data.
<is_null_allowed>true</is_null_allowed>	optional	Set to "true" to let users leave this value undefined (default), false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeImage">	zero or more	Experimental! An image (limited to 4Gb). Supported only since iTop 2.3.0. The name of the attribute is used as the prefix to name the columns used for storing the data.
<display_max_width>128</display_max_width>	optional	When displaying an image which width exceeds this limit (given in pixels, defaulting to 128), the image gets resized in the browser (preserves the aspect ratio)
<display_max_height>128</display_max_height>	optional	When displaying an image height width exceeds this limit (given in pixels, defaulting to 128), the image gets resized in the browser (preserves the aspect ratio)
<storage_max_width>256</storage_max_width>	optional	When uploading an image which width exceeds this limit (given in pixels, defaulting to 256), the image gets resized (preserving the aspect ratio). PHP GD must be installed.
<storage_max_height>256</storage_max_height>	optional	When uploading an image which height exceeds this limit (given in pixels, defaulting to 256), the image gets resized (preserving the aspect ratio). PHP GD must be installed.
<default_image>images/nobody.png</default_image>	optional	Relative path to an image displayed when no image has been uploaded.
<is_null_allowed>true</is_null_allowed>	optional	Set to "true" to let users leave this value undefined (default), false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeInteger">	zero or more	An integer value
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributePercentage">	zero or more	A percentage (integer between 0 and 100), displayed as a bar
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeDecimal">	zero or more	A decimal value
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<digits>6</digits>	mandatory	Total number of digits
<decimals>2</decimals>	mandatory	Number of decimal digits
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeDuration">	zero or more	A duration, stored in seconds, displayed in days/hours/minutes/seconds
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeDate">	zero or more	A date (no time)
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeDateTime">	zero or more	A date and time
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeIPAddress">	zero or more	An IP address
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeURL">	zero or more	An URL (http...)
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<target>_blank</target>	mandatory	Target attribute as it will be set into the A tag (see HTML specs)
<validation_pattern>^[a-z]*\d+$</validation_pattern>	optional	Enforce a format based on a regular expression (slashes must be escaped). Defaults to the global setting 'url_validation_pattern'
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeStopWatch">	zero or more	Cumulate the time spent in some states
<states>	mandatory	States in which the stop-watch will be running
<state id="name">	zero or more	A state (as declared in the life-cycle of the class)
<goal>name</goal>	optional	Name of the class handling the computation of the time limit. Defaults to 'DefaultMetricComputer'
<working_time>name</working_time>	optional	Name of the class handling the computation of active times. Defaults to 'DefaultWorkingTimeComputer', which means 24x7
<thresholds>	mandatory	Intermediate milestones, defined as a portion of the overall time goal.
<threshold id="integer">	zero or more	A milestone. The id is a percentage of the overall duration limit (e.g. 80)
<actions>	mandatory	What must be done when the milestone is being passed.
<action>	zero or more	A milestone
<verb>DoThis</verb>	mandatory	Function (of the current PHP class)
<params>	mandatory	Arguments to be passed to the function
<param xsi:type="bool\|int\|float\|string\|reference">ev_close</param>	zero or more	A scalar argument (integer, float, boolean, string)
<highlight>	optional	The highlight code set when this threshold is reached, if any
<code>critical</code>	mandatory	The name of the higlight code (within the highlight scale)
<persistent>true</persistent>	mandatory	"true" or "false" Whether the highlight code remains applicable when the stopwatch is no longer active
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<field id="name" xsi:type="AttributeEncryptedString">	zero or more	A string, limited to one line of 255 characters, stored encrypted in the database. If the PHP mcrypt extension is present such fields are encrypted using the 'blowfish' algorithm, otherwise a weaker algorithm is used. All encrypted fields depend on the master key 'encryption_key' defined in the configuration file (make sure you never loose it!).
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<default_value>name</default_value>	mandatory	The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed>	mandatory	Set to "true" to let users leave this value undefined, false otherwise
<validation_pattern>^[a-z]*\d+$</validation_pattern>	optional	Enforce a format based on a regular expression (slashes must be escaped)
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeSubitem">	zero or more	One of the state information present in a stopwatch. Both must be defined in the same Class!
<target_attcode>name</target_attcode>	mandatory	The stopwatch (attribute code)
<item_code>100_passed</item_code>	mandatory	The information: timespent, started, laststart, stopped, _deadline, _passed, _triggered, _overrun
<dependencies>	optional	Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name">	mandatory	An attribute code
<field id="name" xsi:type="AttributeRedundancySettings">	zero or more	Settings for the redundancy on a relation. Supported only since iTop 2.2.0.
<sql>name</sql>	mandatory	The column used to store the value into the MySQL database
<relation_code>impacts</relation_code>	mandatory	Identifier/Part 1: the id of the relation
<from_class>name</from_class>	mandatory	Identifier/Part 2: the source class
<neighbour_id>name</neighbour_id>	mandatory	Identifier/Part 3: the id of the
<enabled>true</enabled>	mandatory	Set to "true" to enable the redundancy
<enabled_mode>name</enabled_mode>	mandatory	Set to "user" to let the end-user decide wether the redundancy can be enabled or not, or 'fixed' to keep the value as given by <enabled>
<min_up>1</min_up>	mandatory	Minimum count (resp. percentage) of upstream items that must be up
<min_up_type>name</min_up_type>	mandatory	How to interpret <min_up>: either "count" or "percent"
<min_up_mode>user</min_up_mode>	mandatory	Set to "user" to let the end-user change the values, or "fixed" to enforce the values given by <min_up> and <min_up_type>
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables>	optional	Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<field id="name" xsi:type="AttributeCustomFields">	zero or more	Custom fields handled by a custom module, developped on purpose. Supported only since iTop 2.3.0.
<handler_class>MyHandler</handler_class>	mandatory	Name of a PHP class derived from CustomFieldsHandler
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'

Attribute ExternalKey: edit mode

Edit mode	define the application behavior when editing the current object
<empty>	When no value is provided in the XML, iTop uses its default actions, see below for its behavior
add_remove	Allow to add existing objects = overwrite their ExternalKey with the id of the current object. It proposes a remove option which empty the ExternalKey unless the ExternalKey is mandatory.
in_place	You can create a new object in a modal pop-up window. You can also delete child objects assuming no other relationships prevents it
actions	Add Actions menus which in current window, allow to massively edit (modify or delete) the related objects, as well as create a new related object
add_only	Only allow to create a new related object in a separate window, independently of the current object edition, which can be cancelled or completed without effect on the creation.
none	That (1:n) relationship cannot be edited from the current object, it's in read-only mode

Presentation

Details

The presentation “details” defines the structure of the form used to enter an object and to display its “details”. It can be a simple list (in which case the fields are displayed in one column), but can also define columns and fieldset to group related fields together. Some type of attributes such as Caselog, LinkedSet, LinkedSetIndirect are automatically displayed either in a separate tab or as a full width table.

Tag	Usage	Description
<items>	mandatory
<item>	at least one	An item can be either: an attribute (id = attribute code), a column (id = col:number) or a field set (id = fieldset:dictionary entry)
<rank>123</rank>	mandatory	Display rank. Item are ordered from top to bottom, left to right. This must be an integer value.
<items>	optional	In case the item defined above is a column or a field set, then this tag must be defined to contain the items (recursively, though this recursion is limited).

Controlling the fields

Define simple ordered list of fields for controlling the default behavior of the application for listing and searching object of this class:

default-search: used as default search criteria when searching for objects of this class or its sub-classes if that list is not redefined below.
list: used as default columns when displaying lists of object
search: used as most popular search criteria for this class

Tag	Usage	Description
<items>	mandatory	An ordered list of attributes
<item id="name">	at least one	An attribute
<rank>123</rank>	mandatory	Rank of the attribute in the list (integer)

Stimuli

Each transition from one state to another (for objects with a life -cycle) is trigerred when the object receives a stimuli. The different types of stimuli are listed in the table below:

Tag	Usage	Description
<stimulus id="name" xsi:type="StimulusUserAction">	at least one	An action decided by the end-user. The stimuli is displayed in the Actions menu (if the object is in a state for which this stimuli is taken into account
<stimulus id="name" xsi:type="StimulusInternal">	at least one	An action that can be triggered programmatically.

Menus

The different types of menus are listed in the table below:

Use the triangle arrow on the left of an item to expand/collapse its definition.

Tag	Usage	Description
<menu id="name" xsi:type="MenuGroup">	optional	Top level menu. This menu will always remain visible. It is a container for other menus.
<rank>123.45</rank>	mandatory	Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top.
<enable_admin_only>1</enable_admin_only>	optional	If set to '1' then only administrators will see this menu entry
<enable_class>name</enable_class>	optional	Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter.
<enable_action>UR_ACTION_MODIFY</enable_action>	optional	One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given.
<enable_permission>UR_ALLOWED_YES</enable_permission>	optional	Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given.
<enable_stimulus>ev_assign</enable_stimulus>	optional	Bind to the rights to apply a given stimulus. Ignored if enable_class is not given.
<menu id="name" xsi:type="DashboardMenuNode">	optional	Dashboard. The contents can be produced by the mean of the "export" function. The contents of the dashboard can be found in a file (definition_file) or directly here (definition)
<rank>123.45</rank>	mandatory	Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top.
<enable_admin_only>1</enable_admin_only>	optional	If set to '1' then only administrators will see this menu entry
<parent>name</parent>	mandatory	Parent menu node, either a top node or an intermediate node
<definition_file>name</definition_file>	optional	Dashboard definition file. The path is relative to the module in which the menu is declared.
<definition>name</definition>	optional	Dashboard definition contents. This tag will be ignored if the tag definition_file has been given and is not empty.
<enable_class>name</enable_class>	optional	Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter.
<enable_action>UR_ACTION_MODIFY</enable_action>	optional	One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given.
<enable_permission>UR_ALLOWED_YES</enable_permission>	optional	Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given.
<enable_stimulus>ev_assign</enable_stimulus>	optional	Bind to the rights to apply a given stimulus. Ignored if enable_class is not given.
<menu id="name" xsi:type="NewObjectMenuNode">	optional	Shortcut to create a new object.
<rank>123.45</rank>	mandatory	Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top.
<enable_admin_only>1</enable_admin_only>	optional	If set to '1' then only administrators will see this menu entry
<parent>name</parent>	mandatory	Parent menu node, either a top node or an intermediate node
<class>name</class>	mandatory	Class of the object to create
<enable_class>name</enable_class>	optional	Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter.
<enable_action>UR_ACTION_MODIFY</enable_action>	optional	One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given.
<enable_permission>UR_ALLOWED_YES</enable_permission>	optional	Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given.
<enable_stimulus>ev_assign</enable_stimulus>	optional	Bind to the rights to apply a given stimulus. Ignored if enable_class is not given.
<menu id="name" xsi:type="SearchMenuNode">	optional	Shortcut to search for objects.
<rank>123.45</rank>	mandatory	Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top.
<enable_admin_only>1</enable_admin_only>	optional	If set to '1' then only administrators will see this menu entry
<parent>name</parent>	mandatory	Parent menu node, either a top node or an intermediate node
<class>name</class>	mandatory	Class of the objects to search for.
<enable_class>name</enable_class>	optional	Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter.
<enable_action>UR_ACTION_MODIFY</enable_action>	optional	One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given.
<enable_permission>UR_ALLOWED_YES</enable_permission>	optional	Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given.
<enable_stimulus>ev_assign</enable_stimulus>	optional	Bind to the rights to apply a given stimulus. Ignored if enable_class is not given.
<menu id="name" xsi:type="TemplateMenuNode">	optional	Deprecated. Kept for backward compatibility.
<rank>123.45</rank>	mandatory	Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top.
<enable_admin_only>1</enable_admin_only>	optional	If set to '1' then only administrators will see this menu entry
<parent>name</parent>	mandatory	Parent menu node, either a top node or an intermediate node
<template_file>name</template_file>	optional	Dashboard definition file. The path is relative to the module in which the menu is declared.
<enable_class>name</enable_class>	optional	Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter.
<enable_action>UR_ACTION_MODIFY</enable_action>	optional	One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given.
<enable_permission>UR_ALLOWED_YES</enable_permission>	optional	Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given.
<enable_stimulus>ev_assign</enable_stimulus>	optional	Bind to the rights to apply a given stimulus. Ignored if enable_class is not given.
<menu id="name" xsi:type="OQLMenuNode">	optional	Shortcut to display a search result, given an OQL query.
<rank>123.45</rank>	mandatory	Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top.
<auto_reload>standard</auto_reload>	optional	Determines how the display will be refreshed: "none" to disable this feature (default), "standard" or "fast" to refresh periodically based on the corresponding configuration setting, or "123" to refresh every 123 seconds.
<enable_admin_only>1</enable_admin_only>	optional	If set to '1' then only administrators will see this menu entry
<parent>name</parent>	mandatory	Parent menu node, either a top node or an intermediate node
<oql>SELECT UserRequest WHERE agent_id = :current_contact_id AND status NOT IN ("closed","resolved")</oql>	mandatory	Object query. The only context parameter available is "current_contact_id".
<do_search>1</do_search>	optional	If set to 1, then the search form is displayed, at the top of the page, above the search results.
<search_form_open>1</search_form_open>	optional	If set to 1 - and if do_search is also set to 1, then the search form is fully open at the top of the page, otherwise the search pane is collapsed. Available since iTop 2.3.0. The default value depends of iTop version (From 2.3.0 to 2.4: collapsed, Since 2.5.0 : opened)
<enable_class>name</enable_class>	optional	Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter.
<enable_action>UR_ACTION_MODIFY</enable_action>	optional	One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given.
<enable_permission>UR_ALLOWED_YES</enable_permission>	optional	Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given.
<enable_stimulus>ev_assign</enable_stimulus>	optional	Bind to the rights to apply a given stimulus. Ignored if enable_class is not given.
<menu id="name" xsi:type="WebPageMenuNode">	optional	An hyperlink to a page internal or external to iTop.
<rank>123.45</rank>	mandatory	Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top.
<enable_admin_only>1</enable_admin_only>	optional	If set to '1' then only administrators will see this menu entry
<parent>name</parent>	mandatory	Parent menu node, either a top node or an intermediate node
<url>$$https://www.openitop.com/</url>	optional	URL to the page within the module. Prefix by a $$ to specify an absolute URL. Prefix by a $ to specify an URL relative to the iTop root URL. No prefix: relative to the module directory
<enable_class>name</enable_class>	optional	Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter.
<enable_action>UR_ACTION_MODIFY</enable_action>	optional	One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given.
<enable_permission>UR_ALLOWED_YES</enable_permission>	optional	Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given.
<enable_stimulus>ev_assign</enable_stimulus>	optional	Bind to the rights to apply a given stimulus. Ignored if enable_class is not given.
<menu id="name" xsi:type="ShortcutContainerMenuNode">	optional	Container for shortcuts. Only one container must be defined. The effects are unpredictable is several menus of this type are defined!
<rank>123.45</rank>	mandatory	Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top.
<enable_admin_only>1</enable_admin_only>	optional	If set to '1' then only administrators will see this menu entry
<parent>name</parent>	mandatory	Parent menu node, either a top node or an intermediate node
<enable_class>name</enable_class>	optional	Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter.
<enable_action>UR_ACTION_MODIFY</enable_action>	optional	One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given.
<enable_permission>UR_ALLOWED_YES</enable_permission>	optional	Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given.
<enable_stimulus>ev_assign</enable_stimulus>	optional	Bind to the rights to apply a given stimulus. Ignored if enable_class is not given.

WebMenu example

With relative url:

<menus>
  <menu id="Ongoing approval" xsi:type="WebPageMenuNode">
    <rank>6</rank>
      <parent>RequestManagement</parent>
      <url>$pages/exec.php?exec_module=approval-base&amp;exec_page=report.php&amp;class=UserRequest&amp;do_filter_my_approvals=on</url>
  </menu>
</menus>

Action grants

Grants are the basic elements that define the rights associated with a specific action for a given profile. The different actions that can be “granted” are listed in the table below:

Tag	Usage	Description
<action id="action:read">allow</action>	optional	Read: set to "allow" or "deny"
<action id="action:write">allow</action>	optional	Write: set to "allow" or "deny"
<action id="action:delete">allow</action>	optional	Delete: set to "allow" or "deny"
<action id="action:bulk read">allow</action>	optional	Export data: set to "allow" or "deny"
<action id="action:bulk write">allow</action>	optional	Perform massive changes: set to "allow" or "deny"
<action id="action:bulk delete">allow</action>	optional	Perform bulk deletion: set to "allow" or "deny"
<action id="stimulus:name">allow</action>	optional	Apply a given stimulus: set to "allow" or "deny"

Files

New in 2.0.1

The “files” structure allow to embed binary files (for examples image files used for the object's icons) directly in an XML delta definition file.

Use the triangle arrow on the left of an item to expand/collapse its definition.

Tag	Usage	Description
<file id="??">	zero or more	One entry per binary file.
<name>server.png</name>	mandatory	The name of the file.
<mimeType>image/png</mimeType>	mandatory	The MIME Type of the file.
<data>iVBORw0KGgoAAAANSUhEUgAAADAAA...</data>	mandatory	The binary content of the file, base64 encoded.

Dictionaries

New in 2.0.1

The “dictionaries” structure allows to add dictionary entries to the XML delta in order to define (or to alter) the localization of the data model.

Use the triangle arrow on the left of an item to expand/collapse its definition.

Tag	Usage	Description
<dictionary id="language_code">	at least one	One entry per language. The id is the language code: 'EN US', 'FR FR', etc.
<entries>	mandatory
<entry id="string_code"><![CDATA[Server Name]]></entry>	at least one	An entry in the dictionary. string_code is the identifier of the string to translate. For example Class:Server/Attribute:name

Modules parameters

New in 2.2.0

The “modules parameters” structure allows to define default configuration parameters, directly into the XML. These parameters will be turned into a PHP structure by the compiler and read as default values by the method MetaModel::GetModuleSetting.

The possible type of value that can be stored as parameters are: string, boolean (or bool), integer (or int), float, hash or array.

The syntax for the parameters is the following:

Use the triangle arrow on the left of an item to expand/collapse its definition.

Tag	Usage	Description
<module_parameters>	optional	The location for string module specific parameters
<parameters>	mandatory
<parameter_name type="string\|int\|bool\|float\|hash\|array">	at least one	The parameter to define. The name of the tag is the name of the parameter

The string, integer, boolean and float types are simple scalar types. The value for the parameter is the content of the tag in plain text. The hash and array types are complex types composed of sub-elements. Each sub element is expressed as a sub tag in the XML. The main difference between hash and array is that a hash contains named values (based on the tag name) whereas an array contains a list of unnamed but ordered values. Inside a hash the tag names must be unique. Inside an array all the items must have the same tag name.

array items can be order based on their id (in ascending order, treated as a floating point number)

Example:

<parameters id="itop-object-copier" _delta="define">
  <rules>
    <rule id="0" type="hash">
      <source_scope>SELECT UserRequest WHERE status IN ("assigned", "pending")</source_scope>
      <allowed_profiles>Administrator,Support Agent</allowed_profiles>
      <menu_label>Issue a change ticket...</menu_label>
      <form_label>Issue a change from request %1$s. Please review the description before create the change ticket. After creation of the change ticket, the request ticket will be automatically updated. </form_label>
      <report_label>Issued from the request %1$s. The request has been updated.</report_label>
      <dest_class>Change</dest_class>
      <preset type="array">
        <action id="0"> clone(contacts_list,functionalcis_list,org_id,title,caller_id)</action>
        <action id="1">set(description,Original description:\n$this->description$)</action>
      </preset>
      <retrofit type="array">
        <action id="0">copy(id, parent_change_id)'</action>
        <action id="1">set(private_log,Issued change $this->ref$)'</action>
      </retrofit>
    </rule>
  </rules>
</parameters>

string is assumed to be the default type for tags without child subtags, whereas hash is the default type for tags with child subtags.

Other modules

Module name	details on parameters to configure this module
itop-ticket & itop-config-mgmt	configuring Impact Analyses
itop-attachments	configuring Attachments

Modules designs

New in 2.3.0

The “modules designs” structure allows to define/customize the behavior of a module. That behavior is encoded as an XML structure having the same formal constraints as any other itop_design XML structure. That XML structure, called a module design is accessed by the module by the mean of the class ModuleDesign.

The syntax for the module designs is the following:

Use the triangle arrow on the left of an item to expand/collapse its definition.

Tag	Usage	Description
<module_designs>	optional
<module_design id="??">	at least one	Container node for a set of design data. The identifier must be unique. It can match the name of the module, but any string is allowed provided that it does not contain slashes or backslashes

Files can be specified by the mean of a fileref node (see files section), or a path relative to the modules root directory (env-production).

This capability has been introduced for the sake of customizing the Enhanced Customer Portal shipped with iTop. See the customer portal XML reference.

Changes history

The version number of the XML format is set on the root node <itop_design version=“…”> This version number is used by iTop to convert into the latest format prior to compiling the data model into PHP files.

Version 1.0

The datamodel became editable with iTop 2.0 released in summer 2012

The version number was not defined in the XML file, thus the absence of version is now interpreted as “1.0”.

The version remained unchanged though a few new features have been introduced. Here is the list of releases and the new nodes:

iTop 2.0.1
- itop_design/files
- itop_design/dictionaries

iTop 2.0.2
- itop_design/branding
- itop_design/constants
- itop_design/classes/class/properties/indexes
- itop_design/classes/class/fields/field/always_load_in_tables

iTop 2.0.3
- itop_design/classes/class/fields/field[@xsi:type=“AttributeExternalKey”]/display_style

Version 1.1

This version came live with iTop 2.1.0, released in november 2014.

Finer granularity

id attributes have been added to a number of nodes, allowing for a finer granularity of the alterations that can be performed.

/classes/class/fields/field[@xsi:type=“AttributeEnum”]/values/value: added an id to the node <value id=“…”>
/classes/class/lifecycle/states/state/transitions/transition: stimulus sub-node removed in favor of an id on the node <transition id=“…”>
/classes/class/fields/field[@xsi:type=“AttributeStopWatch”]/thresholds/threshold: percentage sub-node removed in favor of an id on the node node <threshold id=“…”>
/user_rights/profiles/profile/groups/group/actions/action: the type and the name of the “granted” action are now expressed directly by the id, the attribute “xsi:type” has been removed.

Easier edition

Editing the lifecycle of tickets was a pain because of the attributes state flags were given as a complete matrix (e.g. 6 x 15 = 90 definitions to maintain). Though this is still feasible, there is now an alternative: define a state a inherited from another one, so that all the flags will be inherited and only the differences must be explicitely defined.

/classes/class/lifecycle/states/state/inherit_flags_from

The flags Must Prompt and Must Change are never inherited from one state to another.

Highlighting

Tickets or any objects having a lifecycle can be highlighted depending on their state or the state of their stop watches (SLA counters like Time to own)

See the nodes:

classes/class/lifecycle/highlight_scale
classes/class/lifecycle/states/state/highlight
classes/class/fields/field[xsi:type=AttributeStopWatch]/thresholds/threshold/highlight

Version 1.2

This version came live with iTop 2.2.0, released in september 2015.

A new type of field has been added: itop_design/classes/class/fields/field[@xsi:type=“AttributeObjectKey”].

The relations can now be modelized in XML (used to rely on overloading the method GetRelationQueries): itop_design/classes/class/relations. The redundancy on a relation is defined by the mean of a new type of attribute: itop_design/classes/class/fields/field[@xsi:type=“AttributeRedundancySettings”]

The access to the portal user interface is now defined in XML. This also allows to define several portals (for different profiles of end-users) as well to replace the existing portal by a specific user interface provided by a module. See itop_design/portals.

Specify a default value for configuration parameters using the new section itop_design/modules_parameters.

Small snippets of PHP codes can be injected inside the model.xxx.php files using the new tag itop_design/snippets.

Width and height can be set on Attributes of type AttributeText, AttributeLongText and AttributeHTML.

Version 1.3

This version came live with iTop 2.3.0 beta, released in may 2016.

Introduced a new value for _delta: if_exists.

Added module designs, allowing for the module to benefit from the XML delta mechanism (as opposed to a behavior defined as parameters or the configuration file): modules_designs/module_design[id=xxxxxxx]/…

Added attribute types:

AttributeMetaEnum: aggregates the values from other enums (usually found in derived classes). Example: the status of a ticket.
AttributeCustomFields: enables the development (yes, requires PHP development skills) of a module that would be responsible for storing/fetching custom attributes.
AttributeImage: (experimental!) enhances the existing AttributeBlob. Limitations: what if no default image has been provided? what if the user uploads a file that is not an image? When changing the image on IE9/IE10, the image is not previewed (those browser do not support the FileReader API)

New option for OQL Menu Nodes:

The option search_form_open has been added to show/hide the search form at the top of the page.

Version 1.4

This version came live with iTop 2.4 beta, released in July 2017.

Introduced a new value for _delta: forced.

Added 2 class properties: archive/enabled and obsolescence/condition
Added flags on transition
Added multiple changes on Portal XML

Version 1.5

This version came live with iTop 2.5 beta, released in May 2018.

Added 4 menu properties for all menu nodes: enable_class, enable_action, enable_permission and enable_stimulus
Changed default value of search_form_open to 1
Added a default_search section to the presentation (in class) in order to display default search criteria on search screens.
Default criterion on Standard Classes

Sidebar

XML Data Model Reference

Principles

Alter node contents

Rename a node

XML general structure

Fields

Attribute ExternalKey: edit mode

Presentation

Details

Controlling the fields

Stimuli

Menus

WebMenu example

Action grants

Files

Dictionaries

Modules parameters

Other modules

Modules designs

Meta

Changes history

Version 1.0

Version 1.1

Finer granularity

Easier edition

Highlighting

Version 1.2

Version 1.3

Version 1.4

Version 1.5

Table of Contents