Outline

This workshop covers all the steps necessary to model, analyze, test and deploy, execute and monitor a Corticon Decision service.

Summary of Key Steps

  1. Download the installers
  2. Install Corticon Studio (5.5 is now available)
  3. Open Studio
  4. Create a new rule project
  5. Create a new vocabulary
  6. Create a new rule sheet
  7. Create a new test sheet
  8. Create a rule flow
  9. Start the Server
  10.  Publish the rule flow (as a Decision Service)
  11.  Create WSDL (using the deployment console)
  12.  Import WSDL into your client code (or SOAP UI)
  13.  Set your data as the web service request
  14.  Call the web service
  15.  Extract the results from the web service response

 

Preparation

Install Corticon Studio for Analysts

Choose 64 or 32 bit as appropriate. No special configuration required. Version 5.5 should be available now.

 

Basic Example

Open Studio

When you first open studio all the sections will be blank

Create a Rule Project

  1. Right click in the Rule Project Explorer window and create a new project.
  2. Name it “Skydiver”

Create the Vocabulary

  1. Right click on the project in the Project Explorer window and create a new vocabulary



    This can also be named “Skydiver”



    Your screen should now look like this




  2. Right click “add Entity” (on the Skydiver in the Skydiver.ecore window)



  3. Change its name from Entity_1 to Person



  4. Now add an attribute to Person



  5. Name it “risk”. Leave its data type as string.



  6. Create two more attributes:
    • Age of type “integer”, mandatory = “yes”
    • isSkydiver of type Boolean, mandatory = “yes”

      Your screen should look like this:

Model the Rules

  1. Now create a new rule sheet called “DetermineRisk”



  2. Type (or copy) these two rule statements into the TEXT field in the RULE STATEMENT tab at the bottom
    1. Skydivers are high risk
    2. People under 35 are mow risk



  3. Drag the “isSkydiver” attribute from the rule vocabulary into condition (a)

  4. Select T (short for true) from the drop down in cell a1

  5. Drag the “risk” attribute to Actions (A)

  6. Type high in cell (A1) (no quotes – they will be added automatically)

  7. Type 1 in the Ref cell of the first rule statement

  8. Select “Info” from the Post dropdown

  9. Select “Person” from the Alias dropdown
    It should look like this:



  10. Drag age to condition (b)

  11.   Type <35 in cell (b2)

  12.   Type low in cell (A2)

  13.   Update the reference to the rule statement



  14. Save the rule sheet

Test the Rules

  1. Create a new rule test named "test"
    Initially it will look like this



  2. Drag a Person to the input column and expected column

  3. Delete the risk attribute from the input (the rules will figure out its value)

  4. Set the values as follows



  5. Click the “Deploy” button to compile the rules



  6. Click the “Run Test” button to run the rules



    You should see this result:



  7. Now add some more persons with the following expected results:
    • age = 36, skydiver = true, (Expected risk= high)
    • age = 24, skydiver = true, (Expected risk = high)
    • age = 36, skydiver = false, (Expected risk = medium)
    • Run the rules and check the results:

Notice that the output does not match our expected results for persons 3 and 4.

In the case of Person[3] the result given by the rules is risk = low while the expected result is risk = high (because the person is a skydiver they should be high risk)

In the case of Person[4] the rules failed to assign a value to risk.

What went wrong? Let’s take a more detailed look

If you select Person[3] in the Output column you will see that it highlights the corresponding rule statements below:

You can see that for Person[3] two rules were applied. The first rule determined the risk to be high because the person is a skydiver. However a second rule also applied and determined that the risk is low (because the person is under 35).

The effect of this is that our correct answer (high) gets overwritten by the incorrect answer (low).

This situation is referred to as a rule conflict or ambiguity and we’ll need to look at our rules more closely to see what is happening.

In the case of Person[4] the rules simple failed to produce an output. This means that a rule for this situation is probably missing from our model.

Resolving the Problems

Here is our rule sheet again.

So what did we do wrong in modeling these rules?

Well, nothing! We really did model the rules exactly as specified.

Unfortunately the rules as specified are ambiguous.

So how do we resolve this?

Most likely the intent of rule #2 was to apply only to non-skydivers – in fact this vital piece of information might well have been on a yellow post-it note on the business user’s computer and not in the official rule documentation.

So first update the rule statement to reflect the correct rule:

Next update the rule sheet to correspond to the new rule #2:

Now, without having to rerun the test cases, recheck for ambiguity.

Corticon will confirm that there are no conflicts.

Next we need to address the missing rules. Click on the completeness button.

Corticon will add the missing conditions:

Obviously it cannot add the action. The rule author needs to do that. So add Medium.

And since there are now three rules you should add a new rule statement that corresponds to the new rule.

Now save the rule sheet and rerun the test case.

The actual output should now match the expected output:

 

 

What Happens when it gets More Complex?

Assuming we have resolved the ambiguities and incompleteness we might next ask “What happens when it gets more complex”

So let’s change rules 1, 2 and 3 and add three more:

  1. Heavy Male Applicants who skydive have a High Risk rating.
  2. Married female applicants less than 35 years of age who live in California have a Low Risk rating.
  3. Any non-heavy person 35 and over who doesn't skydive is a medium risk
  4. Red haired people are low risk but only in Arizona
  5. Single skydivers are high risk
  6. Divorced, widowed or separated Arizonans are medium risk on Tuesdays

Do we have any conflicts in these rules and under what circumstances?

Are there any missing rules?

Try figuring it out manually and then put the rules into Corticon and see how much easier it is. You will need to add some more attributes to the vocabulary to support these rules.

What’s wrong with having Boolean attributes for single, married, divorced, separate, widowed?

Try writing this in java. Or Drools. Or ABL

Ignore conditions  j for now

Add Custom Data Types

Up to this point you have been typing in the values used in the rule columns.

It’s possible to predefine these values as custom data types.

To do this, open the vocabulary and select the top level “Skydiver”

Enter a custom data type for gender as follows:

Do the same thing for any other attributes for which you want to have predefined lists.

e.g. maritalStatus = {married, single, divorced, widowed, separated}

In order for a custom data type to be used you must select it in the attribute data type property:

Date Operators

The condition in row h is constructed by dragging the “today” function from the Operator tab:

This gives us a date.

Then we can drag the “dayOfWeek” operator from the list of data related operators:

Since there is no built-in function called “isLeapYear”, either that attribute needs to be passed in to the rules or we need to create a rule sheet that figures out if the current date is a leap year.

Such a rule sheet might look like this:

 

Rules for Invalid or Unrecognized Values.

If we cannot be sure that the calling application will pass in valid data we may wish to add a validation rule sheet such as this

other (not in quotes) means any value that is not defined in the custom data type associated with this attribute.

The Missing Rules

After Compression

 

 

How to Deploy Decision Services

Install the Corticon Server

Install the Corticon Server from the USB drive.

Start the Corticon Server

Make sure the server is started. You should see a DOS window like this:

IF THE LICENSE HAS EXPIRED

The license file for the default installer may have expired so copy the CcLicense.jar file from the USB drive to this directory:

Server\Tomcat\webapps\axis\WEB-INF\lib

The license for Studio is good for 90 days

Restart the server to pick up the new license file

NOTE: You must start server once in order for the WEB-INF folder to be expanded from the installer WAR file.

 

Configure the Decision Service

Let’s take the basic Skydiver rule model that you created first and deploy it to the Corticon Server as a web based decision service

Create a rule flow

Name it Skydiver

Drag the rule sheet DetermineRisk onto the rule flow

Edit the properties as follows

Publish the Decision Service

Select the Publish option by right clicking in the project explorer:

If necessary, select the server URL and enter admin/admin for the user and password.

For version 5.4 use 8850

Select the decision service from the list. You may also see your other decision services in this list.

You can rename it here if you wish.

NOTE: The first time you deploy its status will show as “New”

When you republish an existing decision service you will see the status listed as “Update” and you will need to explicitly check the “Republish” button in order to activate the “Finish” button. This is a safety feature to prevent accidentally updating the wrong decision service.

TIP: If you have a lot of projects and rule models open at the same time, Corticon will search for and display ALL valid rule flows. This can take some time so you may want to open the project you are working on.

 

 

How to Monitor Decision Services

You can verify that your decision service was successfully deployed by starting the Corticon Web Console.

Start the Web Console

Enter this URL in Internet Explorer (other browsers may or may not work)

http://localhost:8082/axis/  or http://localhost:8850/axis/

 

Login using admin/admin

This will bring up the main menu:

Select “Decision Services” and you will see something like this

Click on the Skydiver entry to bring up the Decision Service Details:

If you click the “view” hyperlink you can see the rules displayed in the browser window:

You can also switch to the business view that shows the natural language form of the conditions and actions:

Selecting the “Create New Version” button will create a copy of the decision service that you can edit in the web interface. Any changes you make will not be accessible via web services call until you “Promote to Live” (a new button will appear)

The new decision service will appear in the list as follows:

The new version will have its major version number incremented.

Notice the “Live” column is not checked.

“Modify Current Version” will increment the minor version number.

By clicking “No/Remove” (in the “Deployed from CDD” column) you can revert back to the prior version.

Decision services that were deployed as CDDs using the deployment console cannot be removed using the web interface. The CDD must be removed from the CDD folder.

 

Configure the Decision Service

Select Service Configuration and add Person.risk to the monitored attributes:

Make sure that you have these settings under “Decision Service Options” under the “Configure Rules Server” menu item.

These settings are necessary if you want the server to track decision service performance.

 

 

How to Execute Decision Services

From Corticon Studio

Now that the decision service has been deployed and configured we can execute it from the Corticon Studio Tester:

Start with an existing test case and make a copy named “Server”

Double click on the file name (in this case the Skydiver.erf)

Select the appropriate server if more than one is listed.

Then click the Update List button.

Then choose the correct decision service from the list:

Now your test case should look like this:

Now run the test (notice that the compile option is disabled since we are executing the already compiled version in the server)

Now go back the web console and refresh the list of decision services:

You should see that the decision service called Skydiver has been executed once.

Click on the number 1 and look at the Distribution Chart

You can see that the single execution processed the four transactions that were in the test data input. In a similar fashion you can monitor any of the attributes used in the decision. For numeric attributes you can also choose to specify ranges of values for the pie chart rather than discrete values.

From SOAP UI (Optional Exercise)

If you are familiar with SOAP UI then you can use that as a test client to invoke Corticon decision services. There’s an installer for SOAPUI on the USB drive

Simply create a new project, import the Corticon WSDL, and fill in the decision service name and some data values.

Start SOAP UI

Create a new WSDL Project

Enter Details for the New Project

Locate the Initial WSDL

This will be in the project workspace.

If it’s not there then you will need to create it using the Corticon Deployment Console:

Select the rule flow in the Top Section

Choose WSDL in the bottom section

If necessary select the Work Document Entity “Person”.

Ensure that “Vocabulary Level” is selected

This ensures that all entities and attributes are included in the WSDL even if they are not currently being used by the rules. In general it’s better to choose this because then you will not need to recreate the WSDL if a rule author should start to use a new attribute.

However, if the vocabulary is very big and you are only using a few attributes then it may be more efficient to choose “Decision Service Level”.  In this case only the attributes actually used in rule sheets will be included in the WSDL.

Save the WSDL. If you are going to be integrating with OE then a good place to save it is in the project Workspace

This should show up in the SOAP UI project

You should see something like this:

Create the Corticon Request block

Enter the DecisionServiceName as “Skydiver”

Remove the target version, effective date and usage

Later you can experiment with providing either the version number or the effective date – but not both.

Remove the comments (in black)

Remove the risk entry.

Enter values for the other fields

This corresponds to what you entered in the Corticon Tester.

In fact you can generate this Request payload from the Tester

Now submit the request by clicking the green triangle:

You should get a result that looks like this:

If you want, you can put multiple persons in the payload. Just make sure to give them unique ids so you can match up the resulting rule messages (using the href)

You can use SOAP UI to do load testing by putting this request in a continuous loop:

Create a new TestSuite

 

Create a new TestCase

Add the request to the testcase

Choose the TestSuite and TestCase

Use the defaults

Should look like this:

Run once to test it:

Now set it to loop continuously and start it.

Let it run for about a minute and then click on the X to stop it (you might have to click a couple of times to get its attention)

Now if you look in the Web Console you will see something like:

And

If you add some other test cases then the pie chart may be more interesting.

For example


Advanced Example (You can try this if you completed the basic example)

In the basic example the rules applied only to individuals. Even if we passed in many individuals the rules evaluated them independently. Corticon automatically does this so we didn’t need to do anything special for that to happen.

Let’s suppose now that our skydivers have organized themselves into skydiving groups and the groups want to apply for insurance.

Now in addition to the rules that assess the risk of the individuals we will have some additional rules that assess the eligibility of the group as a whole.

Here are the rules:

G1: If there are fewer skydivers than non-skydivers then the group is INELIGIBLE

G2: If there are 10 or more members then the group is INELIGIBLE.

G3: If there is any skydiver over 65 then the group is INELIGIBLE

G4: If none of G1..G3 apply then Group is ELIGIBLE

These rules introduce some new concepts:

  1. Skydivers – the people in a group that jump out of planes
  2. Non-skydivers – the people in a group that do not jump out of places
  3. Members – all the people that belong to a skydiving group

We’ll also need a new rule sheet that evaluates the group. This new rule sheet will work in conjunction with the original rule sheet:

Since we now have a new business object to consider (the Group) we need to modify the vocabulary to model that object and its relationship to the individuals.

  1. Create a new rule project called GroupSkydiver
  2. COPY/PASTE ALL YOUR ORIGINAL BASIC SKYDIVER RULE MODEL FILES INTO THE NEW PROJECT
  3. Open the new Vocabulary (double click on Skydiver.ecore)
  4. Add Entity.
  5. Name it “Group”
  6. Add the following attributes:
  • name (string)
  • eligible (Boolean)
  • numberOfSkydivers  (integer, transient, mandatory)
  • numberOfNonSkydivers (integer, transient, mandatory)
  • numberOfMembers (integer, transient, mandatory)

TIP: once you have created the first integer attribute you can copy/paste to create the others. Your vocabulary should now look like this:

Establish the Relationship between Groups and Persons

  1. Right click on Group and select “add Association”



  2. Enter the following

NOTE: add an “s” to the source-to-target name to indicate that there are many persons in a group. This is not required, but reads better. In fact you can choose any name you like for this.

Now your vocabulary will look like this

  1. Save the vocabulary
  2. Create a new rule sheet named “Calculations”
  3. Open the advance view



  4. Expand Group in the Vocabulary Tab
  5. Drag Group into the Scope section
  6. Drag the embedded persons (not the free standing Person) and drop onto the Group in the Scope section. This is what tells Corticon that you want to work with the persons that are associated with each group:

Now drag attributes as follows:

                                    

  1. Double click on Group and enter group (lower case)
  2. Double click on persons and enter member (lower case)
  3. Drag person twice more and assign names membersWhoJumpOutOfPlanes and membersWhoDoNotJumpOutOfPlanes
  4. Also drag the isSkydiver attribute to both

    The Scope should now look like this:



    What we have done here is to define three different ways (aliases) to refer to the persons that belong to a skydiving group.
    At this point each of the aliases refers to ALL the members of the group. Simply naming an alias “membersWhoJumpOutOfPlanes” does not cause that alias to contain only skydivers. We have to tell Corticon how to determine the persons that are in that alias. This is done by using the filter section

  5. In the filter section add these two statements (by dragging from the Scope)



    This causes only those persons for whom isSkydiver=false to go into the membersWhoDoNotJumpOutOfPlanes collection; similarly those with isSkydiver=true go into the membersWhoJumpOutOfPlanes collection.
    This now gives us a convenient way to refer to the two subsets of the group members.

  6. Add the following to the Action section of the rule sheet.



    If you get an error make sure you have defined the attributes as type integer.
    NOTE: The checkmarks are in column zero which means they are executed unconditionally (but not necessarily first or even in that order – Corticon will analyze the rules and determine the correct order of execution)

  7. Save the rule sheet.

 

Create a Rule Flow

  1. Create a new rule flow
  2. Drag the Calculations rule sheet on to it.
  3. Save it

Create a Test Sheet

  1. Open the Test from earlier.
  2. Add a test sheet



  3. Choose the rule flow you just created:



    NOTE: if the OK button is greyed out it may be because the rule flow does not use the same vocabulary as your test sheet.

  4. Drag a group into the input.
  5. Drag some persons the group (make sure you drag the embedded persons and not the entity)
  6. Set the isSkydiver attribute for each person.
  7. For now you can remove the other attributes:



  8. Now deploy the rules



  9. And run the test




    You should get something like this:



Add Some New Rules

Now create a new rule sheet called EvaluateGroup and add these rule statements to the rule sheet (you can copy/paste)

G1: If there are fewer skydivers than non skydivers then the group is INELIGIBLE

G2: If there are 10 or more members then the group is INELIGIBLE.

G3: If there is any skydiver over 65 then the group is INELIGIBLE

G4: If none of G1..G3 apply then Group is ELIGIBLE

 

Now we can easily build rules 1 and 2

For rule 3 we will write membersWhoJumpOutOfPlanes->exists(age >65)

Finally you can either add rule 4 manually, or use the completeness checker to add it.

The rule sheet should now look like this

Now save this and open the test sheet and add some more data to test that this rule sheet is working. You should add at a test case corresponding to each rule column.

Make sure you also create at least one group that is eligible.

What happens if there are no skydivers or no non-skydivers?

Try setting minimum filters by right clicking the filter column

    

Does it work now?

NOTE:

It is possible to combine the calculations and the rules in a single sheet.

The calculations would be entered as actions using column zero.

If you have time try this out and observe that Corticon correctly figures out the appropriate order of execution of the combined rules.

However, it’s probably easier to follow if they are separated.

Add the Individual Risk Rule Sheet to the Rule Flow

  1. Now open the rule flow
  2. Drag the “IndividualRisk” rule sheet
  3. Connect it to the Calculations sheet:



  4. Save it
  5. Rerun the tests.

You will probably find some warning messages like these

That’s because some data is missing from your test cases.

Fill in the missing data and rerun the tests.

Now you should find you are getting messages for both Groups and Persons

If your messages are not showing up make sure that you have filled in the Ref, Post and Alias columns in the rule statement section.

If you are getting too many messages, make sure you are posting to the correct alias

 

Some things to Consider

What happens if there is a skydiver with no age?

What about a non-skydiver with no age?

What happens if we don’t know whether they are a skydiver or not?

What about invalid values?

Another Enhancement

Add a rule (in a new rule sheet) that checks to see if the average age of the skydivers is greater than 60.

If so then set a flag that an additional premium is required.

Risk Scoring

Add rules to assign a numeric risk score to each individual (eg  high=10, med=8, low=5)

Add a rule sheet to classify the entire group based on the average score of all the members

R1: VERY LOW: Average risk score <=5

R2: LOW: Average risk score 5..8

R3: MEDIUM: Average risk score 8..12

R4: HIGH: Average risk score 12..15

R5: VERY HIGH: Average risk score >=15


 

Download

 Download PDF version