You are browsing the documentation for iTop 2.7 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

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.
2_7_0/customization/add-dashboard-attribute.txt · Last modified: 2020/04/15 15:23 (external edit)
Back to top
Contact us