BAM Dashboard Customization

BAM is an enterprise solution that provides a real-time summary of business activities to operations managers and upper management. Using BAM enables an enterprise to make better-informed business decisions, address problem areas quickly, and re-position itself to take full advantage of emerging opportunities.

In line with this definition, Appway BAM provides managers with real-time visibility and process control over FNZ Studio instances. By monitoring business data and events, managers can identify process issues and successes and initiate action as appropriate.

To provide this information efficiently we may need to customize the BAM Dashboard in different ways. In this document we will cover some of the most common cases of BAM Dashboard customization, specifically:

Adding A Custom action
Adding a New chart
Adding a Scatter Plot Duration Chart
Applying A Solution Template
Moving all from Base to Target Package
Seding a Notification Upon SLA Expiration

Add A Custom Action

Problem

I installed BAM and the out-of-the-box dashboards. Now I would like to add a "Reassign" action to the BAM dashboards. How can I add a new "Actions" column in the dashboard tables and implement a custom "Reassign" action at activity level?

Solution

The custom Actions column at the activity level can be defined by enabling it, and then customizing the appropriate Include Screen which implements the action.

To achieve this, follow these steps:

In the BAM_DefaultFeatures catalog, enable the activity details actions by setting the conf column for the activityActionsEnabled entry to true.
Customize the BAM — Include — Activity Actions Screen to open the reassignment flow used in your specific project. This can be achieved by selecting the existing sample reassign icon, and adding a Display Process action to it as shown below.

In the most common implementations, the reassign flow must be triggered by passing the workitemId of the workitem to be reassigned as an assigned variable. This is the corresponding configuration:

Copy

'workitemId=' & $dbRecord['workflowTokenId']

Screenshot showing the Onclick > Display Process fields

Adding A New Chart

Problem

I installed the BAM including the out-of-the-box dashboards. Now I would like to add a new chart to the BAM dashboards. How can I add a chart based on a custom business indicator (KPI)?

Solution

As an example, we create a new bar chart that presents the number of instances of a travel booking process basing on the travel destination. The 'Destination' is a custom instance-level KPI that is defined with a trackpoint inside the process we're using.

In order to add a new chart to the BAM Performance Metrics dashboard, follow these steps:

Create a new Screen to host the chart. Let's call it DestinationChart (can be any ID).
Enable the first custom chart by setting the conf column for the additionalChart1Enabled entry in the BAM_DefaultFeatures catalog to true.
Change the conf column for the additionalChart1Label entry in the BAM_DefaultFeatures catalog to, for example, Number of Processes by Destination (can be any title).
Include the DestinationChart Screen in the BAM — Dashboards Screen inside the template area ADDITIONAL_CHART1.
Open the DestinationChart Screen and inherit the $filter variable from the BAM — Dashboards Screen.
Add a Line/Bar Chart component and give it the HTML ID ATTCHART (can be any ID).
Style the chart as desired by configuring the component properties. In order to match the other BAM charts' size, select 320px as Width and 320px as Height.
Write down the query on the BAM DB that extracts the desired data — in our case the number of processes by destination.
Copy
```
SqlQuery('ds', JOIN('SELECT wia.attributeValue value, COUNT ( * ) count FROM BAM_WorkflowInstanceAttributes wia, BAM_workflowInstances wi WHERE wi.workflowinstanceid = wia.workflowinstanceid AND wia.attributename = \'Destination\' ', BuildBAMFilterSQL($filter), ' GROUP BY attributeValue'));
```
As you can see, it is possible to use the function BuildBAMFilterSQL which takes the $filter variable (BAMFilter) as an input and returns the SQL string to be concatenated in order to add the filtering conditions specified by the user in the main BAM filtering area.

Write down the rest of the script needed to initialize the chart (Chart Data property). Check the following code as an example:

Copy

// retrieve the data from the DB 
Indexed Any $results := SqlQuery('ds', JOIN('SELECT wia.attributeValue value, COUNT ( * ) count     FROM BAM_WorkflowInstanceAttributes wia, BAM_workflowInstances wi WHERE wi.workflowinstanceid = wia.workflowinstanceid AND wia.attributename = \'Destination\' ', BuildBAMFilterSQL($filter), ' GROUP BY attributeValue'));
SCChartData $chartData := NEW(SCChartData);
// 
//bar options (for all series) 
SCChartOptionBars $barOptions := NEW(SCChartOptionBars);
$barOptions.show := true;
$barOptions.fill := true;
$barOptions.fillColor := 'lightgreen';
$barOptions.barWidth := 0.8;
$barOptions.lineWidth := 1;
$barOptions.align := 'center';
// 
// data series 
SCChartSeries $chartSeriesA := NEW(SCChartSeries);
$chartSeriesA.label := 'Processes';
$chartSeriesA.shadowSize := 10;
$chartSeriesA.bars := $barOptions;
$chartSeriesA.color := 'grey';
// 
SCChartXaxis $xaxisOptions := new SCChartXaxis;
$xaxisOptions.show := true;
// 
// 
Integer $count := 1;
Named String $record;
ForEach $record In $results Do
   // values (with colors) 
   SCChartPoint $p := NEW(SCChartPoint);
   SCChartTick $t := new SCChartTick;
   $t.label := $record['VALUE'];
   $t.value := $count;
   $xaxisOptions.xaxis.addElement($t);
   $p.x := $count;
   $p.y := TODOUBLE($record['COUNT']);
   $chartSeriesA.data.addElement($p);
   $count := $count + 1;
End 
$chartData.xaxis := $xaxisOptions;
// 
$chartData.series.addElement($chartSeriesA);
// 
Return $chartData;

Example file

Click on the following link to download the BAMChartRecipe.awexport containing a custom chart Screen: bamchartrecipe.awexport

Add A Scatter Plot Duration Chart

Problem

I installed the BAM including the out-of-the-box dashboards. Now I would like to add a new chart to the BAM dashboards that helps me see if there is any correlation between the duration of my process and the value of a custom business indicator (KPI). How can I add a scatter plot chart to display such data? [BAM version 2.0.x, 3.0.x, 3.1.x, 3.2.x, 3.3.x, 3.4.x, 3.5.x]

Solution

An example could be creating a scatter plot chart that shows if there is any correlation between the distance (in km) of travel being requested (on the x axis), and the duration (in hours) of a travel booking process (on the y axis). By looking at this chart it will be possible to identify if there is a correlation between the two values, that is, if the duration of the process increases/decreases as the distance increases/decreases.

In order to add a scatter plot chart to the BAM Performance Metrics dashboard, follow these steps:

Create a new Screen to host the chart. Let's call it BAMScatterPlot (can be any ID).
Enable the first (available) custom chart by setting the conf column to true for the additionalChart1Enabled entry in the BAM_DefaultFeatures catalog.
Change the conf column for the additionalChart1Label entry in the BAM_DefaultFeatures catalog to, for example, Duration Scatter Plot (can be any title).
Include the BAMScatterPlot Screen in the BAM – Dashboards Screen inside the template area ADDITIONAL_CHART1 (or the first available template area).
Open the BAMScatterPlot Screen and inherit the $filter variable from the BAM — Dashboards Screen.
Add a Line/Bar Chart component and give it the HTML ID SCATTERPLOT (can be any ID).
Style the chart as desired by configuring the component properties. In order to match the other BAM charts' size, select 320px as Width and 320px as Height.
Configure the chart data property as follows:

Copy

BAM_GenerateScatterPlotChart($filter, 'Distance')

This uses the BAM_GenerateScatterPlotChart function that is available in the BAM dashboards out-of-the-box export. This function generates the necessary chart data based on the two provided inputs: the $filter variable, which represents the user selection, and the name of the KPI to be investigated for correlation.

Example file

Click to download the BAMScatterPlotRecipe.awexport containing a custom scatter plot chart Screen.

Applying A Solution Template

Problem

I installed Appway BAM and the out-of-the-box dashboards that came with it. I would now like to apply the Screen template (header, menus...) used across my solution to the BAM dashboards. How do I do that?

Solution

Note: This article applies to BAM versions 3.4 and 3.5

If you already have a defined Screen template in use in your solution, that template can easily be applied to the BAM dashboards.

A Screen template often includes elements such as a header with a company logo and custom links, and a navigation menu on the left or right side of the Screen.

In order to apply the same Screen template to the BAM dashboards:

Identify the template Screen you wish to apply to the dashboards
Go to System Configuration > Configuration Properties
Click the menu icon next to the Configuration Properties title to open the dropdown menu
Select Edit Content Configuration
Add an Appway configuration property with ID solution.templateid.bam, and a value equal to the ID of the identified template screen

The screenshot below shows an example configuration for a template called MySolutionTemplate.

Studio configuration UI showing the configuration property highlighted in a red rectangle

The selected template is then applied to the BAM dashboards immediately.

The BAM dashboard content is placed inside the CONTENT placeholder of the selected template. No other placeholder is filled.

In the example below, the template simply contains a sample header:

Result:

Moving From Base To Target Package

Problem

I installed BAM and I configured the SLAs. Now I would like Appway to send out email notifications when the SLAs I defined expire for a specific activity. How can I define custom notification actions to be executed upon SLA expiration?

Solution

The notifications action can be modeled in the process editor like any other process behavior. After having defined the SLA on a specific activity (screen or Sub-Process), follow these steps in order to define the actions to be taken upon SLA expiration:

Open the Process that contains the activity to be monitored and identify the activity (screen or Sub-Process) in the process design.
Add a Send Mail task to the process.

Note: the Send Mail task is available in the MailExtension.

Configure the Send Mail task with the desired sender/recipient and a subject/text such as 'SLA expired for review stage.'
Add an outgoing connection from the activity to be monitored to the Send Mail task. Change the Connection Type property to Event:Timer. Give the name SLA Expired to the Connection.
Select the timer icon and configure it with the expression:
Copy
```
TOLONG(ProcessTokenGetAttribute(WORKITEM().getTokenId(), 'activityExpirationTime'))
```
This checks the token attribute activityExpirationTime set by the BAM extension that contains the SLA expiration time for the current activity.
Deselect the Interrupting checkbox, so that the SLA expiration does not interrupt the process execution.
Add an End Event and connect the Send Mail task to it in order to complete the notification flow.
Optionally, an additional script task can be added between the activity and the Send Mail, or between the Send Mail and the End Event in order to implement custom expiration actions such as logging the event or creating an audit trail entry.

Excerpt of a process showing the steps once SLA expires

Example file Click on the following link to download BAMSLANotificationRecipe.awexport which contains a sample process with SLA notification.

Send Notification Upon S L A Expiration

Problem

Solution

Open the Process that contains the activity to be monitored and identify the activity (screen or Sub-Process) in the process design.
Add a Send Mail task to the process.

Note: the Send Mail task is available in the MailExtension.

Configure the Send Mail task with the desired sender/recipient and a subject/text such as 'SLA expired for review stage.'
Add an outgoing connection from the activity to be monitored to the Send Mail task. Change the Connection Type property to Event:Timer. Give the name SLA Expired to the Connection.
Select the timer icon and configure it with the expression:
Copy
```
TOLONG(ProcessTokenGetAttribute(WORKITEM().getTokenId(), 'activityExpirationTime'))
```
This checks the token attribute activityExpirationTime set by the BAM extension that contains the SLA expiration time for the current activity.
Deselect the Interrupting checkbox, so that the SLA expiration does not interrupt the process execution.
Add an End Event and connect the Send Mail task to it in order to complete the notification flow.
Optionally, an additional script task can be added between the activity and the Send Mail, or between the Send Mail and the End Event in order to implement custom expiration actions such as logging the event or creating an audit trail entry.

Excerpt of a process showing the steps once SLA expires

Example file Click on the following link to download BAMSLANotificationRecipe.awexport which contains a sample process with SLA notification.