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, 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

Adding 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:

  1. Create a new Screen to host the chart. Let's call it DestinationChart (can be any ID).

  2. Enable the first custom chart by setting the conf column for the additionalChart1Enabled entry in the BAM_DefaultFeatures catalog to true.

  3. 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).

  4. Include the DestinationChart Screen in the BAM — Dashboards Screen inside the template area ADDITIONAL_CHART1.

  5. Open the DestinationChart Screen and inherit the $filter variable from the BAM — Dashboards Screen.

  6. Add a Line/Bar Chart component and give it the HTML ID ATTCHART (can be any ID).

  7. 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.

  8. 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.

  9. 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

Adding 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:

  1. Create a new Screen to host the chart. Let's call it BAMScatterPlot (can be any ID).

  2. Enable the first (available) custom chart by setting the conf column to true for the additionalChart1Enabled entry in the BAM_DefaultFeatures catalog.

  3. Change the conf column for the additionalChart1Label entry in the BAM_DefaultFeatures catalog to, for example, Duration Scatter Plot (can be any title).

  4. Include the BAMScatterPlot Screen in the BAM – Dashboards Screen inside the template area ADDITIONAL_CHART1 (or the first available template area).

  5. Open the BAMScatterPlot Screen and inherit the $filter variable from the BAM — Dashboards Screen.

  6. Add a Line/Bar Chart component and give it the HTML ID SCATTERPLOT (can be any ID).

  7. 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.

  8. 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 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

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:

  1. Identify the template Screen you wish to apply to the dashboards
  2. Go to System Configuration > Configuration Properties
  3. Click the menu icon next to the Configuration Properties title to open the dropdown menu
  4. Select Edit Content Configuration
  5. Add a 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 imported the BAM Dashboards in FNZ Studio (or migrated the out-of-the-box dashboards) and all the BAM Business Objects are now in the Base Package. I would like to move them to a target Package (for example BAM) in order to better organize my Solution.

Solution

BAM dashboards are always delivered in the Base Package. The following sections provide detailed procedures on:

  • Migrating BAM Business Objects from the Base Package to another Package.
  • Upgrading to a newer BAM version after migrating BAM Business Objects to another Package.

Migrating BAM Business Objects from the Base Package to another Package

Following are the steps required to migrate your BAM Business Objects from the Base Package to a different Package (see Packages):

  1. Create the desired target Package.
This recipe uses BAM as an example Package name. If you decide to choose a different name for your Package, remember to use your chosen Package name instead of BAM: when updating the configurations below.

  1. Use the Move Business Objects functionality on the Maintenance tab of the Base Package to move BAM Business Objects to your target Package. Move all BAM Business Objects except:

    • (DataClass) BAMFilter
    • (DataClass) BAMActivityFilter
    • (Label) DOCUMENT_TITLE-BAM_SLAReport (this label is generated automatically)
    • (Catalog) BAM_Attributes
    • (Catalog) BAM_TokenAttributes

  2. Keep the visibility settings and dependencies suggested by the system.

  3. In the target Package, change the BAM_Dashboards Screen: Edit the first Template expression CONF('solution.templateid.bam', 'BAM_DefaultSolutionTemplate') to include the target Package ID in the default Screen ID e.g. BAM:BAM_DefaultSolutionTemplate

  4. In the Studio, go to System Configuration>Extensions>Permanent Extensions>BAM Extension. Edit the BAM extension configuration property bam.dashboard.process so that it points to the moved BAM_Dashboards Process e.g. bam.dashboard.process = BAM:BAM_Dashboards

  5. Edit the BAM extension configuration property bam.slareport.report to point to the moved BAM_SLAReport report e.g.

    bam.slareport.report = BAM:BAM_SLAReport

  6. In the Studio, go to System Configuration>Extensions>Restartable Extensions>POI. Edit the POI extension configuration to point to the moved BAM template resources. For example:

    • template.activities.resource.id = BAM:BAM_ActivitiesReport
    • template.instances.resource.id = BAM:BAM_InstancesReport

  7. Using the global search functionality, identify any dynamic references to the BAM_Dashboards Process. Update these references so that they point to the moved Process (BAM:BAM_Dashboards). A dynamic reference is the use of the Process ID as a string in an expression, for example.

    • Remember to create necessary entry points and access control rules for the BAM Package if other Packages are dependent on it (see Packages).

  8. Add an entry point in the target Package with the ID GenerateExcelReport pointing to the Business Object BAM_GenerateExcelReport Process. Then update the access control rule to the entry point.

Upgrading to a Newer BAM Version after Migrating BAM Business Objects to Another Package

In the previous section, you moved BAM Business Objects out of the Base Package into the BAM Package of your Solution.

Let's assume that, at some point, you want to import a new version of the BAM dashboards in your Solution. The newly imported Business Objects will be imported to the Base Package and will not overwrite your current BAM Business Objects contained in the BAM Package (which have different Business Object IDs).

In order to take up the changes and new features included in the newer version of the BAM dashboards, you need to manually apply changes one by one to the BAM Business Objects located in the BAM Package.

Sending Notification Upon SLA Expiration

Problem

I installed BAM and I configured the SLAs. Now I would like FNZ Studio 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:

  1. Open the Process that contains the activity to be monitored and identify the activity (screen or Sub-Process) in the process design.
  2. Add a Send Mail task to the process.
Note: the Send Mail task is available in the MailExtension.
  1. Configure the Send Mail task with the desired sender/recipient and a subject/text such as 'SLA expired for review stage.'
  2. 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.
  3. 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.
  4. Deselect the Interrupting checkbox, so that the SLA expiration does not interrupt the process execution.
  5. Add an End Event and connect the Send Mail task to it in order to complete the notification flow.
  6. 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.