Custom plug-ins

You can use the Analytics page in IBM Process Mining to build custom plug-in widgets and analyze the data based on your requirements. You can also use these plug-in widgets to customize how your data is processed and displayed.

For more information on creating plug-in widgets, see the following links:

Understanding the scripts to create plug-in widgets

You can use the following files to succuccessfully create a plug-in widget:

  • backend.js
    Indicates the JavaScript file that you can run on the server to preprocess your data. For more information on the contents of the backend.js file, see Understanding the backend.js file.
  • frontend.js
    Indicates the JavaScript file that runs on your browser to process and display your data. For more information on the contents of the frontend.js file, see Understanding the frontend.js file.
  • view.html
    Indicates the HTML file that includes the content of your widget. For more information on the contents of the view.html file, see Understanding the view.html file.
  • style.css
    Indicates the CSS file that you can use to style your plug-in. For more information on the contents of the style.css file, see Understanding the style.css file.
  • schema
    Indicates the parameter table that you can use to add configurable parameters in your custom widget. For more information on schema, see Understanding schema.

Understanding the backend.js file

Using the following functions, you can configure the backend.js file to return an object:

  • init(params)
    You can use this function to initialize the widget on the server. The term params indicates the key and the value map of the plug-in parameters.
  • update(trace)
    This function is called whenever you process the widget.
  • finalize(output)
    This function is run when the data is processed and displayed to the browser.

The following table describes the objects that you can use in the update function.

Object Function Type Description
trace getCaseId() string It returns the trace-id value that is associated to the current trace.
getCaseIdIndex() int It returns a dictionary index of the trace-id value that is associated to the current trace.
get(index) TraceEvent It returns the TraceEvent object at the specified index in the trace sequence.
size() long It returns the number of events.
'TraceEvent' getCaseId() string It returns the trace-id value that is associated to the current event.
getEventClass() string It returns the class of a trace event, for example, an activity.
getResource() string It returns the associated resource of a trace event.
getRole() string It returns the role of a trace event.
getStartTime() long It returns the start time of the current event in milliseconds.
getEndTime() long It returns the end time of the current event in milliseconds.
getStringAttributeValue(String fieldId) string It returns a string value that is mapped to the corresponding “fieldId” of the current event, for example, the name of the mapped custom column. You must include the prefix, attr-custom-, before fieldId.
For example, var vendor = event.getStringAttributeValue('attr-custom-Vendor');
getDoubleAttributeValue(String fieldId) double It returns a double value that is mapped to the corresponding “fieldId” of the current event, for example, the name of the mapped custom column. You must insert the prefix, attr-custom- before fieldId.
For example, var amount = event.getDoubleAttributeValue('attr-custom-Amount');

Example
This example indicates the sample contents of the backend.js file.

...
update: function(trace) {
    this.myVariable = "plugin test";
},
finalize: function(output) {
    output['myIntVariable'] = 8;
    output['myVariable'] = this.myVariable
}
...

Helpers

You can use the following helper objects to create a plug-in widget:

  • console
    Indicates the helper object that supports to print messages on the console.
  • API
    Indicates the supports the next methods.
  • SummaryStatisticsLite
    Indicates the object that you can use to compute and store statistics.

The following table describes the various helper objects that you can use to create plug-in widgets.

Helper object Function Type Description
console log(string) void It appends a message to the plug-in output that is evaluated after final callback.
API summaryStatistics() SummaryStatisticsLite It returns an instance of a mutable back-end summary statistics object.
getStringCacheId(string eventFieldId, string fieldValue) string It either returns a dictionary index of the specified value, or -1, if such an instance is not found.
SummaryStatisticsLite addValue(value) void It adds a value to the data.
getSummary() StatisticalSummary It returns an instance of StatisticalSummaryValues with a report on the current statistics.
getMedian() double It returns the median of the values that are added.
copy() SummaryStatisticsLite It returns a copy of the SummaryStatisticsLite instance with the same internal state.
getN() long It returns the number of available values.
getSecondMoment() double It returns a statistic that is related to the Second Central Moment.
getMax() double It returns the maximum value of the values that are added.
getMin() double It returns the minimum value of the values that are added.
getMean() double It returns the mean value of the values that are added.
getVariance() double It returns the (sample) variance of the available values.
getStandardDeviation() double It returns the standard deviation of the values that are added.
getSum() double It returns the sum of the values that are added.

Understanding the frontend.js file

Using the following functions, you can configure the frontend.js file to return an object:

  • init(context)
    This function runs when you initialize a widget. The context parameter includes two properties - element and scope. The element property indicates the jQuery object that contains the DOM node of your widget. The scope property indicates the angular context of your widget. You can also change the DOM element of your widget with jQuery or change the scope with AngularJS.
  • update(data, context)
    This function runs whenever you reload the dashboard. The data object contains that the data that can be bound to the scope for display. The context object is similar to the parameter used in the init function.
    Example:
     javascript
     update: function(data, context) {
     // set your data in scope so you can use it where you need
     context.scope.data = data;}
    
    You can also use jQuery or Underscore.js to alter your data as indicated in the following example.
    Example:
    javascript
    update: function(data, context) {
    // set your data in scope after transforming it so you can use it where you need
    context.scope.data = _.map(data, function(element) {
      return {
          name: element.id,
          text: element.value }; });}
    
  • resize(size, context)
    This function runs whenever you resize the widget. The size object must include the width and height of the widget. The context object is similar to the parameter used in the init function.

Understanding the view.html file

The view.html file contains the content of your widget.

You can use the following angular helpers to display your data and change HTML elements based on the content without modifying the DOM with JavaScript:

Example The following example describes the contents of a view.html file based on a frontend.js file.

Assume that the frontend.js file of custom widget includes the following script:

javascript
init: function(context) {
    context.scope.myVariable = 'Plugin widget test';
    context.scope.myIntVariable = 8;
}

You can use the following scripts to create a corresponding view.html file:

<!-- the next syntax will print the content of myVariable inside the paragraph -->
<p>{{myVariable}}</p>

<!-- the next paragraph will be displayed only if myIntVariable is greater than 5 and the content will be formatted as a number -->
<p ng-if="myIntVariable > 5">{{myIntVariable | number}}</p>

For more information on scripting the view.html file, see the Angular documentation.

Advanced Filters

In addition to angular filters, you can use the following custom filter based on your requirement.

  • formatMeasure: param

The following table describes the various parameters that you can use with the custom filter:

Parameter Purpose
auto Automatic formatter
date Date formatter with localization support
datetime Date and time formatter with localization support
duration Duration formatter
number Number formatter with localization support
text Text formatter
percentage Percentage formatter

Example

Following example describes how to use the custom filters in the view.html file.

<!-- will print the date with the format based on your location i.e. 01/01/2018 -->
<p>{{myDateVariable | formatMeasure:'datetime'}}</p>

Understanding the style.css file

The style.css file contains the stylesheet for your widget. For example, the style.css file includes the contents:

p {
    font-size: 14px;
    color: red;
}

Note: The created widget is displayed in the style that is mentioned in the style.css file.

Understanding schema

The schema table contains optional parameters that you can set in the widget options.

You can use either of the following types to define parameters in schema:

  • string
  • dimension

Additional Reference

For more information on functions, objects, and parameters, see the following links:

Creating a sample custom widget

You can use the following steps to create a custom widget:

  1. In the All Processes section of the IBM Process Mining workspace, click the required process.

    Workspace

  2. On the navigation panel of the application, click Analytics.

  3. On the Analytics page, click Dashboard, and then click Create new.

    New dashboard

  4. In the Name box of the Choose a dashboard name dialog box, type the required name for the dashboard, and then click OK.

    Dashboard name

  5. On the newly created dashboard, click Edit.

  6. On the widget panel, click the Add custom widget icon, and then from the menu, click New JSPlugin.

    Custom widget

    Note: You can choose any of the widgets in the menu or create a custom widget by using the scripts that are mentioned in the Understanding the scripts to create plug-in widgets.

  7. On the Pending changes will be lost message box, click Yes.

    Message box

  8. On the Name box of the Info tab, type a name for the custom widget.

    Widget name

    Important: Do not include spaces and special characters in the name for custom widgets.

  9. In the left pane, click Schema, and then in the result window click Add to manage inputs from users. For example, you can ask the user to input their name to the widget by defining a Name parameter as indicated in the following figure. Do note that this is an optional feature that you can set for the widget.

    Widget schema

  10. In the left pane, click backend.js, and then use the functions that are mentioned in Understanding the backend.js file to define the script.

    Backend file

  11. In the left pane, click frontend.js, and then use the functions that are mentioned in Understanding the frontend.js file to define the script.

    Frontend file

  12. In the left pane, click view.html, and then use the functions that are mentioned in Understanding the view.html file to define the script.

    View file

  13. In the left pane, click Save.

  14. The created widget is displayed in the list of custom widgets. You can the use this widget to filter data in the dashboard.