Setting up custom data providers

You can use a custom data provider to obtain data for simulations in the Decision Center Business console.

1. Implement the custom data provider for a decision operation.

   You start by creating the XML descriptor file that you upload to the Business console for 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 simulation, you use the properties to enter values that are used to generate input data when you run the simulation.

   Note:

   The XML descriptor file must have the file extension .simx to work with the Business console. You can rename your XML file to add the proper extension.

   1. Create an XML descriptor file that contains the following information:
      1. Make <scenarioSuiteFormat> the root element of the XML file and add 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 to specify a display name in the specified locale.
      2. Optional: Add the <properties> 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 nonempty string.
         • displayName (optional): Set to specify 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 when you edit a simulation.
         • style: Set to "idp-block" to gather parameters into blocks when you display them in the Query parameters section.
         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 following .simx sample files to see more examples of properties.

      3. Optional: Add the <xom> 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>

         Note: If XOM Management in Decision Center is enabled (see XOM deployment in Decision Center), you do not need to specify the full URI with its version, and can use only the name of the JAR file. For example, you can use resuri://myCustomDataProvider.jar instead of resuri://myCustomDataProvider.jar/1.0. You then add the JAR file in resources/xom-libraries/additional-libs. When you run the associated simulation, the JAR file is deployed and its version number is computed.
      4. Add the <jobDescriptor> element that contains the job descriptor that is used to run the simulation. The simulation runtime instance is built on top of the JSR 352 Java™ Batch specification (see Java Batch Wiki).

         You can use the job descriptors that are provided in the .simx sample files 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.

   2. 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 <ODM_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-core JAR file in <ODM_InstallDir>executionserver/lib.

      See the RandomReader class in the simulation sample for an example of an item reader implementation.

   3. 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 <ODM_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.

2. Deploy 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 Rule Execution Server by following the steps in Deploying resources.

   After you deploy the JAR file, click the new resource in the Rule Execution Server console to display the resource information. Check that the URI is the same as the one that you put in the XML descriptor, otherwise the classes are not found when you run the simulation. If the URI is different, you must update it in the XML descriptor.

3. Upload 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:

   1. In the Business console Library, open the appropriate branch for the custom data provider.
   2. Open Data in the Simulations tab.
   3. Click the plus button + to load data.
   4. Enter a name and select the decision operation that is used with the custom data provider.
   5. Browse to the XML descriptor file and click Create.