Custom metrics

Overview

Custom Metrics is a feature in IBM Process Mining that helps you to apply a custom built JavaScript code at the case level of a project to create a business metric. You can create the JavaScript code using the available data in IBM Process Mining to compute a user-defined result. Therefore, you must have a good understanding of the JavaScript language and the data structures in IBM Process Mining to create a custom metric.

You can use the custom metrics for the following activities in IBM Process Mining:

• Creating project filters
• Comparing process models
• Viewing process statistics
• Model conformance checking
• Creating analytics dashboard
• Taking back-up of the project

Using custom metrics in a project might impact the performance of process analysis. To maintain optimum performance, limit the number of custom metrics and ensure their JavaScript code is optimized.

If there are any invalid custom metrics, you see an Error icon () next to the invalid custom metric.

For the invalid custom metrics, the Show statistics toggle is disabled.

The following topics explain the tasks that you can do in the Custom Metric section in IBM Process Mining:

• Accessing the Custom metric dashboard
• Creating a custom metric
• Editing an existing custom metric
• Deleting a custom metric
• Filtering custom metrics by category
• Example: Creating a custom metric to analyze the opportunity management process

Accessing the Custom metric dashboard

To access the Custom metric dashboard, do the following steps:

1. Go to Home > Recent projects > All Projects > Assets.

2. Select a process-mining project from the Projects table in the Projects tab.

3. In the selected project, go to Manage > Custom Metric.

   

Creating a custom metric

To create or modify custom metrics in IBM Process Mining NextGen, see the Custom metrics topic.

To create a custom metric in IBM Process Mining Legacy, do the following steps:

1. On the Custom Metric dashboard, click Add new custom metric button to open the "Create custom metric" dialog (see 'Figure 1. Create Custom metric).

   

   Figure 1. Create Custom metric

2. In the "Create custom metric" dialog, go to the Details step and do the following:

   1. Enter a name for the custom metric in the Name field.

      

   2. Select one of the following data types from the Data Type dropdown:

      • Boolean

        To get True or False as output based on the query.

      • Date

        To get date as output in the <YYYY-MM-DDTHH:mm:ss.sssZ> format.

      • Numeric

        To get an integer or decimal number as output.

      • String

        To get the text string as output.

      • Duration

        To get the duration (in milliseconds) as output. When you select this data type, IBM Process Mining generates the custom metric result as a duration in milliseconds.
        
        

   3. Add description in the Description field if you need to give any details about the metric.

   4. Turn on the Show custom metric statistics switch if you want to view the statistics of the custom metric in the Model tab, Statistics tab, and Compare tab. You can turn off the Show custom metric statistics switch if you want to hide the statistics of the custom metric in the Model tab, Statistics tab, and Compare tab.

      The changes in the Show custom metric statistics switch do not impact the use of the custom metrics in the Analytics dashboard.

   5. Enter the JavaScript code in the Custom metric code field.

      In Custom metric code, enter a JavaScript code to return results by applying conditions and object methods on the aCase object, which is passed as the parameter to the caseMetric function. To know more about the object methods that you can invoke on the aCase object, see the JavaScript Object methods for the case and event objects topic.

      In the JavaScript code, you must not use a global variable because that can impact the correctness of result.

   6. Click the Test Code button to validate the custom JavaScript code.

   7. Optional: preview your custom metrics test results:

   8. After the successful validation of the custom JavaScript code, click Next button to go to the Additional configuration step.

3. In the "Create custom metric" dialog, do the following in the Additional configuration step:

   1. Enter the unit of the custom metric result in the Unit field if you have any specific unit to display in the custom metric statistics.

   2. In the Assign to categories section, you have two options namely, Select Existing category or Create New category.

      By default, IBM Process Mining categorizes the custom metrics in the General metrics category.

   3. To select an existing category, do the following steps:

      1. Choose the Select Existing radio button in the Assign to categories section.

         

      2. Choose a category by clicking on a related category tile.

      3. Click the Create button to complete the creation of custom metric.

   4. To create a new category to link the custom metric, do the following steps:

      1. Choose the Create New radio button in the Assign to categories section.

         

      2. Enter a name in the Name field.

      3. Enter a description in the Description field.

      4. Select an existing icon or add a new icon in the Icon field.

         The maximum file size that you can upload is 200 KB.

         You can upload only the SVG, JPG, JPEG, or PNG format.

      5. Click the Create button to complete the creation of custom metric.

4. After you complete the creation of Custom metric, you can see details of the created custom metric under the assigned category in the Custom metrics table in the Custom metrics page (see 'Figure 2. Custom metrics').

   

   Figure 2. Custom metrics

Editing a custom metric

To edit a custom metric, do the following steps:

1. In the < Process> page, go to Manage>Custom Metric.

2. In the Custom Metric page, search and hover on the custom metric that you want to edit to see the Edit icon ().

3. Click the Edit icon () to see the "Edit custom metric" dialog.

4. In the Edit custom metric dialog, you can make changes in the following fields in the Details step per your requirement:

   • Description

     Description of the selected custom metric

   • Show custom metric statistics switch

     The switch to show or hide the custom metric statistics in the Model tab, Statistics tab, and Compare tab.

   • Custom metric code

     The custom JavaScript code

     You must validate the updated custom JavaScript code, by clicking the Test Code button.

5. After making changes in the Details step, click Next to go to the Additional configuration step.

6. In the Additional configuration step, you can make changes in the following fields per your requirement:

   • Unit

     Unit of the selected custom metric

   • Category

     Category of the custom metric

7. After the successful entry and validation of the custom metric, click the Save button to complete the editing of Custom Metric.

Deleting a custom metric

To delete a custom metric, do the following steps:

1. In the < Process> page, go to Manage>Custom Metric.

2. In the Custom Metric page, search and hover on the custom metric that you want to delete to see the delete icon ().

3. Click the Delete icon () to see the "Delete custom metric" window.

4. In the "Delete custom metric" window, click the Delete button to complete deleting the custom metric.

   The owner of the original project can delete the custom metric created in the snapshot of the original project.

   When you delete a custom metric, the output of the existing Analytics widgets, which applies the deleted custom metric, becomes invalid.

   When you delete a custom metric, the associated project filters are also deleted.

   When you restore a custom-metric based backup of a process model, IBM Process Mining re-creates only the custom metrics that are relevant to the selected project.

Filtering custom metrics by category

To filter custom metrics by category, do the following steps:

1. In the Custom metric dashboard, click the All dropdown on the upper left of the window to see the list of categories.

2. Select a category from the All dropdown.