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 thebackend.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 thefrontend.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 theview.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 thestyle.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 onschema
, 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 termparams
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. Thecontext
parameter includes two properties -element
andscope
. Theelement
property indicates the jQuery object that contains the DOM node of your widget. Thescope
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. Thedata
object contains that the data that can be bound to the scope for display. Thecontext
object is similar to the parameter used in theinit
function.
Example:
You can also use jQuery or Underscore.js to alter your data as indicated in the following example.javascript update: function(data, context) { // set your data in scope so you can use it where you need context.scope.data = data;}
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. Thesize
object must include thewidth
andheight
of the widget. Thecontext
object is similar to the parameter used in theinit
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:
-
In the All Processes section of the IBM Process Mining workspace, click the required process.
-
On the navigation panel of the application, click Analytics.
-
On the Analytics page, click Dashboard, and then click Create new.
-
In the Name box of the Choose a dashboard name dialog box, type the required name for the dashboard, and then click OK.
-
On the newly created dashboard, click Edit.
-
On the widget panel, click the Add custom widget icon, and then from the menu, click New JSPlugin.
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.
-
On the Pending changes will be lost message box, click Yes.
-
On the Name box of the Info tab, type a name for the custom widget.
Important: Do not include spaces and special characters in the name for custom widgets.
-
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.
-
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.
-
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.
-
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.
-
In the left pane, click Save.
-
The created widget is displayed in the list of custom widgets. You can the use this widget to filter data in the dashboard.