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

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.

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	Check that this node already exists. Then examine the delta in its child nodes.
define	This is the first definition of this node. No flag should be found into its child nodes.
define_if_not_exists	It 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)

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.

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

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.

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.0">	mandatory	Structural node
<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 how the friendly name will be computed. A dictionary entry 'Class:/Name' defines how the attributes will be put together. The format is given as a printf formatting expression (e.g. '%1$s of %2$s'). By default, the friendly name will be rendered as a concatenation of the given attributes.
<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>	zero or more	Define the default reconciliation scheme for data import.
<attributes>	mandatory	List of attributes used for the index. The order matters.
<attribute id="name">	at least one
<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 Attributes
<lifecycle>	optional	Lifecycle: states and transitions
<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
<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 in 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>	at least one	For a given stimulus, defines the target state and the actions to perform
<stimulus>name</stimulus>	mandatory	Event triggering this transition
<target>name</target>	mandatory	State reached after the transition
<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)
<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
<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.
<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 search forms
<items>	at least one	Refer to Presentation (search or list)
<list>	mandatory	Ordered list of attributes shown by default in result lists
<items>	at least one	Refer to Presentation (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 (relative path), or fileref tag
<login_logo>	optional	Logo for the login page. Defined as a PNG file (relative path), or fileref tag
<portal_logo>	optional	Logo for the customer portal (top left corner). Defined as a PNG file (relative path), 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'.

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). Possibe 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="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>name</value>	at least one	Value. Must be made of alphanumeric characters. Other authorized 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 (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). Possibe 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="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). Possibe 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="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	To 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). Possibe 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="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). Possibe 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
<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). Possibe 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="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). Possibe 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="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	OQL query to define objects to which the current object can be linked. This query must match the query found in the corresponding external key. Use :this->name to refer to a value in the current object
<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). Possibe 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. Possibe 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
<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). Possibe 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
<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). Possibe 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="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). Possibe 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="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). Possibe 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="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
<decimal>2</decimal>	mandatory	Number of decimal digits
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possibe 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="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). Possibe 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="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). Possibe 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="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). Possibe 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="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). Possibe 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="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'
<thresholds>	mandatory	Intermediate milestones, defined as a portion of the overall time goal.
<threshold>	zero or more	A milestone
<percent>80</percent>	mandatory	Position of the milestone, relative to the overall duration limit
<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>	optional	Arguments to be passed to the function
<param>	zero or more	A scalar argument (number of string)
<tracking_level>none</tracking_level>	optional	Adjust the recording of changes (history tab). Possibe 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="AttributeEncrytpedString">	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). Possibe 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'

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 fieldsset to group related fields together.

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

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).

Presentation (search or list)

A simple ordered list of fields used when displaying lists of object (usage = list) or for displaying the search form for a given class (usage = seach)

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

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 enough rights for this class.
<enable_action>UR_ACTION_READ \| UR_ACTION_MODIFY</enable_action>	optional	Combination 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.
<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
<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.
<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 enough rights for this class.
<enable_action>UR_ACTION_READ \| UR_ACTION_MODIFY</enable_action>	optional	Combination 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 is executed by default when the user clicks on the menu.
<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>$$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 (buggy FIXME)
<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

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 xsi:type="read">allow</action>	optional	Read: set to "allow" or "deny"
<action xsi:type="write">allow</action>	optional	Write: set to "allow" or "deny"
<action xsi:type="delete">allow</action>	optional	Delete: set to "allow" or "deny"
<action xsi:type="bulk read">allow</action>	optional	Export data: set to "allow" or "deny"
<action xsi:type="bulk write">allow</action>	optional	Perform massive changes: set to "allow" or "deny"
<action xsi:type="bulk delete">allow</action>	optional	Perform bulk deletion: 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 allow to dictionary entries to the XML delta in order to define (or to alter) the localisation 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

Sidebar

XML Data Model Reference

Principles

XML general structure

Fields

Presentation (details)

Presentation (search or list)

Stimuli

Menus

Action grants

Files

Dictionaries

Table of Contents