In IBM Streams 4.2, we have added support for authoring rules compatible with the Operational Decision Manager (ODM) product in Streams Studio, converting them to an SPL composite and using them for real-time analysis in IBM Streams. In this tutorial, we will develop a sample application that will demonstrate each of the steps and walk you through the process of using rules within your streaming applications.

Skill Level

This tutorial assumes that you are already familiar with Java development, Streams Studio and SPL.

What are rules?

Before we develop the demo application, it is important to understand the concept of rules. Rules allow the developer to embed business logic within their Streams application in the form of natural language verbiage. A sample rule is given below:

if the sp O2 of 'the patient' is less than 95
add "spO2 should be greater than 95%" to the messages of 'the patient' ;
setAlert 'the patient' ;

As you can see, the rule describes in natural language that an alert is triggered on a patient if their spO2 level drops below 95%. As an example, the above rule can be embedded in a hospital’s streams application, and used to process incoming patient information coming in from sensors tracking patient health.

The advantage of a rule based system is that it is easy to read and maintain, it allows separation of developer code from business logic and allows non-developers (for example, management) to customize and tweak rules without the need for a whole scale software change.


The demo application that we will create will simulate a real-time patient health tracking streams application. It will use rules like the one shown above to check the patient’s health stats and trigger alerts when needed. We will be using Streams Studio to develop the rules as well as the streams application.

For the demo, we will need 3 projects in Streams Studio:

  • Health Java Object Model: This is a Java project containing Java classes that represent the object model for our rules.
  • Health Rules: This project will contain the rules that will be used in our streams application.
  • Health Streams Application: This contains the SPL code for our streams application and also contains the generated SPL composite from the rules described in the rules project.

Java Object Model

Before we develop the rules that will be used in the health application, we need to define the model on which the rules will act. The model can be defined as Java classes where the fields represent the attributes we will to process or produce as a result of rule processing. For the purposes of this demo, we will define a single Java class named Patient that will represent patient information that we are tracking and processing using our health rules.

To define the Patient class, perform the steps below:

  1. In Streams Studio, create a new Java project by launching the new Java wizard from the File > New Project > Java Project menu. For the demo, I named this health-xom to indicate that this is the execution object model of the health rules.
  2. Once the project is created, create a new Java class called Patient in the demo package.
  3. The Patient class will contain fields representing the health data for the patient. A copy of the Patient class is available here.

Tip: In order for the rules to use the fields defined in the Patient class, the fields must either be public or must have corresponding getter/setter method defined.

Health Rules Project

Once the model for the rules are defined, you can create a rules project that will contain the rules that will be run as part of the health application. The steps to define a rules project are as follows:

  1. Select File > New Project > Rule Project from the main menu. Click Next.
  2. Select Rule Project with a BOM  under Classic Rule Projects in the wizard. Click Next.
  3. Choose a project name such as HealthRules. Click Next.
  4. In the Rule Project XOM Settings wizard page, select the Java project that you created above. Click Finish.
  5. Enable the Decision engine rule engine for the project:
    1. In the Project explorer or the Rules Explorer, right click the project you just created and select Properties.
    2. Select Rule Engine and select Decision engine. Click OK.

Business Object Model (BOM)

Once the HealthRules project is created, open the file created within the bom folder in the HealthRules project. The BOM or  business object model shows the natural language interpretation of the Java object model that you created above. For example, the screenshot below shows the BOM for the Patient class that we defined above:

Patient BOM

As you can see, the above screenshot shows the Java class that the business object model is referencing along with the members of the Java class that are included in the BOM. In addition, the Class Verbalization section of this editor shown the natural language verbalization of this class – the patient, a patient etc. that will be used when you are creating rules.

The corresponding verbalization of each member can also be managed from this editor. Double clicking on a member will open an editor similar to the one shown above. For example, double clicking on heartRate will open the following editor:

heartRate BOM entry

The new rule project wizard automatically generates verbalization for all classes and fields within the classes. It will also smartly detect whether a particular member is read only or read/write and generate the appropriate verbalization. In the example above, the heartRate field in the Patient class has both getter and setter defined making it a read/write property. As you can see the wizard has generated a verbalization for reading the property – “the heart rate of a patient” as well as for setting it – “set the heart rate of a patient to a number”. These verbalizations can be customized if a different phrase makes more sense in your particular application.

Ruleset Parameters

Now that we have created our business object model, the next step is to set some ruleset parameters which defines the part of the model that will serve as input and/or output to our rules. The input and output parameters are also important because these determine the input and output attributes of the generated SPL composite as you will see below.

To define ruleset parameters, follow the steps below:

  1. Right click on the rules project and select Properties.
  2. Open the Ruleset Parameters property page and set the parameter as shown below for the demo:Ruleset parameters property page

Let us take a look at the property page options in more detail:

  • Name: A descriptive name for the ruleset parameter.
  • Type: A reference to the BOM type of this parameter.
  • Direction: There are 3 options for this field – IN, OUT or IN_OUT.
    • IN: Specifies that the parameter is to be used as input for the rules. The generated SPL for the rules will use these parameters as input tuple attributes.
    • OUT: Specifies that the parameter is to be used as output for the rules. The generated SPL for the rules will use these parameters as output tuple attributes.
    • IN_OUT: Specifies that the parameter is to be used as input and output for the rules. The generated SPL for the rules will use these parameters as both input and output tuple attributes.
  • Default Value: If a value is not set for this parameter, this value will take effect.
  • Verbalization: A natural language phrase to represent this parameter in rules.

Creating rules

Now that the setup for the rules is complete, we can create the actual rules that will be used in our streams application. To create a new rule, follow the steps below:

  1. Right click on the rule project and select New > Action Rule.
  2. Choose a package and name for the rule. For example, the demo project used alertrules as the package and sp02 levels as the rule name. Click Finish to create the new rule.
  3. Once the rule is created, the rule editor will come up where you can define the logic of the rule.

For the demo, we are creating a rule that tracks a patient’s oxygen saturation and tests whether it is within an acceptable range. If not, the rule triggers an alert and sends a message to the system indicating the problem. The rule definition is given in the What are rules? section above. In the Content section of the editor, add the rule definition as shown below:

SP02 levels rule

If you have set up the BOM and ruleset parameters as specified above, you will be able to use content assist (Ctrl+Space) within the content section in the editor above to complete the rule logic.

As an exercise, create a new rule called heart rate within range with the content as specified below:

if the heart rate of 'the patient' is less than 60 or the heart rate of 'the patient' is more than 100
add "Heart rate must be between 60 and 100!" to the messages of 'the patient' ;
setAlert 'the patient' ;

Generating SPL from rules

Now that we have written the rules that we want to use in our SPL application, we can develop the application and generate an SPL composite containing the rule logic defined above. In IBM Streams 4.2, we have added a rules compiler that converts the natural language rules to one or more SPL composites so that they can be incorporated into your streams application.

The rules compiler can be invoked in one of two ways:

  • Invoking rulescompiler from the command line
  • Streams Studio

For this tutorial, we will be using Streams Studio to generate SPL from the rules using the steps below:

  1. Right Click on the rules project and select Generate SPL Source Files… action.
  2. This will launch the Generate SPL Code From Rule Project dialog. Lets take a look at some of the options available in the dialog.
    • Rule Project: The rule project that contains the rules that should be converted to SPL
    • SPL Project: The SPL project where the SPL code should be generated
    • SPL namespace (optional): The SPL namespace into which the SPL code should be generated.
    • Options
      • Split rules by package: By default, the rules compiler will generate the logic of all the rules within a single operator. If you want to generate rules logic to be split into different operators by rule package, enable this option.
      • Generate function definitions: If you are using Java methods that you have defined in your rules, this option will generate stub SPL functions corresponding with each Java method. You must mirror the logic in your Java methods in SPL within these stub functions.
      • Generate type definitions: When enabled, this option will generate SPL types for each BOM type that is defined in your rules project.
      • Support dynamic rule updates: When enabled, the rules compiler will generate code that will allow you to dynamically update your rules logic within your SPL application without restarting the app.
  3. Select Generate to generate SPL code from the rules within the selected rules project.

For the demo, I selected the following options:

Generate SPL dialog

Note that I am generating the code into a HealthApplication SPL project that I created before and into the generated namespace to separate generated code from application code that I will write.

Health Application

Once the code is generated, the following artifacts will be available within the HealthApplication SPL application:

SPL Project structure

As you can see, the rules compiler has generated an SPL type called Patient that mirrors the Java object model type of the same name. In addition, the compiler has generated two function stubs – addToMessages and setAlert to match the Java methods with the same name. You must provide the implementation in the stubs to match the functionality that was available in the Java methods. Finally, the compiler has generated a composite called HealthRules (the same name as the project that the compiler was run against) that contains the logic of all the rules that were available in the rule project.

Once the artifacts are generated, you can use them in your SPL application. For this demo, we are developing a health application that will have patient data flowing through it. This patient data will be evaluated against the rules in the rules project and resulting alerts and messages will be output by the application.

The structure of the Health Application is shown below:


The application has 5 core parts:

  • Custom: This is the start operator that will send random sample patient data as tuples through the rest of the application.
  • Aggregate: Calculates an hourly running average of heart rates that is also sent as a tuple. This running average can be used in the rules as well.
  • Functor: Transforms the tuples output by the aggregate into a format that the HealthRules composite expects.
  • HealthRules composite: This is the generated composite containing the rules logic.
  • FileSink: This operator writes the result of rule processing to the file.
  • DirectoryScan: This feeds the control port of the generated composite and is used to dynamically update rules logic.

This application can be now run within a streams instance. The output will be generated into a results.txt file in the application data directory. The output will look as follows:

{age=18,alert=true,bpDiastolic=58,bpSystolic=98,heartRate=78.2929,hrAverage=78.2929,messages=["spO2 should be greater than 95%"],name="John Smith",roomInfo="",spO2=85,temperature=36.7439}
{age=49,alert=true,bpDiastolic=89,bpSystolic=129,heartRate=109.308,hrAverage=93.8007,messages=["Heart rate must be between 60 and 100!"],name="John Smith",roomInfo="",spO2=95,temperature=41.3963}
{age=15,alert=true,bpDiastolic=55,bpSystolic=95,heartRate=75.1556,hrAverage=87.5857,messages=["spO2 should be greater than 95%"],name="John Smith",roomInfo="",spO2=84,temperature=36.2733}
{age=47,alert=true,bpDiastolic=87,bpSystolic=127,heartRate=107.25,hrAverage=92.5019,messages=["Heart rate must be between 60 and 100!","spO2 should be greater than 95%"],name="John Smith",roomInfo="",spO2=94,temperature=41.0876}

As you can see, the above output shows the sample patient data that was processed by the rules and any messages/alerts that were generated as part of the rules being run against the data.

The source code for the demo application is located here.

3 comments on"Rules based processing in real-time streaming applications"

  1. Javeria Nadeem September 08, 2018

    hi, have been following this tutorial, everything is perfect however when i have running Main.spl file it gives an error of “updatedRules” directory in the directoryScan operator doesnot exist. I am not able to find out how to solve it; is it I have to create a directory named updatedRules myself? or is it the directory parameter in the directoryScan operator has not been defined properly. please tell me what’s the solution to it. Thanks

Join The Discussion