Customer portal XML Reference

You must be familiar with the fundamentals of iTop XML design.

For an overview of the Customer Portal customization capabilities, please have a look at the page Customize your Customer Portal

Structure

This structure is specific to a portal developped over the itop-portal-base library.

Tag	Usage	Description
<module_design id="PORTAL_UNIQUE_ID" xsi:type="portal">	mandatory	Structural node defining configuration for a portal instance
<properties>	mandatory	Global properties of the instance
<name>portal:itop-portal</name>	mandatory	Portal name
<logo>../images/itop-logo.png</logo>	optional	Logo to use in the instance. If defined, will override the one from the Designer or env-xxx/branding/portal-logo.png
<themes>	mandatory	Declared CSS stylesheets
<theme id="custom">sample-portal-custom-css/custom.css</theme>	zero or more	List of CSS stylesheets. IDs bootstrap\|portal\|custom are loaded first, redefining them will override the default files. Then other IDs will be loaded. Path must be relative to /env-xxx
<templates>	mandatory	Declared TWIG templates
<template id="layout">sample-portal-alter-twig/layout.html.twig</template>	zero or more	List of TWIG template to override. Available values are "layout" for the whole page or "home" for the home page content. (Bricks content layout can be defined directly in each bricks)
<triggers_query>SELECT TriggerOnPortalUpdate AS t WHERE t.target_class IN (:parent_classes)</triggers_query>	mandatory	OQL query to retrieve triggers when updating an object on the instance
<attachments>	mandatory	Structural node
<allow_delete>true</allow_delete>	mandatory	Can the attachments be deleted on the portal. Available values are true\|false
<bricks>	mandatory	Declared bricks
<brick id="BRICK_UNIQUE_ID" xsi:type="Combodo\iTop\Portal\Brick\BrowseBrick">	zero or more	Declaration of a brick. ID must be unique through the collection. xsi:type must be the fully qualified class name (including the namespace). There can be several instances of a same xsi:type brick as long as their IDs are differents. See the various types of bricks in section Bricks (Note that only the common tags are displayed under this node)
<active>true</active>	optional	Is the brick active on the portal. Note that an active brick that is not visible on both the home page and the navigation menu can still be accessed from its URL. Available values are true\|false, default is true
<width>3</width>	optional	Width of the tile on the home page. Value must be an integer between 1-12, 12 being the whole row width. Default value is 3.
<rank>	optional	Rank of the brick on the home page and the navigation menu. If not specified, will be placed last.
<default>1</default>	optional	Rank on both home page and navigation menu. Value must be an float.
<home>1</home>	optional	Rank on the home page only. Value must be an float.
<navigation_menu>1</navigation_menu>	optional	Rank on the navigation menu. Value must be an float.
<title>	optional	Title of the brick on the home page and the navigation menu.
<default>Brick:Portal:Foo:Bar</default>	optional	Title on both home page and navigation menu.
<home>Brick:Portal:Foo:Bar</home>	optional	Title on the home page only.
<navigation_menu>Brick:Portal:Foo:Bar</navigation_menu>	optional	Title on both the navigation menu only.
<description>Brick:Portal:Foo:Bar+</description>	optional	Description of the brick that will be displayed on the home page.
<visible>	optional	Is the brick visible on the home page and the navigation menu. If not specified, default is true on both.
<home>true</home>	optional	Is the brick visible on the home page. Available values are true\|false, default is true
<navigation_menu>true</navigation_menu>	optional	Is the brick visible on the navigation menu. Available values are true\|false, default is true
<decoration_class>	mandatory	CSS classes for the brick's icon on the home page and the navigation menu. CSS classes from Glyphicon, Font Awesome or your own can be used.
<default>fa fa-user fa-2x</default>	optional	CSS classes applied on both home page and navigation menu.
<home>fa fa-user fa-2x</home>	optional	CSS classes applied on the home page.
<navigation_menu>fa fa-user fa-2x</navigation_menu>	optional	CSS classes applied on the navigation menu.
<security>	optional	Limitation on which profile can see this brick or not
<allowed_profiles>SELECT URP_Profiles WHERE name = 'Portal User'</allowed_profiles>	optional	List of Profiles objects which members can see this brick. If omitted, all Profiles not explicitly denied can see it
<denied_profiles>SELECT URP_Profiles WHERE name IN ('Power Portal User')</denied_profiles>	optional	Profiles which cannot see this brick.
<forms>	mandatory	Declared forms
<form id="name">	zero or more	Declaration of a form. ID must be unique
<class>ServiceSubcategory</class>	mandatory	Object class of the form. Child classes will inherit this form if they have none defined
<fields>	optional	Declared fields. If empty, only fields from twig tag will be displayed. If omitted only fields from zlist details will be displayed, twig tag will be ignored
<field id="title">	zero or more	Declaration of a field. ID must be a valid attribute code of the class. Will be placed one after the other if not placed in twig tag. Missing mandatory attributes will be automatically appended to the form
<slave>	optional	Is the field slave. If present, flag will be merged we those from the datamodel/lifecycle. Available values are true\|false, default is true
<read_only>	optional	Is the field read-only. If present, flag will be merged we those from the datamodel/lifecycle. Available values are true\|false, default is true
<mandatory>	optional	Is the field mandatory. If present, flag will be merged we those from the datamodel/lifecycle. Available values are true\|false, default is true
<hidden>	optional	Is the field hidden. If present, flag will be merged we those from the datamodel/lifecycle. Available values are true\|false, default is true
<must_prompt>	optional	Is the field must prompt. If present, flag will be merged we those from the datamodel/lifecycle. Available values are true\|false, default is true
<must_change>	optional	Is the field must change. If present, flag will be merged we those from the datamodel/lifecycle. Available values are true\|false, default is true
<twig>	optional	Form layout. HTML markup (with TWIG capabilities) to make a perfect form template. If not defined, fields will be placed one after the other.
<div class data-field-id="title">	zero or more	Place a div with an "data-field-id" attribute anywhere in the markup and the form will place the right input. Class tag is optional and allow you to style the field. data-field-id attribute must be a valid attribute code for the class
<modes>	optional	Declared modes. If not defined, form will be for all modes
<mode id="create">	zero or more	Defines in which modes the form will be available for this class. Available values are view\|edit\|create
<classes>	mandatory	Declared classes
<class id="Contact">	zero or more	Declaration of class. A class (or one of its ancestors) MUST be defined to be displayed in the instance. ID must be a valid Object class
<scopes>	mandatory	Declared scopes
<scope id="name">	zero or more	Declaration of scope. A scope defines the set of objects a Profile can access, they are cumulative regarding the user profiles
<oql_view>SELECT Contact WHERE org_id = :current_contact->org_id</oql_view>	mandatory	OQL query that defines the set of objects allowed to view
<oql_edit>SELECT Contact WHERE id = :current_contact_id</oql_edit>	optional	OQL query that defines the set of objects allowed to edit. Note that this apply only on the sub set from oql_view.
<allowed_profiles>	optional	Declared profiles that will have access to that scope. If this tag is not present, all profiles will have access to the scope.
<allowed_profile id="Portal User">	zero or more	Name of the Profile that will have access to that scope. ID must be unique and a valid Profile.
<lists>	optional	Presentation lists. As of today, used only in objects' LinkedSet in the portal.
<list>	zero or more	Declaration of list. ID must be unique.
<items>	mandatory	Declared attributes to show in the list.
<item id="status">	zero or more	Declaration of attribute. ID must be unique and must be a valid attribute code of the object class
<rank>10</rank>	optional	Rank of the attribute in the list. Lowest comes first.
<action_rules>	optional	Declared action rules. AR are actions that will be applied to an object / form in a specific brick, on a specific action. They can be combined.
<action_rule id="contact-to-userrequest">	zero or more	Declaration of action rule. ID must be unique.
<source_oql><![CDATA[SELECT Contact AS C WHERE C.id = :current_contact_id]]></source_oql>	optional	When copying values from a specific object to another, use this tag to specify the OQL query. (eg. The current contact) Note : Can't be used with source_oql.
<source_class>Service</source_class>	optional	When copying values from the clicked object in a brick, use this tag to specify the object class. (eg. The Service or ServiceSubCategory in the Services catalog) Note : Can't be used with source_oql.
<presets>	optional	Declared presets
<preset id="1">set(caller_id, $current_contact_id$)</preset>	zero or more	Declaration of a preset. ID mus be unique. When combined with source_oql\|source_class, will preset an attribute value of the object. Syntax is similar to ObjectCopier, supported verbs are set\|copy.

Bricks

Here are the features built it the itop-portal-base library. You may implement your own brick in a separate module, provided that its name (i.e. xsi:type) does not interfere with the existing bricks.

Tag	Usage	Description
<brick id="name" xsi:type="Combodo\iTop\Portal\Brick\UserProfileBrick">	mandatory	Connected user profile edition brick.
<form>	mandatory	Contact informations edition form for the connected user. Behave exactly like global forms of the portal, please check the corresponding section.
<brick id="name" xsi:type="Combodo\iTop\Portal\Brick\BrowseBrick">	zero or more	Navigate through an hierarchy of objects and specify actions for each levels (view or edit the object, create another object from this one). Navigation can be done from multiple views such as a regular list or a tree. An use case could be to browse the service catalog to find the one to create your request from.
<levels>	mandatory	Declared levels
<level id="name">	mandatory	Declaration of level. ID must be unique, integer are safer, avoid '-'
<class>ServiceFamily</class>	optional	Object class to display on this level. Optional if oql tag is present.
<oql><![CDATA[SELECT ServiceFamily]]></oql>	optional	OQL query to define a sub-set of an object class to display. Optional if source_class tag is present.
<title>	optional	Title for that level. Mainly used in list mode as column header.
<name_att>	?	Class attribute to be displayed as the object name. Default is "name"
<tooltip_att>	optional	Class attribute to be displayed in a tooltip
<fields>	optional	List of extra fields to be displayed in list mode
<field id="name">	zero or more	Class attribute to display as an extra information. Will be used when filtering. Must be a valid attrbiute code of the class
<actions>	optional	Available actions for objects of that level.
<action id="name" xsi:type="drilldown">	zero or more	ID must be unique. xsi:type defines the type of action. Available types are drilldown\|view\|create_from_this.
<levels>	optional	Optional sub levels. Must be linked to the parent level through an attribute
<level id="name">	mandatory	Declaration of sub level. Has the same tags as the parent level with the following as extras.
<parent_att>servicefamily_id</parent_att>	mandatory	Class attribute that linked the current class to the parent level's class
<browse_modes>	mandatory	List of browse modes
<availables>	mandatory	List of available browse modes
<mode id="name">	zero or more	Available browse mode. ID must be unique and a valid browse mode. Standard modes are list\|tree.
<default>list</default>	mandatory	Default browse mode. Must be one of the available browse modes
<data_loading>auto</data_loading>	mandatory	Defines how the data will be loading. Available values are auto\|full\|lazy. auto means that data will be loaded in one shot if their count is less than the "lazy_loading_threshold" module_parameter of the instance. full means that all data will be loaded at once. lazy means that data will be loaded dynamically at each page / level. This parameter shouldbe tuned to improve performances.
<brick id="name" xsi:type="Combodo\iTop\Portal\Brick\ManageBrick">	zero or more	Allows to manage objects by grouping them on 2 axis and edit them. Typically to manage the ongoing requests or a group of CIs.
<class>Ticket</class>	optional	Class of object to manage in the brick. Optional if oql tag is present.
<oql><![CDATA[SELECT Ticket]]></oql>	optional	OQL query to define the subset of object to manage in the brick. Optional if class tag is present.
<fields>	mandatory	List of attributes to display in the object list
<field id="name">	zero or more	Attribute to display in the list, will be used when filtering. ID must be a valid attribute of the class.
<grouping>	mandatory	Declared grouping.
<tabs>	mandatory	Grouping on tabs is done over an OQL query whereas grouping on tables is done on the finalclass.
<attribute>operational_status</attribute>	optional	Grouping on distinct values of an attribute. Optional if tag groups is present.
<groups>	optional	Grouping by explicit OQL queries. Optional if tag attribute is present.
<group id="name">	zero or more	Declaration of group
<rank>1</rank>	optional	Rank of the tab among the groups
<title>Brick:Portal:OngoingRequests:Tab:OnGoing</title>	mandatory	Title of the tab
<condition><![CDATA[SELECT Ticket AS T WHERE operational_status NOT IN ("closed", "resolved")]]></condition>	mandatory	OQL query that will be applied on the brick's object set to make that group
<data_loading>auto</data_loading>	mandatory	Defines how the data will be loading. Available values are auto\|full\|lazy. auto means that data will be loaded in one shot if their count is less than the "lazy_loading_threshold" module_parameter of the instance. full means that all data will be loaded at once. lazy means that data will be loaded dynamically at each page / level. This parameter shouldbe tuned to improve performances.
<brick id="name" xsi:type="Combodo\iTop\Portal\Brick\CreateBrick">	zero or more	Displays an object creation form.
<modal>true</modal>	mandatory	Should the form be in a modal dialog or on a whole page. Available values are true\|false, default is true.
<class>UserRequest</class>	mandatory	Class of the object to create.
<rules>	mandatory	Action rules to apply on the form.
<rule id="name">	zero or more	Declaration of action rule. ID must be unique. See Action Rule section for more informations.

Sidebar

Customer portal XML Reference

Structure

Bricks

Table of Contents