M
mparish
Guest
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 Download the installers Install Corticon Studio (5.5 is now available) Open Studio Create a new rule project Create a new vocabulary Create a new rule sheet Create a new test sheet Create a rule flow Start the Server Publish the rule flow (as a Decision Service) Create WSDL (using the deployment console) Import WSDL into your client code (or SOAP UI) Set your data as the web service request Call the web service 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 Right click in the Rule Project Explorer window and create a new project. Name it “Skydiver” Create the Vocabulary 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 Right click “add Entity” (on the Skydiver in the Skydiver.ecore window) Change its name from Entity_1 to Person Now add an attribute to Person Name it “risk”. Leave its data type as string. 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 Now create a new rule sheet called “DetermineRisk” Type (or copy) these two rule statements into the TEXT field in the RULE STATEMENT tab at the bottom Skydivers are high risk People under 35 are mow risk Drag the “isSkydiver” attribute from the rule vocabulary into condition (a) Select T (short for true) from the drop down in cell a1 Drag the “risk” attribute to Actions (A) Type high in cell (A1) (no quotes – they will be added automatically) Type 1 in the Ref cell of the first rule statement Select “Info” from the Post dropdown Select “Person” from the Alias dropdown It should look like this: Drag age to condition (b) Type 35 in cell (b2) Type low in cell (A2) Update the reference to the rule statement Save the rule sheet Test the Rules Create a new rule test named "test" Initially it will look like this Drag a Person to the input column and expected column Delete the risk attribute from the input (the rules will figure out its value) Set the values as follows Click the “Deploy” button to compile the rules Click the “Run Test” button to run the rules You should see this result: 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: Heavy Male Applicants who skydive have a High Risk rating. Married female applicants less than 35 years of age who live in California have a Low Risk rating. Any non-heavy person 35 and over who doesn't skydive is a medium risk Red haired people are low risk but only in Arizona Single skydivers are high risk 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: Skydivers – the people in a group that jump out of planes Non-skydivers – the people in a group that do not jump out of places 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. Create a new rule project called GroupSkydiver COPY/PASTE ALL YOUR ORIGINAL BASIC SKYDIVER RULE MODEL FILES INTO THE NEW PROJECT Open the new Vocabulary (double click on Skydiver.ecore) Add Entity. Name it “Group” 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 Right click on Group and select “add Association” 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 Save the vocabulary Create a new rule sheet named “Calculations” Open the advance view Expand Group in the Vocabulary Tab Drag Group into the Scope section 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: Double click on Group and enter group (lower case) Double click on persons and enter member (lower case) Drag person twice more and assign names membersWhoJumpOutOfPlanes and membersWhoDoNotJumpOutOfPlanes 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 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. 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) Save the rule sheet. Create a Rule Flow Create a new rule flow Drag the Calculations rule sheet on to it. Save it Create a Test Sheet Open the Test from earlier. Add a test sheet 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. Drag a group into the input. Drag some persons the group (make sure you drag the embedded persons and not the entity) Set the isSkydiver attribute for each person. For now you can remove the other attributes: Now deploy the rules 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 Now open the rule flow Drag the “IndividualRisk” rule sheet Connect it to the Calculations sheet: Save it 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
Continue reading...
Continue reading...