Portal customization overview

Since iTop 2.3.0 the portal comes with a brand new version that is fully customizable. This allows you to shape it so it fits perfectly your end-users needs with close to zero coding.

• Full XML configuration : No more PHP to adjust the configuration
• Customizable : From the configuration, to the look and feel
• Extensible : Add (and reuse) new functional features by developing bricks (as extensions) and configure them in the XML
• Multiple instances : Set multiple instances / configurations to fit your various end-users needs by giving them access to what they need only

You are a developper, consultant. You are already familiar with the fundamentals of iTop XML design.

Data security is based on the datamodel security layout, an instance cannot access more than the console allows to. Also, objects available for visualization and edition on the instance must be explicitly allowed, this helps you keep control over what the users can access.

Each instance of the portal has its own configuration, making them completely independents from one another.

An instance is made of several “bricks”, each enabling its own functional features like creating an object, browsing through a collection of objects, etc. Bricks have their own configuration but rely on the instance configuration and cannot override it.

There are 4 types of bricks available :

• CreateBrick : Displays an object creation form
• BrowseBrick : 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.
• ManageBrick : Allows to manage objects by grouping them on 2 axis and edit them. Typically to manage the ongoing requests or a group of CIs.
• UserProfileBrick : Displays a form with the current user information so he can edit some of them.

Several bricks of the same type can be added to a same instance with several configurations as long as they have different IDs. Also, more bricks can be developed to fit other needs (showing a picture, embedding an iframe or a video, …).

The configuration is made in the datamodel under the /itop_design/module_designs/module_design[@=“<PORTAL_ID>”] node.

The first thing you should do when configuring an instance is to set the scopes for all the objects that should be access in the portal. This will be the corner stone of all bricks logic. Not enabling an object class might end in an unexpected behavior from the bricks.

Scopes are pretty easy to defined once you have determine exactly what you want your users to view and edit.

1. Choose the object class
2. Specify an OQL query for the objects users can view
3. Optionally, specify an OQL query for the objects users can edit. That query will be apply to the subset of objects from the “viewing” query. If not specify, users will not be able to edit objects of this class.
4. Optionally, specify allowed user profiles for this scope. This means that you can allow different scopes depending on the user's profiles.

Now that scopes are defined, you need to define how those objects will be displayed through the portal. By default a basic form containing all attributes from the “details” z-list will be displayed, but you can customize this to optimize the layout and/or add/hide attributes.

A form is defined for a specific class (and its child classes) for one or more modes (view, create, edit). If there is no defined form matching the class/mode, it will fallback to the default one.

You can either choose to specify the attribute list you want to display, in which case they will be displayed one after another like for the default form. Or you can give an HTML layout that the portal will fill with the right markup. Both Bootstrap classes and Twig operator can be used.

You can also set flags on the attributes, they will be merges with those from the datamodel's life-cycle.

Action rules are behaviors applied on a brick under certain circumstances like presetting values on a object or defining which page to open when submitting/cancelling a form. It is similar to ObjectCopier in its syntax but doesn't have some of its limitations.

An action rule can be used in several bricks but not all bricks supports them. As of today they can only be used in BrowseBrick and CreateBrick.

Configuring the bricks should be the last step you do when configuring the instance as it relies on all the previous one. Keep in mind that they are based on the datamodel's security and instance's scopes.

Each brick has its own configuration and specifics, check the reference guide for detailed informations.

The new portal is based on well known frameworks such as Twig for the HTML layout and Boostrap for the styling, you can also use font libraries as Font awesome and Glyphicons are embedded as well. This allows you to find many online resources and examples.

By changing the bootstrap theme you can easily change the global look and feel of the portal. Lots of free themes are available online, you can even build yours if you wish.

Check www.bootswatch.com or the “sample-portal-new-theme” sample module in the how-tos.

Changing the layout is a bit more complex has you will have to code the HTML markup all over but it will give you freedom to shape it has you want.

There are several levels of layouts that you can override :

• The global portal structure
• The home page
• The generic brick page
• Each brick content layout

Check the “sample-portal-alter-twig” sample module for an example.

See the customer portal XML reference guide