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.

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

• Access rights, menus, forms: this is all defined in XML, so can easily be changed
• 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

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 6 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.
• FilterBrick : Pre-filters another brick
• AggregatePageBrick : A page with one to many brick tiles.
• 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 define once you have determined 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 as you will have to code the HTML markup all over but it will give you freedom to shape it as 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.

Since iTop 2.7.0, the portal is base on Symfony. In order to ease your developments, you can enable Symfony's “Web Profiler” which is a development tool that gives detailed information about the execution of requests.

To enable it:

1. create in the same directory, a copy of the file /datamodels/2.x/itop-portal-base/portal/.env (or “/env-production/itop-portal-base/portal/.env” to avoid running a Setup, but this will be removed by the next Setup),
2. name the copied file .env.local
3. add this line to this content of the new file:

.env.local

APP_ENV=dev

The result of this setup is to display a bottom banner on Portal screen:

See the customer portal XML reference guide

The itop portals have module-parameters which can be overwritten within iTop Configuration file.
Those parameters can be different for each portal instances

Define the threshold which tells the auto loading mode of Browse and Manage Bricks, to switch between full and 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 portal instance, above it will be loaded dynamically at each page / level.
• full means that all data will be loaded at once.
• lazy means that data will be loaded dynamically at each page / level.

This parameter is used by iTop 2.7.6, 3.0.0 and 3.0.1 and remove in the following versions (2.7.7, 3.0.2 and 3.1.0).
The parameter might be set to 'false' if a Portal extension returns such error message: “Twig content not allowed in this context!”

Configuration file

$MyModuleSettings = array(
  'itop-portal' => array(  // itop-portal is the User Portal included in iTop
    // 'lazy_loading_threshold' => '500', as this is the default, it does not have to be specified here
    'enable_formmanager_content_check' => false,
  ),
  'itop-business-portal' => array(  // id of the portal instance, here another portal brought by an extension
    'lazy_loading_threshold' => '1000',
    'enable_formmanager_content_check' => true,  // as this is the default, it could have been omitted
  ),