Mark Coble (coblm)
Sr. System Architect
Pegasystems Inc.
coblm Member since 2018 7 posts
Posted: July 29, 2020
Last activity: October 6, 2020
Posted: 29 Jul 2020 22:27 EDT
Last activity: 6 Oct 2020 2:38 EDT

Dashboard for Dummies


Sorry, couldn’t resist the title. On my latest project I have had the opportunity to have more exposure to the Case Management portal, specifically pyDashboard7. This blog post it yet another to document my discoveries as a junior SSA, especially those which require engagement from LSAs and where seemingly no clear examples in documentation exist. 

For this change request to a recent Go-Live application two new dashboard requirements to the existing Case Management portal were introduced:

  1. A new Case Management navigation link for a new dashboard shall be added to the portal Navigation menu and visible only to a defined set of workgroups.
  2. The new dashboard shall contain a new widget and be published to all members of the defined workgroups.


Launching the Case Management portal from Designer Studio and using LiveUI in the portal it is pretty easy to discover Data-Portal-pyCaseManagerLinks rule is the one that needs to be specialized for adding a new menu link and configuring which Dashboard it opens (FN1). Figure 1 shows the UI section in the portal containing this rule. Figure 2 and 3 show the General and Actions tabs for configuring a New Dashboard item.



Figure 1: LiveUI on this section revealed pyCaseManagerLinks for specializing.


Figure 2: Added New Dashboard item and configured like the MyWork item.



Figure 3: Actions required to display new dashboard instance with NewCategory and label of New Category Label

In this example, which reflects the solution delivered to the client, a clone of what is done for MyWork was sufficient.  By adding the appropriate When rule for visibility we can restrict the access of this new link to the set of allowed workgroups. Reviewing the pxUserDashboardPrepareDisplay data transform it is pretty clear what its purpose is, but it was not clear what to use as the UserDashboardCategory and UserDashboardLabel.  Tracing and LiveUI were not giving any clues. Turns out you use whatever value you want. They will both be used when creating the new Dashboard instance.  

So requirement 1 above is configured, but how does the dashboard instance get created and published to the workgroup? The case management portal itself is a powerful ‘developer’ tool if your operator has the correct roles and associated privileges. First, check in the pyCaseManagementLink rule with the configuration above.  When you launch the portal your new dashboard link will be there as in Figure 4. (Checking in this rule is important as your changes will not be reflected for you or other users until it is checked in.)



Figure 4: Addition of New Dashboard link with the associated dashboard to be published.

Notice the UserDashboardLabel is the title of the Dashboard. You now can add whatever widgets are available and as highlighted in the upper right corner of Figure 4 the option to publish to a team is available (FN2). Publishing this way will create the System-User-Dashboard instance shown in Figure 5 using the UserDashboardCategory 'NewCatetgory' defined in Figure 3. Notice it is part of the instance handle and that the handle also indicates it is a dashboard instance at the Payroll@TGB workgroup level.

Dashboard, My Work and now the New Dashboard in Figure 2 are widget-supporting UI that have associated data instances. The data instances are created at the following levels.

  1. User
  2. User Workgroup
  3. Default

If more than one instance exists, the priority is also as above. Default applies to all users and makes the widget available for users of other applications, so it’s not a good idea to use it.  This is to allow varying levels of personalisation of widgets. The normal practice is to have it at the workgroup level with the user’s having the option to add widgets they want. When user-specific personalisation is done, any changes done to widgets at the workgroup or default level are no longer visible.



Figure 5: System-User-Dashboard instance created for dashboard published in Figure 4


Both requirements have now been met.  Please read the following footnotes for further explanation.



FN1:  To be able to use tracer, LiveUI or the clipboard in the portal it needs to be launch from Designer and to do so the user needs to of course have access to the Developer portal.  The user also needs the correct privileges to use tracers, etc.  One role which gives these privileges is PegaRULES:SysAdm4.

FN2:  The option of Publish to Team is only available to Operators that are the manager of the team’s workgroup.  Figure 6 shows that SSA@TGB is the manager of the Payroll@TGB workgroup. Therefore, this dashboard is currently published to the Payroll@TGB workgroup. To do the same for other workgroups, managers of those workgroups would need to do the same.



Figure 6: Manager associated with a workgroup can publish dashboards to the workgroup.

Pega Platform 8.3 Case Management Other Industry Senior System Architect Developer Knowledge Share