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

Consider browsing to iTop 3.2 documentation

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:

  1. 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,
  2. 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.

Search in the XML:
Tag Usage Description
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.4"> 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> 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
<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 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 (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.

Search in the XML:
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="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 fieldsset to group related fields together.

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

Search in the XML:
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.

Search in the XML:
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:

Search in the XML:
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.

do

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.

Search in the XML:
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_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 all the rights specified by enable_action described hereafter.
<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 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. Default is collapsed. Available since iTop 2.3.0
<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

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:

Search in the XML:
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.

Search in the XML:
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.

Search in the XML:
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.

Search in the XML:
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.

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.

Search in the XML:
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.

Meta

Usage of this tag is restricted to Combodo for driving ITSM Designer behavior.
It is used to declare in XML stuff which are in PHP code and need to be known and manipulate by the ITSM Designer.

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
2_4_0/customization/xml_reference.txt · Last modified: 2018/12/19 11:40 by 127.0.0.1
Back to top

Table of Contents

Contact us
Contact us