Problem/Scenario

Operational Decision Manager (ODM) is the next generation of business rules technology, delivering the ability to centrally manage the business rules that determine the day-to-day automated decisions that are made in an organization’s applications and processes.

In this lab, we are going to show how you can integrate ODM business rules with a Streams application.

We have a fictional taxi company that monitors the whereabouts of its taxis in real-time.  Each of its taxis is equipped with a sensor that sends back location and occupancy information every so often.  This data is consumed by a Streams application that analyzes this data and displays the taxi’s whereabouts on a map in a browser.

Our taxi company also has a set of ODM rules that are used to calculate taxi fare based on distance travelled and an initial meter drop charge.

The goal of the lab is to run the fare calculation ODM rules in the Streams application and calculate taxi fares in real time using the geo-location data from the taxis.

There are three exercises in this lab.  In the first exercise, we are going to focus on how to execute an ODM rule in a Streams application.  In the second exercise, we are going to work on hot update of business rules, and see the effects of changes in the business logic without having to restart the Streams application. In the third exercise, we are going to add a new business rule and deploy it without restarting the Streams application.

Data

The data for this lab is located in the “Taxi/data/taxidata” directory within the SPL project. The data comes from the cabspotting project (cabspotting.org), which collected geospatial data for a number of San Francisco’s taxi cabs as they travelled throughout the Bay Area. There is a pre-written composite that will open the files and provide the data to your application.

The data is structured as:

stream< rstring ID, // The identifier for the taxi
        float64 latitude, 
        float64 longitude, 
        boolean occupied, // is taxi occupied (has a fare)
        int64 currentTaxiTime, //timestamp of the observation
        int64 fareStartTime, //  timestamp when the taxi became occupied
        float64 fareDistanceTravelled, // distance driven this fare
        float64 fareTotalCharge, // The total fare charge
        float64 totalDistanceTravelled, // taxi total distance
        float64 meterDropCharge, // The meter drop charge (set via ODM rules)
        float64 chargePerKM, // The cost per KM (set via ODM rules)
        int64 timeOfLastMovement, // The last time the taxi moved
        boolean hasAlert > // Whether or not the taxi has an alert set

Technology

This tutorial will focus on using the com.ibm.streams.rules toolkit. This toolkit provides streams applications with the ability to stream data through an ODM Rules Execution Server. This enables business analysts to construct rules and automate decisions in real time.

Operators to Use

The com.ibm.streams.rules contains one operator called the ODMRulesetExecutor operator. The ODMRulesetExecutor operator maps tuples to input parameters that are used as an input for executing the deployed rules. The operator passes these parameters to the ODM rules engine, which executes the rules and sends a response object that contains  the results to the operator. The operator converts the output parameters to tuples.

ruleslab1

Prerequisites

  1. Operational Decision Manager (ODM) with Decision Center Enterprise installed
  2. Firefox (not tested with IE or Chrome)

Setup

  1. Install ODM
  2. Set the ODM_HOME environment variable to the location where ODM is installed (add this to your ~/.bashrc)
  3. Import the projects found in TaxiDemoProjects into the ODM Rule Designer
  4. Deploy the Rule App Project
  5. Import the TaxiDemo SPL project from TaxiDemoSPLProject into Streams Studio

Quick Start Edition (QSE) Setup

These steps assume that the ODM server is installed on a separate server (referred to below as the ODM server).

  1. Create a directory path on the QSE VM that is the same as the ODM directory path on the ODM server (i.e. /opt/ibm/ODM).
  2. Copy the ‘executionserver/lib’ directory from the ODM server’s home directory to the directory created in Step 1
    • For example, this should result in the following path: ‘/opt/ibm/ODM/executionserver/lib’
  3. Set the ODM_HOME environment variable to point to this location
  4. If the rules are deployed to the file system on the ODM server, you will need to setup a shared directory so that the rules can be accessed from the VM
    1. On the ODM server, NFS export the directory where the rules are deployed
    2. On the QSE VM, mount the exported directory to a location that is readable by the ‘streamsadmin’ user
  5. Import the projects found in “TaxiDemoProject.zip” into the ODM Rule Designer on the ODM server
  6. Deploy the Rule App Project
  7. Import the TaxiDemo SPL project from “TaxiDemoSPLProject.zip” into Streams Studio on the QSE VM

Exercise 1 – Getting Started

Problem Statement

This exercise will focus on adding parameters to the ODMRulesetExecutor operator in order to execute ODM rules in a Streams application.

Configuring the Operator

  1. Open Streams Studio by double-clicking on the icon on the desktop
  2. Navigate to the “workspace_rules_exercise” workspace and click OK
    ruleslab3
  3. Expand the “Taxi” project and then expand the “application” namespace.
    ruleslab4
  4. Right-click on “Taxi [Build:Distributed]” and select “Open With>SPL Graphical Editor”
  5. In the Graphical Editor, there should be an error marker on the ODMRulesetExecutor operator. Hovering over this marker will indicate that the rulesetPath parameter is not set.ruleslab5
  6. Right-click on the ODMRulesetExecutor operator and select “Edit” to open the op-erator’s properties.
    ruleslab6
  7. Click on the “Param” tab to open the Param property page
    ruleslab7
  8. Click the “Add” button
  9. In the dialog that opens, select the “rulesetPath” and “rulesetAppDirectory” parameters, then click OK.
    ruleslab8
  10. Click in the “Value” column next to “rulesetAppDirectory” and add the following, including quotes:
    “/home/streamsadmin/demo”
    This is the directory where the ODM rules are deployed on the file system.
  11. Click in the “Value” column next to rulesetPath and the following, including quotes:
    “/TaxiRuleApp/TaxiDemo”
    This is the path to the rule application that was already deployed.
    ruleslab9
  12. Navigate to File>Save or press Ctrl+S to save the changes. The SPL application will build and there should be no errors.

Launch Streams Application

In the following steps, we will launch our application to the Streams instance.

  1. Expand the “Taxi” project and then expand the “application” namespace.
    ruleslab10
  2. Right-click on “Taxi [Build: Distributed]” and select “Launch Active Build Config”
  3. Click “Continue” in the dialog that appears
  4. Open the “Streams Explorer” view which is next to the “Project Explorer” view
  5. Expand “InfoSphere Streams 3.2.0.0”
  6. Expand “Instances”
  7. Right-click on the “default” instance and select “Show Instance Graph”
    ruleslab11
  8. The Instance Graph view will be made visible and will show the application running.
    ruleslab12

Viewing the Map

Windows Users:
If you are running Streams Studio on Windows, you will need to frequently “Synchronize” the project’s data folder in order to download the latest result files. Alternatively, you can start an httpd daemon on your Linux system and configure it to point to your project’s data folder. This will allow you to access the taximap.html file on your remote system using a URL (i.e. http://mylinuxserver/~jcancilla/Taxi/data/taximap.html). Leave me a comment if you have question on how to set this up.

In the following steps, we will view the results of the running application.

  1. Expand the “Taxi” project.
  2. Expand the “Resoures” folder.
  3. Expand the “data” folder
  4. Right-click on the “taximap.html” and click “Open with…>Web Browser”. This will open an external web browser and should display a map with markers. The markers represent the taxis that the application is tracking. The markers are updated every couple of seconds. When a taxi is occupied (has a fare), information about the fare is updated in the marker popup.ruleslab13

Exercise 2 – ODM Rule Refresh

Problem Statement

In this exercise we will demonstrate how to configure and launch an SPL application in such that it can detect updates to rules and use the new ruleset without having to restart the application. With the SPL application running, we will use ODM’s Decision Console to modify an existing rule and deploy it.

Open a new workspace

  1. Shut down Streams Studio if it is already started
  2. Start Streams Studio again
  3. Select the following workspace to open:  workspace_rules_exercise2

Cancel a Streams Job

Before launching a new job, we need to cancel the SPL job that was launched in Exercise 1.

  1. Open the “Streams Explorer” view which is next to the “Project Explorer” view
  2. Expand “InfoSphere Streams 3.2.0.0”
  3. Expand “Instances”
  4. Under “Instances” you should see the running job. Right click on the job and select “Cancel Job”. Click “Yes” to confirm that you want to cancel the job.
    ruleslab14

Configuring the Operator

In order to configure the ODMRulesetExecutor operator to detect that a ruleset has been refreshed, we need to add the “managementConsoleHost” and “managementConsolePort” parameters to the operator.

  1. Expand the “Taxi” project and then expand the “application” namespace.
  2. Right-click on “Taxi [Build:Distributed]” and select “Open With>SPL Graphical Editor”
  3. Right-click on the ODMRulesetExecutor operator and select “Edit” to open the operator’s properties.
    ruleslab15
  4. Click on the “Param” tab to open the Param property page
    ruleslab16
  5. Click the “Add” button
  6. In the dialog that opens, select the “managementConsoleHost” and “manage-entConsolePort” parameters, then click OK.
    ruleslab17
  7. Click in the “Value” column next to “managementConsoleHost” and the following, including quotes:“streamslab.localdomain”
  8. Click in the “Value” column next to “managementConsolePort” and the following:1883
    ruleslab18
  9. Navigate to File>Save or press Ctrl+S to save the changes. The SPL application will build and there should be no errors.

Launch Streams Application

In the following steps, we will launch our application to the Streams instance.

  1. Expand the “Taxi” project and then expand the “application” namespace.
    ruleslab10
  2. Right-click on “Taxi [Build: Distributed]” and select “Launch Active Build Config”
  3. Click “Continue” in the dialog that appears
  4. Open the “Streams Explorer” view which is next to the “Project Explorer” view
  5. Expand “InfoSphere Streams 3.2.0.0”
  6. Expand “Instances”
  7. Right-click on the “default” instance and select “Show Instance Graph”
    ruleslab11
  8. The Instance Graph view will be made visible and will show the application running.
    ruleslab19

Viewing the Map

Windows Users:
If you are running Streams Studio on Windows, you will need to frequently “Synchronize” the project’s data folder in order to download the latest result files. Alternatively, you can start an httpd daemon on your Linux system and configure it to point to your project’s data folder. This will allow you to access the taximap.html file on your remote system using a URL (i.e. http://mylinuxserver/~jcancilla/Taxi/data/taximap.html). Leave me a comment if you have question on how to set this up.

In the following steps, we will view the results of the running application.

  1. Expand the “Taxi” project.
  2. Expand the “Resoures” folder.
  3. Expand the “data” folder
  4. Right-click on the “taximap.html” and click “Open with…>Web Browser”. This will open an external web browser and should display a map with markers. The markers represent the taxis that the application is tracking. The markers are updated every couple of seconds. When a taxi is occupied (has a fare), information about the fare is updated in the marker popup.

Modify the Existing Rule

  1. Open a new tab in your web browser and then open the Decision Center Enterprise console (http://localhost:9081/teamserver)
    • Note: The URL for the Decision Center Enterprise console may be on a different port depending on how ODM was setup on your system)
  2. If you are prompted to login, the login credentials are: streamsadmin/passw0rd
  3. At the top, click the “Explore” tab
    ruleslab20
  4. On the left side, expand “Business Rules” if it is not already expanded, then click on
    ruleslab21
  5. On the right side, click on “baseChargeRule”
  6. Click “Edit” on the toolbar below the title
    ruleslab22
  7. On the left side, click on “Step 2: Content”
    ruleslab23
  8. On the right side, click on “175” and change this to “1.75”
    ruleslab24
  9. Click on “Finish”
  10. At the top, click the “Configure” tab
    ruleslab25
  11. Under “Deployment”, select “Manage RuleApps”
    ruleslab26
  12. Put a check next to “TaxiRuleApp”
    ruleslab27
  13. Click “Deploy” on the toolbar
  14. Click “Next” through each of the options and then finally click “Deploy”
  15. Switch back to the map and notice that the fare prices are more reasonable

Exercise 3 – Add a new Business Rule (Optional)

In this exercise we will add a new rule to the Decision Center. In Exercise 2, we configured the ODMRulesetExecutor operator to detect changes to a ruleset while the application is running.

The rule we will be adding will check if a taxi is operating between a certain time. If it is, the meter drop charge will be set to a defined value.

Open a new workspace

  1. Shut down Streams Studio if it is already started
  2. Start Streams Studio again
  3. Select the following workspace to open:  workspace_rules_answer2

Adding the Rule

  1. Open Decision Center Enterprise console (http://localhost:9081/teamserver)
    1. NOTE: The URL for the Decision Center Enterprise console may be on a different port depending on how ODM was setup on your system)
  2. At the top, click the “Explore” tab
    ruleslab20
  3. On the left side, expand “Business Rules” if it is not already expanded, then click on “charges”
    ruleslab28
  4. On the right side, click “New” to add a new Rule
    ruleslab22
  5. On the left side, under “Start from a template”, ensure that the “rushHourChargesTemplate” is selected, then click “OK” on the right side
    ruleslab29
  6. Set the “Name” to “rushHourCharges”, then click “Next”
    ruleslab30
  7. Click on the first “<enter a string>” and set the value to “12:00 pm” (without the quotes, but keep the space before ‘pm’)
  8. click on the second “<enter a string>” and set the value to “11:59 pm” (without the quotes, but keep the space before ‘pm’)
  9. When complete, the rule should look as follows:
    ruleslab31
  10. Click on “Finish”
  11. At the top, click the “Configure” tab
  12. Under “Deployment”, select “Manage RuleApps”
    ruleslab32
  13. Put a check next to “TaxiRuleApp”
    ruleslab33
  14. Click “Deploy” on the toolbar
  15. Click “Next” through each of the options and then finally click “Deploy”
  16. Switch back to the map and you will eventually see that the cost of a trip is at least $50

Summary

This lab demonstrated how the ODMRulesetExecutor operator can be used to apply rules on streaming data in order to analyze the data and automate decisions in real time.

8 Comments on "Rules (ODM) Toolkit Lab"

  1. Is there a trial or community edition of ODM available for use with this lab?

  2. At this point there is not a trial or community edition of ODM available for use with this lab. You need to have ODM already to use this lab.

    We have forwarded your request to the ODM team for consideration.

  3. How do I install ODM?

  4. Hi, I’m using ‘InfoSphere Streams Quick Start Edition VMware Image’: Can I run this lab or I will have the ODM problem? If yes, where is ‘Taxi/data/taxidata’ located? I cannot find it!

  5. chantalokh March 12, 2014

    hi everyone,
    i will work on a project similar to the one described in this doc, but i havent well understood what the “Operational Decision Manager” does exactelly here, cuz i have just streams,
    Thanks,

    • James Cancilla March 17, 2014

      ODM is a product that allows you to create and manage business rules. As developers, we are capable of implementing the logic that an application needs by including it in the source code of an the application. Changes that need to be made to the logic can only be made by a developer with the right technical skills. This can pose a challenge in some environments where the application needs to change frequently and those changes are better handled by the business users.

      This is where ODM comes in. ODM allows for creating and managing business rules that can be easily updated by business users without the need for deep technical knowledge. The business rules are typically created using plain English rather than complex source syntax. For example, a Java developer may create a conditional statement like this:

      if(taxiObj.distanceTravelled() > 100) { taxiObj.incrementFair(50) }

      However, a business rule may look something like this:

      IF the distance traveled in the taxi is more than 100km
      THEN add $50 to the total fair charge

      As you can see, the business rule is easier to read and write than the equivalent Java rule. Keep in mind, this is only a very high-level, simplistic explanation of ODM. I have provided some links below to the product site where you will find more information.

      http://www-03.ibm.com/software/products/en/odm/
      http://www-03.ibm.com/software/products/en/category/operational-decision-management
      http://www-01.ibm.com/software/decision-management/operational-decision-management/scenarios/

Join The Discussion