Setting up custom data providers

You can use custom data providers to obtain data for tests and simulations in the Decision Center Business console.

You implement and deploy a custom data provider to Rule Execution Server. Then, you upload an XML descriptor file that sets parameters for this custom data provider to the Business console for use in tests and simulations (see also Sample: Test and simulation customization).

Implementing the custom data provider for a decision operation

You start by creating the XML descriptor file that you upload to the Business console for tests and simulations. The XML descriptor file works with a decision operation, and its properties are used to set parameters for the custom data provider. When you create a test suite or simulation, you use the properties to enter values that are used to generate input data when you run the test suite or simulation.
Note: To work with the Business console, the XML descriptor file must have the file extension .simx for simulations, and .tstx for test suites. You can rename your XML file to add the proper extension.
Your XML descriptor file must be written according to the following structure:
```
<scenarioSuiteFormat>
  <properties>
    <property>
      <value></value>
    </property>
  </properties>	
  <xom>
    <uri></uri>
  </xom>
  <jobDescriptor></jobDescriptor>
  <predicates> 	    	  
    <predicate/>
  </predicates>
</scenarioSuiteFormat>
```
Description of XML elements and attributes
<scenarioSuiteFormat>
It is the root element of the XML file and takes the following attributes:
- version: Set to 1.0.
- name: Set as a non-empty string.
- locale: Set to a value of the XSD language type.
- displayName (optional): Set a display name in the specified locale.
Optional: <properties>
Set this element if you want to define properties that set parameters for your custom data provider, and then add <property> elements. For each property, you must specify the following attributes:
- name: Set as a non-empty string.
- displayName (optional): Set a display name in the specified locale.
- required: Can be set to a Boolean expression (default value: true).
- editable: Can be set to a Boolean expression (default value: true). When set to true, the property is displayed in the Query parameters section in the Business console when you edit a simulation.
- style: Set to "idp-block" to gather parameters into blocks when you display them in the Query parameters section in the Business console.
Example:
<property name="A" style="idp-block/> <property name="B"/> <property name="C" style "idp-block/> <property name="D"/>
The example formats the properties as follows:
A B C D
You can use the following property types:

stringProperty

booleanProperty

dateProperty

dateTimeProperty

timeProperty

longProperty

doubleProperty

enumerationProperty
You provide a property value in a <value> element. The following example defines a property of type long and gives it a predefined value of 100,000:
<property name="scenario.count" xsi:type="longProperty" displayName="Scenario Count"> <value>100000<value> </property>
The following example defines a property of type double and gives it a predefined value of 0.5. The property is not displayed in the Query parameters section since the editable attribute is set to false.
<property name="loan.to.value" xsi:type="doubleProperty" displayName="Loan To Value" editable="false"> <value>0.5<value> </property>
The following example defines a property of type enumeration. This property supports the selection of a value from a list of values. When you edit this value in the Business console, the list of labels is displayed in a drop-down list and the "All" option is selected.
<property name="loan.year" xsi:type="enumerationProperty" displayName="Loan Submission Year"> <value> <select> <option label="All" selected="true">-1</option> <option label="2013">2013</option> <option label="2012">2012</option> <option label="2011">2011</option> <option label="2010">2010</option> </select> </value> </property>
Look at the .simx files provided in the sample to see more examples of properties.
Optional: <xom>
Set this element to specify the URIs of libraries that are deployed in the managed XOM and required for your custom data provider. You must include the JAR file that contains the classes of your custom data provider. Each library is added with an uri element, for example:
```
<xom>
<uri>resuri://myCustomDataProvider.jar/1.0</uri>
</xom>
```
You specify the full URI with its version, as shown in the example above, only if this version is already deployed in Rule Execution Server when you run the test suite.

If you do not specify the version, and use only the name of the JAR file (for example resuri://myCustomDataProvider.jar), the version number is the latest that is deployed in Rule Execution Server.

You must add the JAR file as a resource in your project, from the Business console, in the folder Resources > xom-libraries > additional-libs.
<jobDescriptor>
This element contains the job descriptor that is used to run the test suite or simulation. The tests and simulation runtime is built on top of the JSR 352 Java™ Batch specification.
You can use the job descriptors that are provided in the sample as a starting point:
- Loan Data Provider (Basic).simx: Refer to this sample 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.
- Loan Data Provider (Multi Thread).simx: Refer to this sample 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 and the mapper with your partition mapper.
You can find the sample files in the directory InstallDir/teamserver/samples/simulationcustomdatasource/simulationdatasource/data.

Setting the "execution.estimated.scenario.count" is optional. If you set it, you do not have to use the real number of scenarios. If you do not set it, you do not get a progress bar when you run the simulation in the Business console.
Only for testing: <predicates>
This element contains <predicate> elements, with id, name, operand, and operator attributes. This element is automatically added when you generate a scenario file from the Business console, and contains the definitions of the test.
The id attribute links the description from the test, and the implementation of the data provider. The item reader returns an object Test with expected values for each scenario. For example, assume that you have the following predicate element that checks the approved state of a loan in the report output of your loan application:
```
<predicate id="approved" name="loan approved" operand="report.approved" operator="Equals"/>
```
This predicate is identified by approved in your test scenario provider.
Implement the item reader:
To get the scenarios for your custom data provider, you must implement the javax.batch.api.chunk.ItemReader interface or extend the javax.batch.api.chunk.AbstractItemReader class. The interface and class are part of the JSR 352 Java Batch specification. You can find them in the javax.batch-api JAR in InstallDir/executionserver/lib.

At run time, one instance of the item reader is created for each partition. The open and close methods are called by the partition.

The readItem method allows the return of the next scenario for a partition. It returns null when there are no more scenarios to retrieve for this partition. A scenario contains the input parameters that are required to run a ruleset. It is represented by an instance of the com.ibm.rules.cdi.core.scenario class. This class can be found in the jrules-cdi-api JAR file in InstallDir/executionserver/lib.

See the RandomReader class in the simulation sample for an example of an item reader implementation.
Example for tests:
```
Scenario scenario = new Scenario();
// ... add  input values for the scenario ...
// Create  the Test object for the 'approved' predicate, and specify its expected value
Test test =  new Test();
test.setId("approved"); // Associate the Test object with the 'approved' predicate
test.setExpectedValues(new  Object[]{true}); // we expect the loan to be approved for this scenario
scenario.addTest(test);
```
Implement the partition mapper:
You must implement a partition mapper if you want the scenarios to run on different partitions in separate threads.

To implement a partition mapper, you must implement the javax.batch.api.partition.PartitionMapper 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.

The mapPartitions method allows the setting of the partition count, the properties for each partition, and optionally the maximum number of threads that are used to run the partitions. If you do not set the maximum thread count, it is equal to the partition count.

See the SimplePartitionMapper class in the simulation sample for an example of a partition mapper implementation.

Error handling

When implementing extensions for testing and simulation, you have to 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.

Deploying the custom data provider

After you implement the item reader and the partition mapper, generate a JAR file that contains these classes. Then, deploy the file to the Business console. To do this, it is recommended that you enable XOM management in Decision Center. For more information, see XOM deployment from Decision Center.

To deploy the JAR file:

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

Uploading the XML descriptor for the custom data provider in the Business console.

After you deploy the custom data provider classes, you can upload the XML descriptor file in the Business console:

For simulations:

In the Business console Library, open the appropriate branch where you want to run your simulation.
Open Data in the Simulations tab.
Click the plus button + to upload data.
Enter a name and select the decision operation that is used with the custom data provider.
Browse to the XML descriptor file and click Create.

For testing:

In the Business console Library, open the appropriate branch where you want to run your test suite..
Click New test suite in the Tests tab, and select the appropriate operation.
In File to use, browse to your test data provider and upload it to the Business console.
In the field Data provider parameters, check that the value corresponds to your test data provider.

You can then select the remaining details for your test suite configuration, and save and run your test suite.