2013 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.

Transcription

1

2 Introduction... 3 What are Business Rules?... 3 What is a Corticon Decision Service?... 4 What is the Corticon Business Rules Server?... 4 What is Progress Rollbase?... 4 Installation and setup... 5 Install Corticon Studio... 5 Install Corticon Server... 5 Install Rollbase... 5 Create a simple Corticon application... 5 Install or walk through the Corticon-provided tutorial... 5 Create and deploy the Decision Service... 6 Create a Rollbase application... 6 Create a New App... 6 Create an Object Definition... 6 Add fields to the Object and Views... 6 Calling the AirCargo Decision Service Create template for the Decision Service request Create Trigger to make the Decision Service request Create a Trigger to process the Decision Service response Testing the integration Conclusion Appendix A: Trigger Object Script Using XPath Appendix B: Trigger Object Script Using DOM Appendix C: Decision Service Response Example... 17

3 Introduction This document explains how to invoke a Decision Service in the Progress Corticon Server from a Rollbase application. The processes described in this document assume Corticon version 5.3 and later. External references are made to sections of the documentation of each product and the reader should be aware that some details may vary in other versions of the products. This paper shows the integration between an on-premise installation of Corticon and Rollbase - that means you are not using a hosted solution and have the software running on servers under your control. Note that steps would also work with the hosted version of Rollbase - Progress Pacific - assuming your Corticon server is accessible from the public internet. What are Business Rules? Business applications are typically composed of certain elements: application or infrastructure logic (security, translations, session and context management) and business or domain logic (applying logic and transformations to a set of business data). This business logic is typically made up of business rules. These rules can be discovered in application code by their structure typically a condition and the related actions when this condition is true and their content a business domain like life insurance. In a life insurance context, a business rule condition might take the form of if a policy applicant is a smoker, then she falls into a high-risk category or the sum of a policy s beneficiaries allocated percentages must be 100, with an associated action of update the applicant s status and report that fact and stop processing any more rules and return a violation event or message, respectively. The consequences of these rules actions are handled by the application invoking them; the rules themselves take no actions and have no concept of what to do next. This is in contrast to Business Process Modelling (BPM). Business rules produce knowledge; work flows perform business work 1. This concept allows different workflows or processes (whether formal or not) to use the same business rules (i.e. the same set of knowledge) to perform different tasks. 1

4 What is a Corticon Decision Service? A Decision Service automates a discrete decision-making task. It is implemented as a set of business rules and exposed as a Web Service (or Java service). By definition, the rules within a Decision Service are complete and unambiguous; for a given set of inputs, the Decision Service addresses every logical possibility uniquely, ensuring decision integrity. A Vocabulary defines a relational data structure against which rules are applied. This relational data structure contains domains, entities, attributes and relationships (incl. cardinality); the vocabulary is used to build a one or more Rulesheets, which each contain related rules. A Ruleflow aggregates one or more Rulesheets into a sequence or series or rules that must be executed, and is exposed as a named Decision Service, and is deployed to the Corticon server. Multiple versions of a single Decision Services can be deployed concurrently. What is the Corticon Business Rules Server? The Corticon Business Rules Server is a scalable and reliable high-performance system resource that manages pools of Decision Services and executes their rules against incoming requests. The Corticon Server can be easily configured as a Web Services server, which exposes the Decision Services as true Web Services. The Corticon Server is a Java application, typically called via Web Services (in the box uses Apache Tomcat). Also provided are a native API via Java &.NET and a Java-based batch client. For the integration described here they must be deployed to a server and exposed as SOAP based Web Services. What is Progress Rollbase? Progress Rollbase is a cloud platform that allows rapid creation of software as a service (SaaS) business applications using point and click, drag and drop tools in a standard Web browser with a minimal amount of code. Progress Rollbase can be deployed to any cloud or in-house infrastructure. More information about Rollbase can be found at More information about installing and using Rollbase is available at the Rollbase Resources page at including the comprehensive Rollbase in Action book. Chapter 18 of that book describes installation and configuration.

5 Installation and setup Install Corticon Studio Corticon Studio is is the tooling environment for creating Business Rules, available on Progress ESD. Download and follow the installation instructions. For additional help, see the StudioHelp.pdf document, which can be accessed from Corticon Studio by selecting Help>Contents from the main menu. Install Corticon Server Corticon Server the runtime server needed to execute your Business Rules, and expose them as Web Services. This is available on Progress ESD. Download the Corticon Server 5.3 Installer and run it. Make sure you select a Complete install when prompted (includes Corticon and Tomcat servers, and Samples). Once installed, start the server from the Start menu. Install Rollbase Download the latest version of Rollbase Private Cloud from the Try-It site at and install it following the instructions. Once installed, start your Rollbase Private Cloud instance. Create a simple Corticon application Install or walk through the Corticon-provided tutorial The Corticon Studio Tutorial provides an overview of how to construct a simple Corticon Decision Service. The tutorial can be accessed from Corticon Studio by selecting Help>Contents from the main menu. The Tutorial is based on the Cargo vocabulary, which is used to create a set of rules for a fictitious shipping company. The Decision Service created determines the kind of shipping container (standard, oversize, heavyweight or reefer) that some cargo needs to be packed in, based on weight, volume and contents. (A reefer is a refrigerated container.)

6 Create and deploy the Decision Service Using the Project > Publish menu item, publish the Rule flow. Change the Decision Service Name to AirCargo from the default, provided value. Take a note of the URL you use to publish the Decision Service (the default value is particularly the host (eg localhost) and port (eg 8082). Create a Rollbase application We will now create a simple Rollbase app that provides our client for the AirCargo Decision Service. You will need to be logged in to Rollbase to do so. Create a New App Select the New App option from under the Applications dropdown (in the right-hand column). Select the A new Application (from scratch) option, and click Create. Give the application a name: we will use CargoShipping and click Save, keeping the default values. Create an Object Definition We now need to create an object: objects are the core building block of Rollbase and can be thought of in similar terms to a database table, only far more powerful. Rollbase allows you to specify attributes and properties which add and extend the behaviour of the object automatically. Once the application saves successfully, you will be prompted to create an Object Definition, by selecting the + link. Select the A new Object (with Tab) option and click Create. We will name this object Cargo and will further select the Audit Trail property from the Optional Object Properties. We will keep all the other default values and click Save. Rollbase will prompt for Tab details we will simply take the default values and Save. Add fields to the Object and Views At this point we have the basic skeleton for an application Rollbase has created a number of screens automatically for us, and we are now taken to the CargoShipping application s main screen. An example appears below. Of particular importance to note here is that we now are actually running the application.

7 Selecting the New Cargo button takes us to an input screen, as seen below. This screen is not especially useful yet, since there s only a single field, and we need more information in order to make a decision. Rollbase allows us as long as we have sufficient permissions to edit screens and objects on the fly, via the Edit this Page functionality highlighted below. Once in the Page Editor, we can add the fields we need to capture and display the data relating to our AirCargo Decision Service.

8 We will add four new fields to our Cargo object, by dragging the New Field option from the Create group into the Default New Fields Section. For more information see Chapter 1 in Rollbase in Action. The necessary fields are described in the table below. Name Type Comment Weight Integer Required Volume Integer Required Needs Refrigeration Checkbox Once the fields have been added, the screen should look similar to the screenshot below. We now select Save & Synchronize, and check the Select All checkbox and select Save. We are now taken into the New Cargo (ie add record) screen, which now contains our new fields.

9 We also want to see the results of the Decision Service call somewhere. We will add that to the Cargo View and Edit Cargo pages. To do so, we select the newly-created Cargo record from the list, using the Edit Action link. We select the Page Editor again using the Edit this Page link. We now add two new fields, as described in the table below: Name Type Comment Container Text Read Only Container Messages Text Area Read Only After this, the screen should look similar to the screenshot below.

10 Now select Save. Note that we do not want to synchronize this with the New Cargo page. This returns us to the application s New Cargo page. We can now enter some data into the page. The values aren t especially important at this point. Once done, click Save. Calling the AirCargo Decision Service We now need to tell Rollbase to call the AirCargo Decision Service. We do this using document templates and event triggers. These are described in Chapter 10: Workflow and Triggers. To add the necessary triggers, select the dropdown from the Cargo tab, and select the Object Definition from the menu (see below). We are now in the Object View page. Create template for the Decision Service request Rollbase communicates with Corticon using Web Services. This uses specially-formatted XML documents for both the request and response. Rollbase allows us to create templates so that we don t have to manually create the XML on each request. The first step is to create a template for the request. We first need to save the template code to a temporary location on disk. Save the following text to a file on disk. Name it something like request.txt.

11 <soapenv:envelope xmlns:soapenv=" xmlns:urn="urn:corticon"> <soapenv:header/> <soapenv:body> <urn:corticonrequest decisionservicename="aircargo"> <urn:workdocuments> <urn:cargo> <urn:weight>{!weight}</urn:weight> <urn:volume>{!volume}</urn:volume> <urn:needsrefrigeration>{!needs_refrigeration#value}</urn:needsrefrigeration> </urn:cargo> </urn:workdocuments> </urn:corticonrequest> </soapenv:body> </soapenv:envelope> Scroll down to the Templates section or jump there via the Templates link in the grey header section. Now click on the New Document Template button to add a new template. Give the template a name: for example AirCargo_request makes sense in our case. Click on the Browse button and select the file you just created. Save the template. Before going further, let s look at the content of the template. There are a few points to note. i) The name of the Decision Service to call AirCargo is contained in the urn:corticonrequest node, in the decisionservicename attribute. This value is required by the Corticon Server in order to know which Decision Service to call. There are other values that can be provided via attributes here, such as decisionservicetargetversion and decisionserviceeffectivetimestamp. For more information on using these attributes, see the Corticon documentation. ii) The urn:cargo node is the root node for the XML that represents the Corticon Vocabulary entity being used in the Decision Service. Note that the children of this element represent the attributes. iii) Rollbase allows us to change the values passed in to the Decision Service by means of tokens. These tokens are placeholders which are replaced by the values on screen when the Decision Service is called. The Template Helper, available in the Edit Document Template screen, can show us the string tokens available for use in a template. Create Trigger to make the Decision Service request We now create a trigger which uses this document template and calls the AirCargo Decision Service. From the Object View page, scroll down to the Triggers section or jump there via the Triggers link in

12 the grey header section. Select New Trigger, choose the Send HTTP POST Request option near the end of the list, and click Next. We first need to decide when this trigger is to be fired, in the Trigger Timing section. Chapter 10 has a section on Order of Execution which illustrates the order in which triggers are fired in Rollbase. For this trigger, make sure that the After Create and After Update options are checked. This means that any time the values in the Cargo object change the trigger will fire. Give the trigger a name AirCargo_DecisionServiceRequest for example and set the Target URL field. Replace localhost and 8082 in the URL below with the values you noted when deploying the Decision Servicer earlier. There are 2 more values to provide: add an HTTP Header called SOAPAction with a value of urn:corticon. Then select the template we just added from the Template drop-down. Click Save & New to enable us to add the response trigger. Create a Trigger to process the Decision Service response You should be on the New Trigger page already. If not, from the Object View page, scroll down to the Triggers section or jump there via the Triggers link in the grey header section. Select the Object Script trigger type. Select the After Create and After Update timings, and give the trigger a name. Let s use AirCargo_DecisionServiceResponse, which is consistent with the request trigger. We currently need to explicitly add logic to process the response XML from the Corticon Decision Service. Generally speaking, we can perform a variety of actions, including updating record data, or displaying a message to the user. In this example we will update the current Cargo record in Rollbase. Code to do this is in Appendices A and B. The code in Appendix A to this document uses newer XPath functionality, which was added to Rollbase relatively recently. has more details. Note that there are more details in the release notes that are available from that page. The code in Appendix B uses a more traditional approach to traversing the XML node tree and is more verbose and boilerplate. It will, however, work on older versions of Rollbase. Copy the code from Appendix A and paste it into the empty editor in the Trigger Properties section. Select Save to complete the trigger. Most of the Object Script is boilerplate for working with the XML. A sample response body is included in Appendix C for your interest. We use the Rollbase Server-Side API to manipulate the XML and to update the various field values. There are a couple of noteworthy parts.

13 Let s look at the script at around line 15 where we have the following code. This code retrieves the contents of the container XML node of the first Cargo return returned and using the rbv_api.setfieldvalue API, sets the value of the container field. You may notice that this is not how we created the field we used the capitalized Container version. The lower case name is what s known as the Integration Name, which must be unique. The Integration Name is used to reference fields via merge fields and the Web Services APIs. Be careful when changing the Integration Name as it may affect existing templates, formulas and integrations. Notice that the second argument to the setfieldvalue is using another string token this time, a system-provided token representing the current record s unique internal id. Testing the integration We have now put all of the necessary pieces in place for our CargoShipping Rollbase app to be able to call out to the Corticon Server and execute the AirCargo Decision Service. To validate that the integration works, we go back to the application. Select the CargoShipping application via the APPLICATIONS drop-down on the left-hand side. This will return us to the application start page (a list of All Cargos). If we select the Edit Action on the record we created earlier, we will now see values in the Container and Container Messages fields. These messages are the result of calling the AirCargo Decision Service. If we change the value of the Weight, Volume or Needs Refrigeration fields, and save, we can observe that the values of these Container and Container Messages fields changes according to the rules applied to the data. An example Cargo is shown below, along with the container that has been calculated by the Decision Service.

14 Conclusion This document set out to provide an overview of why and how a Rollbase application might use a formal business rules service such as Corticon for some of its business rules processing. Using the example above we have shown how quick and easy it is to add business rules to your application. The value of a rule system is realized when you have a large, complex set of rules which can be expressed in Corticon by those with expertise in the business case. Adding business rules to a Rollbase application will make it more flexible in response to changing business environments, government mandates, and other changes over time.

15 Appendix A: Trigger Object Script Using XPath var code = rbv_api.getsharedvalue("returnstatus"); var body = rbv_api.getsharedvalue("returnbody"); if (body!= null && body!= '') { /* assume that there's only a single Cargo record */ /* get the id for finding the associated messages */ var xpathexpr = '/Envelope/Body/CorticonResponse/WorkDocuments/Cargo[1]/@id'; var res = rbv_api.evalxpath(body, xpathexpr); var cargoid = res.item(0).getnodevalue(); /* get the value of the container field to update our data */ xpathexpr = '/Envelope/Body/CorticonResponse/WorkDocuments/Cargo[1]/container/text()'; res = rbv_api.evalxpath(body, xpathexpr); /* set the value from the response into the application data */ rbv_api.setfieldvalue("cargo", {!id}, "container",res.item(0).getnodevalue()); /* find all the messages for the specific Cargo record */ xpathexpr = '/Envelope/Body/CorticonResponse/Messages/Message/entityReference[@href=\'#'+ cargoid + '\']/..'; res = rbv_api.evalxpath(body, xpathexpr); /* we now have potentially multiple Message nodes */ for (var k=0; k<res.length; k++) { /* get the severity and text values */ var childnodes = res.item(k).getchildnodes(); var messagetxt = ''; for (var j=0; j<childnodes.length; j++) { var node = childnodes.item(j); if (node.getnodename() == 'ns1:severity') { messagetxt += '[' + node.gettextcontent() + '] '; } else if (node.getnodename() == 'ns1:text') { messagetxt += node.gettextcontent() + '\r\n'; } } rbv_api.setfieldvalue("cargo", {!id}, "container_messages", messagetxt); } }

16 Appendix B: Trigger Object Script Using DOM var code = rbv_api.getsharedvalue("returnstatus"); var body = rbv_api.getsharedvalue("returnbody"); if (body!= null && body!= '') { var root = rbv_api.parsexml(body); var nodes = root.getchildnodes(); // soapenv:body for (var k=0; k<nodes.length; k++) { var child = nodes.item(k); var nodes2 = child.getchildnodes(); // ns1:corticonresponse for (var m=0; m<nodes2.length; m++) { var child2 = nodes2.item(m) var nodes3 = child2.getchildnodes(); var hrefid = ''; } // ns1:workdocuments for (var n=0; n<nodes3.length; n++) { var child3 = nodes3.item(n); var tage = child3.getnodename(); if (tage == 'ns1:workdocuments') { var nodes4 = child3.getchildnodes(); for (var o=0; o<nodes4.length; o++) { var child4 = nodes4.item(o); var nodes5 = child4.getchildnodes(); var taga = child4.getnodename(); if (taga == 'ns1:cargo') { hrefid= child4.getattribute('id'); for (var p=0; p<nodes5.length; p++) { var element = nodes5.item(p); var tag = element.getnodename(); var value = element.gettextcontent(); if (tag == 'ns1:container') { rbv_api.setfieldvalue("cargo", {!id}, "container",value); }}}}} if (tage == 'ns1:messages') { var nodes4 = child3.getchildnodes(); for (var o=0; o<nodes4.length; o++) { var child4 = nodes4.item(o); var nodes5 = child4.getchildnodes(); var tagm = child4.getnodename(); if (tagm == 'ns1:message') { for (var p=0; p<nodes5.length; p++) { var element = nodes5.item(p); var tag = element.getnodename(); var msgid = ''; if (tag == 'ns1:text') { value = element.gettextcontent(); } else if (tag == 'ns1:entityreference') { msgid = element.getattribute('href'); if (msgid == '#' + hrefid) { rbv_api.setfieldvalue("cargo", {!id}, "container_messages",value); }}}}}} }}}

17 Appendix C: Decision Service Response Example <ns1:corticonresponse xmlns:ns1="urn:corticon" decisionservicename="aircargo"> <ns1:workdocuments xmlns:xsi=" <ns1:cargo id="cargo_id_ "> <ns1:container>oversize</ns1:container> <ns1:needsrefrigeration>false</ns1:needsrefrigeration> <ns1:volume>35</ns1:volume> <ns1:weight>14</ns1:weight> </ns1:cargo> </ns1:workdocuments> <ns1:messages version="0.16"> <ns1:message> <ns1:severity>info</ns1:severity> <ns1:text>cargo with volume > 30 cubic meters must be packaged in an oversize container.</ns1:text> <ns1:entityreference href="#cargo_id_ " /> </ns1:message> </ns1:messages> </ns1:corticonresponse>