Creating custom KPIs

The KPIs that can be created within the Business console might not meet all the reporting needs of business users. In this case, technical users can implement custom KPIs and make them available in the Business console. Business users can then include these custom KPIs in their simulations.

Note: The sections Implementing custom KPIs, Importing custom KPIs to the Business console, and Defining custom KPIs in the Business console are intended for technical users to implement the custom KPIs and make them available in the user interface. Business users can follow the procedure in the section Using custom KPIs in the Business console to use custom KPIs in their simulations.

Implementing custom KPIs

  1. Create an XML descriptor file that you upload to the Business console. This file must have the extension .simx. To create the XML descriptor, follow the detailed procedure at Setting up custom data providers.
    As a starting point, you can use the job descriptors that are provided in the Test and simulation customization sample:
    • Loan Custom KPI (Basic).simx: Refer to this file if you want all the scenarios to be run in a single thread. In the job descriptor, you replace the reader with your item reader and the SimpleWriteListener class with your item write listener.
    • Loan Custom KPI (Multi Thread).simx: Refer to this file if you want the scenarios to be split into partitions that run in separate threads. In the job descriptor, you replace the reader with your item reader, the mapper with your partition mapper, the SimpleWriteListener class with your item write listener, the collector with your partition collector, the analyzer with your partition analyzer.

    You can find the sample files in the directory InstallDir/teamserver/samples/simulationcustomdatasource/simulationdatasource/data/.

  2. Implement the following Java™ classes:
    • Implement the item write listener:

      To retrieve the data used to compute the KPI, you must implement the javax.batch.api.chunk.listener.ItemWriteListener interface. This interface is part of the JSR 352 Java Batch specification. You can find it in the javax.batch-api JAR file in InstallDir/executionserver/lib. At runtime, one instance of the item write listener is created for each partition.

      See the SimpleWriteListener class in the Test and simulation customization sample for an example of an item write listener implementation (see link at the end of the page).

    • Implement the partition collector:

      To collect data for each partition, you must implement the javax.batch.api.partition.PartitionCollector interface. This interface is part of the JSR 352 Java Batch specification. You can find it in the javax.batch-api JAR file in InstallDir/executionserver/lib. At runtime, one instance of the partition collector is created for each partition.

      See the SimplePartitionCollector class in the Test and simulation customization sample for an example of a partition collector implementation.

    • Implement the partition analyzer:

      To receive intermediate data sent by the partition collector, you must implement the javax.batch.api.partition.PartitionAnalyzer interface. This interface is part of the JSR 352 Java Batch specification. You can find it in the javax.batch-api JAR file in InstallDir/executionserver/lib. At runtime, one instance of the partition analyzer is created for all the partitions.

      See the SimplePartitionAnalyzer class in the Test and simulation customization sample for an example of a partition analyzer implementation.

    • Error handling

      When implementing extensions for testing and simulation, you must catch and persist the errors to display them in the Business console when running the corresponding test suite or simulation.

      There are two cases:
      • For top-level errors that prevent the test suite or simulation from running properly, use the DecisionRunnerContext.persistError method to persist the error, then throw the error so that the test suite or simulation is stopped properly and the status is updated accordingly.

        See the open method of the RandomReader class in the Test and simulation customization sample for an example.

      • For errors at the scenario level that do not prevent the other scenarios from running properly, set them directly on the scenarios with the Scenario.addError method. These errors are automatically persisted with the scenarios by the built-in item writer.

        See the readItem method of the RandomReader class in the Test and simulation customization sample for an example.

    You can find the sample files for these classes in the directory InstallDir/teamserver/samples/simulationcustomdatasource/simulationdatasource/src/simulation.

  3. When implementing the KPIs, you must call the following method to persist the computed KPI results: DecisionRunnerContext.persistKpiResults. The KPI results are provided through a Map. The key corresponds to the KPI ID and the value to the KPI value.

    The KPI ID used for a given KPI must be the same as the ID used in the Business Console.

    The KPI value can be a single value or an array of bidimensional arrays for bidimensional values. The single value can be a simple data type or a String that can possibly contain HTML elements. For more information, see the Test and simulation customization sample.

  4. Package all your Java classes as a JAR file.
Note: You must include metrics that are required to compute KPI values in your implementation. You do not create them from the Business console.

Deploying custom KPIs to the Business console

After implementing the code for the custom KPIs, you must deploy the JAR file to the Business console. To do this, make sure that you enabled XOM management in Decision Center. See XOM deployment from Decision Center.

To deploy the JAR file:
  1. Open your project in the Business console and open the folder Resources > xom-libraries.
  2. If not already present, create a subfolder that you name additional-libs.
  3. In this subfolder, create a resource and add your JAR file as a resource. Save your changes.

Defining custom KPIs in the Business console

You must create the KPIs in the user interface and link them to your implementation, and you must upload the XML descriptor file:
  1. In the Business console Library, open the branch where you want to create a simulation by using custom KPIs.
  2. In Simulations > KPIs, create a new KPI. Select the check box to compute the KPI with a custom implementation.
  3. In the field that appears, enter the KPI ID that identifies this KPI in the custom KPI implementation. See Implementing custom KPIs.
  4. In the Data tab, upload the XML descriptor:
    1. Create a new data file.
    2. Select the XML descriptor file (.simx file) and import it.

Using custom KPIs in the Business console

Business users can now use custom KPIs in their simulation reports, in the same way they use standard KPIs in the Business console:
  1. In Report format, create a new report format and drag your KPIs onto the report, then choose how you want to render these KPIs. When editing the display type, the Text format is selected by default. Select the format according to the type of KPI your want to display: Text format for custom KPIs with a single value, or a chart format for custom KPIs with bidimensional values.
  2. In Simulations, create a new simulation and set the Report format field to the report format that you created in step 1, and set the Input data field to the data file that was created in Defining custom KPIs in the Business console, step 4.
  3. Run the simulation.
  4. The results of the simulation with custom KPIs are visible in Reports.
    Note: If you see the message no data to display in your report, make sure that the ID provided for the custom KPI corresponds exactly to the ID declared in the custom KPI implementation, and check that the JAR file containing the implementation is correctly deployed to the Business console.