:: Version 2.4.0 ::

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.

Intended audience

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

What's new in Portal ?

  • Full XML configuration No more PHP to adjust the portal 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
The enhanced portal is not installed by default when upgrading from iTop 2.2.1 or older.
If you have not selected the option “Enhanced Customer Portal” in the Setup, you will still be able to use the legacy customer portal.

How it works

Objects security

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.

Instance features

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

Configuring an instance

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

For the default one, its configuration has been splited in several modules so it adapts to the setup possibilities but the main part is located in /datamodels/2.x/itop-tickets/datamodel.itop-tickets.xml under the /itop_design/module_designs/module_design[@=“itop-portal”].

Depending on your setup choices, some other parts can be found in itop-request-mgmt, itop-request-mgmt-itil, itop-incident-mgmt-itil, itop-full-itil, itop-knownerror-mgmt and itop-portal

Object scopes

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.
If a class is not defined, the portal will try found the closest defined parent to retrieve its scope. If there is none, access will be denied.
Scopes are applied to external key in object forms but NOT to OQL fields of request templates.

Object forms

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.

In both cases, the portal will automatically append mandatory attributes for the current state to the form if they were not specified. This is a fail-safe to maintain object in a consistent state.

Action rules

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.

Bricks

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.

Customizing the look

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.

Changing the Bootsrap theme

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

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.

Twig template are cached to improve performance. If you want to skip the twig rendering cache during development, just add the debug parameter to the url and set it to true.

localhost/pages/exec.php?exec_module=itop-portal&exec_page=index.php&debug=true

Resources

2_4_0/customization/portal_overview.txt · Last modified: 2018/10/24 18:24 (external edit)
Back to top
Feedback