You are browsing the documentation for iTop 2.0 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

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.

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.

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

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

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.

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 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:

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

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

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
2_0_3/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