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:
-
Load the XML data model files of the installed modules. The XML are combined into one single XML definition. It is important to figure out that, starting from an empty definition, iTop will merge each XML one by one,
-
Interpret the final combined definition.
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
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.
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
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
Condition
is to
be used with care as it is not checked on the current object but
only on objects already existing in databaseFields
The fields (also called attributes) are the actual data members of the objects. A field generally corresponds to one (or more) columns(s) in one table in the database. The different types of fields are listed in the table below:
Use the triangle arrow on the left of an item to expand/collapse its definition.
Tag | Usage | Description |
---|---|---|
<field id="name" xsi:type="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.
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 asmost 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.
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:
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.
Menus
The different types of menus are listed in the table below:
Use the triangle arrow on the left of an item to expand/collapse its definition.
Tag | Usage | Description |
---|---|---|
<menu id="name" xsi:type="MenuGroup"> | optional | Top level menu. This menu will always remain visible. It is a container for other menus. |
<rank>123.45</rank> | mandatory | Display rank. This is a float. Menus are ordered by ascending rank: the smallest rank is on top. |
<enable_admin_only>1</enable_admin_only> | optional | If set to '1' then only administrators will see this menu entry |
<enable_class>name</enable_class> | optional | Class to which the menu will be bound. The menu will be hidden to users who do not have all the rights specified by enable_action described hereafter. |
<enable_action>UR_ACTION_MODIFY</enable_action> | optional | One of the following flags: UR_ACTION_READ, UR_ACTION_MODIFY, UR_ACTION_DELETE, UR_ACTION_BULK_READ, UR_ACTION_BULK_MODIFY, UR_ACTION_BULK_DELETE. Ignored if enable_class is not given. |
<enable_permission>UR_ALLOWED_YES</enable_permission> | optional | Invert the rule by setting this value to UR_ALLOWED_NO. Defaults to UR_ALLOWED_YES. Ignored if enable_class is not given. |
<enable_stimulus>ev_assign</enable_stimulus> | optional | Bind to the rights to apply a given stimulus. Ignored if enable_class is not given. |
<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&exec_page=report.php&class=UserRequest&do_filter_my_approvals=on</url> </menu> </menus>
Action grants
Grants are the basic elements that define the rights associated with a specific action for a given profile. The different actions that can be “granted” are listed in the table below:
Tag | Usage | Description |
---|---|---|
<action id="action:read">allow</action> | optional | Read: set to "allow" or "deny" |
<action id="action:write">allow</action> | optional | Write: set to "allow" or "deny" |
<action id="action:delete">allow</action> | optional | Delete: set to "allow" or "deny" |
<action id="action:bulk read">allow</action> | optional | Export data: set to "allow" or "deny" |
<action id="action:bulk write">allow</action> | optional | Perform massive changes: set to "allow" or "deny" |
<action id="action:bulk delete">allow</action> | optional | Perform bulk deletion: set to "allow" or "deny" |
<action id="stimulus:name">allow</action> | optional | Apply a given stimulus: set to "allow" or "deny" |
Files
New in 2.0.1
The “files” structure allow to embed binary files (for examples image files used for the object's icons) directly in an XML delta definition file.
Use the triangle arrow on the left of an item to expand/collapse its definition.
Tag | Usage | Description |
---|---|---|
<file id="??"> | zero or more | One entry per binary file. |
<name>server.png</name> | mandatory | The name of the file. |
<mimeType>image/png</mimeType> | mandatory | The MIME Type of the file. |
<data>iVBORw0KGgoAAAANSUhEUgAAADAAA...</data> | mandatory | The binary content of the file, base64 encoded. |
Dictionaries
New in 2.0.1
The “dictionaries” structure allows to add dictionary entries to the XML delta in order to define (or to alter) the localization of the data model.
Use the triangle arrow on the left of an item to expand/collapse its definition.
Tag | Usage | Description |
---|---|---|
<dictionary id="language_code"> | at least one | One entry per language. The id is the language code: 'EN US', 'FR FR', etc. |
<entries> | mandatory | |
<entry id="string_code"><![CDATA[Server Name]]></entry> | at least one | An entry in the dictionary. string_code is the identifier of the string to translate. For example Class:Server/Attribute:name |
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.
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.type
attribute
is present in the original XML definition, it can be avoided in XML
overridesThe 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.
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 |
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
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
andenable_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.
Version 1.6
This version came live with iTop 2.6 beta, released in October 2018.
-
Added AttributeTagSet
-
Added AttributeDashboard
-
Added Uniqueness rules on Class properties
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 propertiesfields_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
andAttributeEnumSet
, code is now in a dedicatedcode
subnode along with thestyle
except forAttributeEnumSet
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
create_temporary_object
node toAttributeExternalKey
attribute -
Add
with_php_constraint
node toAttributeLinkedSet
andAttributeLinkedSetIndirect
attributes -
Add
with_php_computation
node toAttributeLinkedSet
andAttributeLinkedSetIndirect
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