Sidebar

Using iTop

Creating your iTop

iTop Customization

"How to" examples
DataModel

User Interface

Automation & Ticket management

Portal Customization

:: Version 3.2.0 ::

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

To customize User portal, here is the Portal XML reference

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. Stop processing if node does not exist. Do not provide any child nodes under this one
delete_if_exists Delete this node. Do not provide any child nodes under one having this delta
force New in 2.4.0 - 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.

When there can be multiple nodes with the same tag, under a single node, we call this a collection

When the nodes of a collection have no id, then there is no way to add a node in the collection, the complete collection must be redefine.

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="3.0"> mandatory Structural node. No comments are allowed before this tag. Compare to previous version, see details of changes due to Version_30
<classes> mandatory Declared classes
<class id="name"> zero or more Declaration of class
<parent>cmdbAbstractObject</parent> mandatory Parent class. See Class properties inheritance
<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</category> optional Usages that will be made of this class. See Class categories
<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> 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
<complementary_attributes> optional Define the list of attributes used to complete the friendly name of an object to differentiate duplicates. By default, the complement is empty. You can specify a format by adding a dictionary entry 'Class:<myClass>/ComplementaryName'. 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 additional information would depend on the language of the end-user. Note that the order matters. You can also define a long friendlyname with all the attributes of naming with the dictionary entry 'Class:<myClass>/LongName'. Supported only since iTop 3.0.0.
<attribute id="name"> at least one
<fields_semantic> optional Define the attributes carrying some aspect of the class (eg. image, state, ...)
<image_attribute> optional Attribute code carrying the image that should represent the object (must be declared as AttributeImage). If not define, the class icon will be used when necessary
<state_attribute> optional Attribute code carrying the object state, mandatory if there is a lifecycle, attribute must be an Enum of the current class. If node is not defined here but in a parent class, it is inherited
<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.
<style> optional Specify the style of the class (colors and icon). Supported only since iTop 3.0
<icon>../../images/user-request.png</icon> optional Specify an icon for your class (relative path from module root).
<main_color>#4E79A5</main_color> optional Main color for the class, can be any valid CSS color (hexa, rgba, hsla but not variable) or an SCSS variable.
<complementary_color>#FFFFFF</complementary_color> optional Complementary color for the class, can be any valid CSS color (hexa, rgba, hsla but not variable) or an SCSS variable.
<reconciliation> mandatory Define the default reconciliation scheme for data import.
<attributes> mandatory List of attributes used for the reconciliation.
<attribute id="name"> at least one
<indexes> optional Define table indexes
<index id="name"> zero or more To explicitly force a database index to be created with all specified attributes in the declared order.
<attributes> mandatory List of attributes used for the index. The order matters.
<attribute id="name"> at least one
<archive> optional Archival configuration.
<enabled>true</enabled> mandatory Applicable on root classes only. Set to true to make this class and all its descendant archivable (adds two magic attributes: archive_flag and archive_date). Attempting to set false when any of the parent has enabled=true will lead to an error at runtime
<obsolescence> optional Obsolescence configuration. As soon as the obsolescence is defined for a class, two magic attributes are added (obsolescence_flag and obsolescence_date), all classes in the hierarchy have the flag (defaulting to "No")
<condition><![CDATA[status='closed']]></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.
<uniqueness_rules> optional Rules that will be used when saving an object to check for its uniqueness
<rule id="name"> at least one
<attributes> mandatory List of attributes values that should be unique.
<attribute id="name"> at least one
<filter><![CDATA[status = 'active']]></filter> optional OQL condition to restrict the amount of checked objects
<disabled> optional Can be used to temporarly disable the rule. When overriding this attribute on an existing rule, only this can be defined.
<is_blocking> optional If the rule fails to verify, then if this value is true the object won't be saved, otherwise it will. Default to true.
<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. In 3.0 "lifecycle/attribute" tag was replaced by "fields_semantic/attribute_state"
<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
<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 Identifier must be the stimulus id used to trigger that transition, then provide the target state and the actions to perform.
<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. See examples in section Actions on 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
<param xsi:type="string|int|float|reference"> zero or more The value of the parameter
<event_listeners> optional **New in 3.1** List of the methods used as listeners
<event_listener id="name"> zero or more Event listener
<event>EVENT_DB_CREATE_DONE</event> mandatory Event name
<callback>OnUserRequestCreateDone</callback> optional Current class method of type EventListener that will be called when the event is triggered. The method signature must be: public function MyMethod(Combodo\iTop\Service\Events\EventData $oEventData)
<code>function(Combodo\iTop\Service\Events\EventData $oEventData) {}</code> optional Callback function to execute (choose at least 'callback' or 'code')
<rank>0</rank> mandatory Rank to call the listener for the same event
<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, EventListener (3.1), Overload-cmdbAbstractObject, Overload-iDisplay, Overload-DBObject, Overload-ExNihilo, Custom
<arguments> optional This tag is mandatory for lifecycle actions, even if the method has no argument
<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 highly 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 System AS s JOIN SoftwareInstance AS si ON si.system_id = s.id WHERE si.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> mandatory Refer to Presentation
<search> mandatory Ordered list of attributes shown in the 'Most popular' section of the 'Add new criteria' menu of search screens
<items> mandatory Refer to Presentation (search, default-search or list)
<default_search> optional Ordered list of default search criteria shown in search screens. This parameter is inherited from parent class if left empty or not existing.
<items> mandatory Refer to Presentation (search, default-search or list)
<list> mandatory Ordered list of attributes shown by default in result lists
<items> mandatory Refer to Presentation (search, default-search or list)
<summary> optional Ordered list of attributes displayed in external key pop-up overview. Since iTop 3.1
<items> mandatory Refer to Presentation (search, default-search or list)
<custom_presentations> optional Custom list of attributes brought by extensions. Since iTop 3.1
<custom_presentation id="my-custom-list-unique-id"> zero or more ID **MUST** be different than standard list names (details, list, ...). See ''/itop_design/meta'' section for how to provide a description of your list.
<items> mandatory Refer to Presentation (search, default-search or list)
<menus> mandatory Declaration of the menus shown in the main GUI (left pane)
<menu> at least one Declaration of a menu. See the various types of menus in section Menus
<user_rights> mandatory Implementation of the user rights policy: users will have one or more profiles, granting them access rights.
<groups> mandatory Groups are sets of classes. Grants are given based on this grouping - see "profiles"
<group id="name"> at least one A set of classes.
<classes> mandatory List of classes found in the group
<class id="name"> zero or more
<profiles> mandatory Profiles that will be listed in the application. A user can have one or more profiles. The profile "administrator" is always present and cannot be redefined.
<profile id="123"> at least one A usage profile.
<name>Configuration Manager</name> mandatory Name of the profile as it will be shown in the application. No translation is possible.
<description>Person in charge of the documentation of the managed CIs</description> mandatory Description of the profile (one line) as it will be shown in the application. No translation is possible.
<groups> mandatory Grants associated to the profile
<group> at least one Group for which grants must be defined
<actions> mandatory Allowed actions for the profile/group
<action> at least one See the various types of grant in section Action grants
<files> optional For embedding binary files (like icons) in the XML. Supported only since iTop 2.0.1
<file> at least one Declaration of file, see details in the section Files
<dictionaries> optional For adding localizations into the XML. Supported only since iTop 2.0.1
<dictionary> at least one Declaration of dictionary for a given language, see details in the section Dictionaries
<branding> optional Appearance of the GUI. For Logo define as a PNG file (path relative to the modules root directory = env-production), or fileref tag (see details in the section Files)
<main_logo> optional Logo for the main GUI (top left corner) when the menu is expanded. Dimensions: max width 310px, max height 70px.
<main_logo_compact> optional Top left corner logo when the console menu is collapsed. Dimensions: width 37px, height 37px.
<login_logo> optional Logo for the login page. Dimensions : max width 300px, max height 54px (div#login-logo)
<portal_logo> optional Logo for the customer portal. Dimensions: max width 192px (.col-sm-3 width 26%% and media query 768px), max height 50px (img tag).
<main_favicon> optional Favicon (icon in the browser tab) used in the main GUI and by default for other GUIs. Since iTop 3.2.0.
<portal_favicon> optional Favicon (icon in the browser tab) used in the end-users portal. Since iTop 3.2.0.
<login_favicon> optional Favicon (icon in the browser tab) used in the login page. Since iTop 3.2.0.
<themes> mandatory Themes main node to custom iTop's look. Since iTop 2.7.0
<theme id="light-grey"> at least one Defines a theme with an unique id for iTop.
<variables> optional Set of variables to redefines (refer to imports files to know which variables can be redefined)
<variable id="combodo-orange">purple</variable> optional Variable to redefine and its new value
<imports> mandatory Set of variables to import.
<import id="css-variables" xsi:type="variables|utilities">../css/css-variables.scss</import> at least one Path to scss variable file to import.Path is relative to env-*/.Attribute xsi:type since 3.0
<stylesheets> mandatory Set of stylesheets to compile. Declaration order matters.
<stylesheet id="jqueryui">../css/ui-lightness/jqueryui.scss</stylesheet> at least one Path to scss stylesheet to import. Path is relative to env-*/
<stylesheet id="main">../css/light-grey.scss</stylesheet> at least one Path to scss stylesheet to import. Path is relative to env-*/
<precompiled_stylesheet>itop-structure/precompiled-themes/light-grey/main.css</precompiled_stylesheet> optional See theme_compilation for details
<themes_common> mandatory **New in 3.1** Global theme rules compiled with every theme declared in themes node. Can contain same content as a theme node.
<variables> optional Set of variables to redefines (refer to imports files to know which variables can be redefined)
<variable id="combodo-orange">purple</variable> optional Variable to redefine and its new value
<imports> mandatory Set of variables to import.
<import id="css-variables" xsi:type="variable|utility">../css/css-variables.scss</import> at least one Path to scss variable file to import.Path is relative to env-*/.Attribute xsi:type since 3.0
<stylesheets> mandatory Set of stylesheets to compile. Declaration order matters.
<stylesheet id="jqueryui">../css/ui-lightness/jqueryui.scss</stylesheet> at least one Path to scss stylesheet to import. Path is relative to env-*/
<stylesheet id="main">../css/light-grey.scss</stylesheet> at least one Path to scss stylesheet to import. Path is relative to env-*/
<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
<presentation> optional
<custom_presentations> optional
<custom_presentation id="my-custom-list-unique-id"> zero or more
<description> mandatory Description of the custom list introduced in ''/itop_design/classes//class/presentation/custom_presentations/custom_presentation''
<events> optional **New in 3.1** Event definition list
<event id="name"> zero or more Event definition
<description>An object insert in the database has been requested. All changes to the object will be persisted automatically.</description> mandatory description of the event
<sources> mandatory Sources of the event, used to filter the events before calling the listeners
<source id="name">cmdbAbstractObject</source> zero or more Source of the event (can be anything relevant like parent classes)
<replaces>DBObject::OnInsert</replaces> optional when previous extension callbacks are obsoleted
<event_data> mandatory Description of the data given with the event when a listener is called
<event_datum id="name"> zero or more Data name
<description>Specific information for this event</description> mandatory Data description
<type>array</type> mandatory PHP type of the data
<event_listeners> optional **New in 3.1** Global event listeners
<listener id="name"> mandatory Event Listener
<event>EVENT_DISPLAY_OBJECT_DETAILS</event> mandatory Event name
<filters> mandatory Event source filters
<filter>FAQ</filter> mandatory Event source filter
<priority>0</priority> mandatory Priority
<code>function(\Combodo\iTop\Service\EventData $oEventData) {}</code> mandatory Callback function to execute

Class properties inheritance

Please refer to the Class properties inheritence reference to check wether it is necessary for you to define a property or you can count on iTop to inherit that characteristic from the parent class.

Class categories

DBObject "category" values

Uniqueness rules

Uniqueness check is done in \DBObject::DoCheckUniqueness, by verifying the result of a query built in \DBObject::GetUniquenessDuplicatesQuery.

All scalar and non encrypted attribute types can be used in the /itop_design/classes/class/properties/uniqueness_rules/rule/attributes/attribute nodes. That includes for example :

  • AttributeString
  • AttributeEnum
  • AttributeEmailAddress
  • AttributePhoneNumber
  • AttributeExternalKey
  • AttributeInteger
  • AttributeDateTime
Error message is a dictionary entry, following this convention:
  • Class:<Class_name>/UniquenessRule:<rule_id>
  • Class:<Class_name>/UniquenessRule:<rule_id>+ for more information
Within this error message you can use placeholders like $this->attribute_code$
Condition is to be used with care as it is not checked on the current object but only on objects already existing in database
Uniqueness rules are checked whenever inserting new object or updating existing one, but no lock (iTopMutex) are used for performance reasons. So there might be use cases with concurrent access where the rule won't be triggered.

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="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="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="AttributeCustomFields"> zero or more Custom fields handled by a custom module, developed 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'
<field id="name" xsi:type="AttributeDashboard"> zero or more Dashboard field used to display information only. Supported only since iTop 2.6.0.
<is_user_editable>true</is_user_editable> optional Set to "true" to let users edit the dashboard. Defaults to 'true'
<definition_file>name</definition_file> optional Dashboard definition file. The path is relative to the module in which the class 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.
<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). If 'is_null_allowed' is set to 'true' then 'default_value' will be current_date
<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). If 'is_null_allowed' is set to 'true' then 'default_value' will be Now
<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="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. 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="AttributeEncryptedString"> zero or more A string, limited to one line of 255 characters, stored encrypted in the database. See AttributeEncryptedString for more informations
<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
<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
<sort_type> optional Type of sort applied to the values on display. Possible values are ''code'' (default), ''label'' or ''rank'' (in which case, see the rank node).
<values> mandatory List of possible values
<value id="name"> at least one Value and style. The id is used solely for identifying the XML node
<code>name</code> mandatory Value. Must be made of alphanumeric characters. Do not use '0' as it's treated as undefined. Other authorized characters: '_', '-'. Supported only since iTop 3.0
<rank>10</rank> optional Only if sort_type set to ''rank''. Rank of the value among the others. Must be an integer or a float. Supported only since iTop 3.1
<style> optional Specify the style of the value (colors and decoration icon). Supported only since iTop 3.0
<main_color>#4E79A5</main_color> mandatory Main color for the value, can be any valid CSS color (hexa, rgba, hsla but not variable) or an SCSS variable.
<complementary_color>#FFFFFF</complementary_color> mandatory Complementary color for the value, can be any valid CSS color (hexa, rgba, hsla but not variable) or an SCSS variable.
<decoration_classes>fas fa-user-tag</decoration_classes> mandatory Specify a blank separated list of css classes from FontAwesome 5 to decorate the value. Defaults to empty value.
<default_style> optional Specify the default style of the values (colors and decoration icon) when the values don't specify a style. Supported only since iTop 3.0
<main_color>#4E79A5</main_color> mandatory Main color for the values, can be any valid CSS color (hexa, rgba, hsla but not variable) or an SCSS variable.
<complementary_color>#FFFFFF</complementary_color> mandatory Complementary color for the values, can be any valid CSS color (hexa, rgba, hsla but not variable) or an SCSS variable.
<decoration_classes>fas fa-user-tag</decoration_classes> mandatory Specify a blank separated list of css classes from FontAwesome 5 to decorate the values. Defaults to empty 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 (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="AttributeEnumSet"> zero or more A string that is a set of values from a fixed set of possible values
<values> mandatory List of possible values
<value id="name"> at least one Value. The id is just identify the XML node
<code>name</code> mandatory Value. Alphanumeric characters, dash and underscore authorized. If the value is less than 3 characters, then it's prefixed with '_' or '__' to reach 3. Supported only since iTop 3.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
<tracking_level>all</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'
<max_items>12</max_items> mandatory Maximum number of tags allowed on an object. Default 12. Max value 255.
<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="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 amongst others aren't supported.
<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 object to which the external key is pointing. If the class does not exist, this field will silently be ignored.
<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. Since 3.0.0 it is no more required to declare such attributes in the dependencies property.
<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)
<create_temporary_object>false</create_temporary_object> optional Introduced in iTop 3.1.0 for future usages, does nothing for now.
<field id="name" xsi:type="AttributeHierarchicalKey"> zero or more An external key pointing to the same class, in order to build hierarchies of objects. Implementation of this attribute uses https://en.wikipedia.org/wiki/Nested_set_model
<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', 'DEL_AUTO' and 'DEL_MOVEUP'
<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="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 This tag has no effect (Width of the edition area)
<height>200px</height> optional When left empty, the whole content is displayed in view and print. If set in 3.0+ it applies on edit, **display and print** (so truncate content). Height of the edition area. Possible values: 100px, 30em.
<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 An image (limited to 4Gb). 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 (from the environment root like env-production) 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 A positive 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="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="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. If the class does not exist, the whole field will silently be ignored.
<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 'none' in case of a fresh install, 'list' otherwise - this to preserve backward compatibility while upgrading from a version older than 2.0.3. Could be overridden in configuration file with 'tracking_level_linked_set_default' parameter.
<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'
<edit_when>always</edit_when> optional Specify when the relation can be edited. Possible values: always, on_host_edition, on_host_display, never. It has an effect from iTop 3.1.1 only. This flag applies after edit_mode, if edit_mode=none, then edit_when value is ignored
<count_min>0</count_min> optional unused yet
<count_max>0</count_max> optional unused yet
<with_php_constraint>false</with_php_constraint> optional If true, there is a constraint checked by CheckToWrite related to the LinkedSet. Effective since 3.1.1. If tag omitted false is used
<with_php_computation>false</with_php_computation> optional If true, there is a computation triggered by EVENT_DB_LINKS_CHANGED event related to the LinkedSet. Present since 3.1.1. If tag omitted false is used
<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". The link class must contain an ExternalKey field pointing to the exact class declaring this LinkedSetIndirect field.
<linked_class>name</linked_class> mandatory A class of objects having an external key pointing to the current object. If the class does not exist, the whole field will silently be ignored.
<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'. Could be overridden in configuration file with 'tracking_level_linked_set_indirect_default' parameter.
<edit_when>always</edit_when> optional Specify when the relation can be edited. Possible values: always, on_host_edition, on_host_display, never. It has an effect from iTop 3.1.1 only.
<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
<display_style>tab</display_style> optional Display style for links. Possibles values: tab, property. 'tab' displays links in a table inside a tab, 'property' displays links in a multi selectable input. Defaults to 'tab'. Since 3.1.0
<with_php_constraint>false</with_php_constraint> optional If true, there is a constraint checked by CheckToWrite related to the LinkedSetIndirect. Effective since 3.1.1. If tag omitted false is used
<with_php_computation>false</with_php_computation> optional If true, there is a computation triggered by EVENT_DB_LINKS_CHANGED event related to the LinkedSet. Present since 3.1.1. If tag omitted false is used
<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
<sort_type> optional Type of sort applied to the values on display. Possible values are ''code'' (default), ''label'' or ''rank'' (in which case, see the rank node).
<values> mandatory List of possible values
<value id="name"> at least one Value and style. The id is used solely for identifying the XML node
<code>name</code> mandatory Value. Must be made of alphanumeric characters. Do not use '0' as it's treated as undefined. Other authorized characters: '_', '-'. Supported only since iTop 3.0
<rank>10</rank> optional Only if sort_type set to ''rank''. Rank of the value among the others. Must be an integer or a float. Supported only since iTop 3.1
<style> optional Specify the style of the value (colors and decoration icon). Supported only since iTop 3.0
<main_color>#4E79A5</main_color> mandatory Main color for the value, can be any valid CSS color (hexa, rgba, hsla but not variable) or an SCSS variable.
<complementary_color>#FFFFFF</complementary_color> mandatory Complementary color for the value, can be any valid CSS color (hexa, rgba, hsla but not variable) or an SCSS variable.
<decoration_classes>fas fa-user-tag</decoration_classes> mandatory Specify a blank separated list of css classes from FontAwesome 5 to decorate the value. Defaults to empty 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 (must be in the list of possible values).
<default_style> optional Specify the default style of the values (colors and decoration icon) when the values don't specify a style. Supported only since iTop 3.0
<main_color>#4E79A5</main_color> mandatory Main color for the values in css format
<complementary_color>#FFFFFF</complementary_color> mandatory Complementary color for the values in css format
<decoration_classes>fas fa-user-tag</decoration_classes> mandatory Specify a blank separated list of css classes from FontAwesome 5 to decorate the values. Defaults to empty value.
<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="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 programmatically, and no GUI has been developed 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="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="AttributePhoneNumber"> zero or more A phone number
<sql>name</sql> mandatory The column used to store the value into the MySQL database
<default_value>name</default_value> mandatory The default value (can be specified as an empty string)
<is_null_allowed>true</is_null_allowed> mandatory Set to "true" to let users leave this value undefined, false otherwise
<tracking_level>none</tracking_level> optional Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<always_load_in_tables>true</always_load_in_tables> optional Advanced: set to true for attributes that are always used by a plugin. Possible values: true, false. Defaults to 'false'
<validation_pattern>[0-9.\-\ \+\(\)]+</validation_pattern> optional Enforce a format based on a regular expression. Defaults to the global setting 'phone_number_validation_pattern'
<dependencies> optional Attributes on which the current attribute depends. This will be taken into account in the forms.
<attribute id="name"> mandatory An attribute code
<field id="name" xsi:type="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 whether 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="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="string">ev_close</param> zero or more A scalar argument (integer, float, boolean, string, reference)
<highlight> optional The highlight code set when this threshold is reached, if any
<code>critical</code> mandatory The name of the highlight 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="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. Warning : slash characters (''/'') mustn't 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="AttributeTagSet"> zero or more List of tags to associate to an object. Supported only since iTop 2.6.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
<max_items>12</max_items> optional Maximum number of tags allowed on an object. Default 12. Max value 255.
<tag_code_max_len>20</tag_code_max_len> optional Max length of tag code for this field. Default 20. Max value 255.
<tracking_level>all</tracking_level> optional Adjust the recording of changes (history tab). Possible values: none, all. Defaults to 'all'
<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 This tag has no effect (Width of the edition area)
<height>200px</height> optional When left empty, the whole content is displayed in view and print. If set in 3.0+ it applies on edit, **display and print** (so truncate content). Height of the edition area. Possible values: 100px, 30em.
<format>text</format> optional **New in 2.3.0** format of the text, either plain text or HTML. Defaults to 'text'. Possible values 'text', 'html'.
<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 This tag has no effect (Width of the edition area)
<height>200px</height> optional When left empty, the whole content is displayed in view and print. If set in 3.0+ it applies on edit, **display and print** (so truncate content). Height of the edition area. Possible values: 100px, 30em.
<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. Defaults to the global setting 'url_validation_pattern'. Warning : slash characters (''/'') mustn't 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

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

Tag: always_load_in_tables

  • Fields which are only meant to be displayed in list or details: Set it to no
  • Fields used to compute other attributes or used internally by methods: Set it to yes

As iTop relies on lazy loading when retrieving objects, it only loads the required attributes to minimize DB and memory impact. But, if a method tries to access a not loaded attribute, then it will retrieve the complete object from DB. When displaying a list, if a method is trying to access a not loaded attribute, iTop will make a DB query for each objects, which can be pretty time consuming.

Typically, when displaying a list of Ticket, the status and tto are always loaded even if not displayed, because they are used to compute the highlight scale (none, orange, red).

Tag: target_class & linked_class

If an ExternalKey, a LinkedSet or a LinkedSetIndirect field reference a class which does not exist in the datamodel, then iTop XML compilation process will ignore those fields silently. This behavior allow to simplify the writing of generic extension, which can auto-adapt to the variability of datamodel.

Attribute LinkedSetIndirect: duplicate

Purpose of duplicates= “false”: You don't want that the same objects can be linked twice, for eg Person “John Smith” belongs to the Team “Helpdesk” with one role, and should not be added to the same team with another role. The tricky point with the design is that if you don't make it symmetrical, you may from the Person attach the same PC twice to the same Person, because from that side, it's not controlled, if you don't flag the AttributeLinkedSetIndirect for no duplicates on both side of the relation.

AttributeEncryptedString

See Encrypted data

Presentation

Details

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

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

Other presentations

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

  • summary: When such tag is defined (added in XML 3.1), it is used to display a summary card of the object, when getting over an hyperlink to that object.
  • list: used as default columns when displaying lists of object
  • default_search: used as default search criteria when searching for objects of this class or its sub-classes if that list is not redefined below.
  • search (standard_search in PHP) : used as most popular search criteria for this class
  • my-zlist: (added in XML 3.1) an extension can bring its own custom zlist and use it for its own purpose.
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)

Lifecycle

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.

Actions on Transition

See Methods available for transitions for existing methods which can be called in XML as actions.

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

WebMenu example

With relative url:

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

Action grants

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

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

Branding

Logos

Example of XML to set up a logo using a fileref refencing a file

itop_design
  <files>
    <file id="cron_c8b5" xsi:type="File" _delta="define">
      <name>cron.png</name>
      <mime_type>image/png</mime_type>
      <width>37</width>
      <height>37</height>
      <!-- In tag 'data' provide the image encoded in base 64 -->
      <data>iVBORw0KGgoAAAANSUhEUgAAAL...</data>
    </file>
  </files>
  <branding>
    <main_logo_compact _delta="define">
      <fileref ref="cron_c8b5"/>
    </main_logo_compact>
  </branding>

Theme compilation

The precompiled_stylesheet allows to pass an already compiled CSS. The corresponding path is relative to one of those directories :

  • /datamodels/2.x
  • /extensions
  • /data/production-modules

To learn everything about CSS compilation, see Theme precompilation

Modules parameters

New in 2.2.0

Introduction

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 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 id="module_code"> 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

module_parameters

Q:Should you do an XML module_parameter or parameter in the module file ?

When creating a custom module, the module parameters can be defined in the module definition file (module.my-module.php) using the settings key.

When defining a parameter this way, at soon as the module is installed the parameter is written in the iTop config file. Any change to its default value won't be possible anymore.

When using a definition in XML with the module_parameters node, no value is written in the iTop config file, so the default value can be changed later on by a new module version.
Also, other modules can change the default value with an XML override if needed.

Parameter typing

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

string is assumed to be the default type for tags without child subtags, whereas hash is the default type for tags with child subtags.
If a type attribute is present in the original XML definition, it can be avoided in XML overrides

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 ordered based on their id (in ascending order, treated as a floating point number)

Example

Multiple module parameters, including array type ordered by id.

<module_parameters>
  <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>
</module_parameters>

Other modules

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

Modules designs

New in 2.3.0

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

The syntax for the module designs is the following:

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

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.

Known limitations

When creating a link class, be aware that this type of class does not support every type of fields. Also it seems obvious for multiple, some are more like a current limitation.
Unsupported fields:

  • Caselog
  • LinkedSet, LinkedSetIndirect
  • Text, HTML, Template,
  • File, Image
  • Duration
  • TagSet, EnumSet

Changes history

iTop versions introduce minor changes to the XML structure in order to ease the customization of iTop. iTop always supports older format (backward compatibility).

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.

New option for AttributeText:

  • The option format has been added to support the migration from plain text to HTML for the description of tickets.

Version 1.4

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

Introduced a new value for _delta: forced.

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

Version 1.5

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

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

Version 1.6

This version came live with iTop 2.6 beta, released in October 2018.

Version 1.7

This version came live with iTop 2.7, released in April 2020.

  • Added in_new_window property for WebPageMenuNode
  • Add of theme in branding
  • New field type: AttributeEnumSet which is kind of TagSet with allowed values defined in XML instead of database

Version 3.0

This version came live with iTop 3.0.0, released in January 2022

  • Add main_logo_compact in branding to specify a reduced console icon when menu bar is collapsed
  • Modify main_logo icon size from 220px / 64px to 310px / 70px
  • Add fields_semantic in class properties to define which attributes carry the state and image of the class
  • Add style in class properties to define the colors and image used to identify objects of the class
  • Move attribute_code from class lifecycle to class properties fields_semantic/state_attribute
  • Move icon from class properties to class style
  • Add precompiled_stylesheet to branding/themes/theme
  • Remove display_template from class properties as it wasn't use anymore
  • When using placeholders in external key filters, it is no more mandatory to declare the corresponding attributes in the dependencies of the external key (those dependencies are now computed, and it is still possible to declare other dependencies).
  • Change structure of the AttributeEnum, AttributeMetaEnum and AttributeEnumSet, code is now in a dedicated code subnode along with the style except for AttributeEnumSet which has no style
  • New in 3.0.1 The migration of XML format store the removed nodes (when upgrading) in the meta/previous_versions section, and restore the removed nodes (when donwgrading) from the information in the meta/previous_versions section.

Version 3.1

This version came live with iTop 3.1.0 released in July 2023

  • Add sort_type node to AttributeEnum and AttributeMetaEnum attributes
  • Add create_temporary_object node to AttributeExternalKey attribute
  • Add with_php_constraint node to AttributeLinkedSet and AttributeLinkedSetIndirect attributes
  • Add with_php_computation node to AttributeLinkedSet and AttributeLinkedSetIndirect attributes (version 3.1.1)
  • Add display_style node to AttributeLinkedSetIndirect attributes
  • Add Custom zlists :
    • itop_design/classes/class/presentation/custom_presentations/custom_presentation
    • itop_design/meta/presentation/custom_presentations/custom_presentation nodes
  • Add itop_design/classes/class/presentation/summary node for Summary zlist
  • Add itop_design/branding/themes_common node
  • Add new nodes for events :
    • itop_design/classes/class/event_listeners/event_listener
    • itop_design/events
    • itop_design/event_listeners

Version 3.2

This version came live with iTop 3.2.0 released in August 2024

  • Add itop_design/branding/main_favicon node
  • Add itop_design/branding/portal_favicon node
  • Add itop_design/branding/login_favicon node
3_2_0/customization/xml_reference.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1
Back to top

Table of Contents

Contact us
Contact us