You are browsing the documentation for iTop 3.0 which is not the current version.

Consider browsing to iTop 3.1 documentation

Add a Dashboard on a Team

Prerequisite: You must be familiar with the Syntax used in Tutorials and have already created an extension.
We also assume that you are familiar with dashboard design within iTop and OQL.

learning:
Add a Dashboard attribute on a class
level:
Beginner
domains:
XML, Dashboard, Presentation
min version:
2.6.0

You want to display on every Team, a new tab displaying a dashboard with information specific for that team:

  • The list of open Tickets assigned to that team
  • A list of members limited to the active ones
  • The list of locations where at least one team member is located

Those are just examples of dashlets which could be defined, the purpose of this tutorial isn't to explain how to create a dashlet

OQL queries which could be used for the above examples

The list of open Tickets assigned to that team :

SELECT UserRequest WHERE STATUS IN ('assigned') AND team_id=:this->id
UNION SELECT Incident WHERE STATUS IN ('assigned') AND team_id=:this->id
UNION SELECT Problem WHERE STATUS IN ('assigned') AND team_id=:this->id

A list of members limited to the active ones :

SELECT Person AS p
   JOIN lnkPersonToTeam AS l ON l.person_id = p.id
   WHERE l.team_id = :this->id AND STATUS='active'

The list of locations where at least one team member is located :

SELECT Location AS L
   JOIN Person AS P ON P.location_id=L.id
   JOIN lnkPersonToTeam AS l1 ON l1.person_id=P.id
   JOIN Team AS T ON l1.team_id=T.id
   WHERE T.id=:this->id

with the Designer

Prerequisite: You must be a Combodo's customer

Create a Dashboard Attribute

Go to the Team class, tab Schema to create a new field:

  • Enter overview as field Code (lower letter only, no blank, dash or other non alphabetical characters),
  • chose Dashboard for type
  • Give it a label

A Dashboard Attribute is a dashboard displayed as an extra tab on a object. The queries used in such a dashboard can use the context of the current object.

Dashboard attributes can be added and all their parameters can be set and modified within the ITSM Designer.

  • You can allow normal users to create a customized version of such a dashboard by checking the field Is User Editable.
  • Even if it is not user editable, Administrators are always allowed to customize a dashboard. This allows for designing dashboards at run time (using real data) before injecting their definition in the Designer.
To edit the Definition (Raw XML) of the Attribute dashboard:
  1. just leave the default XML at creation,
  2. do a Move to Test or Move To Production,
  3. once in iTop, edit and modify that dashboard as you want,
  4. use the action Export to a file
  5. open that file with any text editor and copy its content
  6. return into the ITSM Designer
  7. paste the dashboard XML in the Attribute Dashboard Definition (Raw XML)
Dashboard Attribute cannot be put in a list, nor in any search criteria.

with an iTop Extension

Prerequisite: You must be familiar with the Syntax used in Tutorials and have already created an iTop extension.

Create a Dashboard Attribute

For this you will need to create a new AttributeDashboard field to the Team class and add it to the details display.

itop_design / classes
    <class id="Team" _delta="must_exist">
      <fields>
        <field id="dashboard" xsi:type="AttributeDashboard" _delta="define">
          <is_user_editable>true</is_user_editable>
          <!-- Use this default definition for creating a new dashboard -->
          <definition>
            <!-- Later replace the whole definition with the XML export -->
            <layout>DashboardLayoutOneCol</layout>
            <title/>
            <auto_reload>
              <enabled>false</enabled>
              <interval>300</interval>
            </auto_reload>
            <cells>
              <cell id="0">
                <rank>0</rank>
                <dashlets>
                  <dashlet id="0" xsi:type="DashletEmptyCell">
                    <rank>0</rank>
                  </dashlet>
                </dashlets>
              </cell>
            </cells>
          </definition>
        </field>
      </fields>
      <presentation>
        <!-- Dashboard can only be displayed in the details -->
        <details>
          <items>
            <!-- Dashboard can be displayed neither in a fieldset, nor in a column -->
            <item id="dashboard" _delta="define">
              <rank>100</rank>
            </item>
          </items>
        </details>
      </presentation>
    </class>
Use a high rank for your dashboard, to put it at the end (just before 'History'), otherwise when switching to modify mode on a relation tab located after the dashboard, you would end-up modifying the wrong relation tab. Because Dashboard being non editable, it is removed from the edit view, the tabs are renumbered, and switching from read to edit, stays on the same tab number

Add a dictionary entry for class:Team/Attribute:dashboard.

Design your Dashboard

Deploy a first version of your extension, which will provide an empty dashboard. Redesign this dashboard within iTop

When writing your OQL queries within the Team dashboard, you can use placeholders like :this->att_code where att_code can be any field of the Team

Example using the id of the team:

SELECT Person AS p JOIN lnkPersonToTeam AS lnk ON lnk.person_id = p.id WHERE lnk.team_id=:this->id

When satisfied with your design, export it in XML and replace the content of the initial <definition> with the exported <dashboard> tag content:

<?xml version="1.0"?>
<dashboard xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <layout>DashboardLayoutOneCol</layout>
  <title/>
  <auto_reload>
    <enabled>false</enabled>
    <interval>300</interval>
  </auto_reload>
  <cells>
    <cell id="0">
      <rank>0</rank>
      <dashlets>
        <dashlet id="1" xsi:type="DashletObjectList">
          <rank>0</rank>
          <title>Members</title>
          <query>SELECT Person AS p 
                 JOIN lnkPersonToTeam AS lnk ON lnk.person_id = p.id 
                 WHERE lnk.team_id=:this-&gt;id
          </query>
          <menu>true</menu>
        </dashlet>
      </dashlets>
    </cell>
    <cell id="1">
      <rank>1</rank>
      <dashlets>
        <dashlet id="0" xsi:type="DashletEmptyCell">
          <rank>0</rank>
        </dashlet>
      </dashlets>
    </cell>
  </cells>
</dashboard>

Replace all tags under the <definition> tag by what you find in your XML export under the <dashboard> tag:

itop_design / classes / class@Team / fields
        <field id="dashboard" xsi:type="AttributeDashboard" _delta="define">
          ...
          <definition>
            <!-- Paste here the XML export of your Dashboard designed directly in iTop -->
          </definition>
          ...

And run the setup again.

  • Everyone will see that dashboard on all Team objects.
  • Users can also twist it to build their own version of the Team dashboard,
  • but they all share the common version that you have designed and pushed on iTop.

If you push a new version of that dashboard:

  • every one will get it
  • customized versions of the dashboard, also they were build on the previous common dashboard, will remain unchanged.
3_0_0/customization/add-dashboard-attribute.txt · Last modified: 2023/03/09 14:34 (external edit)
Back to top
Contact us