tutorial: using corticon business rules in a … · tutorial: using corticon business rules in a...

Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 1 © 2015 Progress Software Corporation. All rights reserved.

Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application

Product Version: OpenEdge 11.5 and Corticon 5.5


Table of Contents

Introduction .......................................................................................................................... 3

Overview of using a Corticon Decision Service in an OpenEdge application ............................................ 3

Introducing the sample application ........................................................................................ 5

Importing the sample application ............................................................................................................. 5

Setting up the development environment .............................................................................. 7

Exporting a dataset as a Business Rule Vocabulary Definition file ......................................... 12

Creating a .brvd file from an OpenEdge ProDataSet: ............................................................................. 12

Accessing and Using a Decision Service from an OpenEdge application ................................ 15

Connecting to the Decision Service ........................................................................................................ 15

Invoking the Decision Service ................................................................................................................. 19

Receiving and processing rule messages ................................................................................................ 20

Testing your application ...................................................................................................... 22

Running the application .......................................................................................................................... 23


Introduction

This tutorial teaches you how to access and use Corticon Business Rules in a Progress OpenEdge

Application. You will learn how to:

Set up an integrated development environment containing OpenEdge and Corticon,

Export a dataset to align data definitions in OpenEdge with the rules Vocabulary in Corticon,

Add code to your OpenEdge application to connect to and use a Corticon Decision Service using

the BusinessRules API, and,

Test the execution of Corticon rules from your OpenEdge application.

By defining business rules in Corticon instead of hard coding them in OpenEdge, you can easily modify

and maintain them without needing to change your application source code.

This tutorial is designed for hands-on use. We recommend that you follow along in Developer Studio for

OpenEdge, using the instructions and illustrations that are provided. We assume you have already

installed Developer Studio. You will also need a copy of Corticon. If you don’t have the Corticon Studio

installer executable, you can download a free trial version. Later in the tutorial, we will show you how to

add Corticon to your Developer Studio environment.

Overview of using a Corticon Decision Service in an OpenEdge application

https://www.progress.com/products/corticon


To use Corticon Business Rules in an OpenEdge application you need to do two things on the OpenEdge

side:

Align data definitions in OpenEdge with the rules Vocabulary in Corticon. A Corticon Vocabulary

is the set of terms used when defining Business Rules. To do this you can export a ProDataSet or

temp-table as a Business Rules Vocabulary Definition (.brvd) file. This file can then be imported

into Corticon to generate a Vocabulary.

Add code to your OpenEdge application to connect to and use a Corticon Decision Service using

the BusinessRules API. A Decision Service is a set of deployed Corticon business rules.


Introducing the sample application

The sample application you will use in this tutorial is a simple customer credit rating system. The sample

application contains 2 projects: OpenEdgeProject and CorticonProject. It uses the sports2000 database.

OpenEdgeProject contains a procedure file, InvokeFinanceReview.p, which you will modify to invoke a

Corticon Decision Service. The project also contains a ProDataSet, dsCust. The CorticonProject contains a

Decision Service called FinanceReview. The OpenEdge application takes a customer ID as input. It then

fetches the customer record from sports2000 and sends it to FinanceReview. The FinanceReview

Decision Service uses rules to evaluate the credit rating of the customer and returns the result to the

OpenEdge application. Depending on the credit rating, the Decision Service returns one of three

messages with a severity level and the current order terms value:

Importing the sample application

Follow these steps to import the sample application into your Developer Studio environment:

1. Download OEBusinessRules.exe which is a self-extracting executable to a location on your PC.

2. Extract the course files. Verify that the following directory is created:

C:\progress_education\OpenEdge\OEBusinessRules. This directory should contain the following

subdirectories and files:

o \sample (contains the files that you must use to start the sample application)

o FinanceReview.brvd (The Decision Service business rule vocabulary definition file for

reference)

3. Open Developer Studio.

http://wbt.progress.com/progress/nd/fresco/content/public/tutorials/corticon/pdfs/OEBusinessRules.exe


4. Create a new project in your Developer Studio workspace with the name OpenEdgeProject.

5. Create another new project in your Developer Studio workspace with the name CorticonProject.

6. Import the files in C:\progress_education\OpenEdge\OEBusinessRules\sample\OEProject to

OpenEdgeProject in Developer Studio.(Note: Overwrite the existing files if prompted)

7. Import the files in C:\progress_education\OpenEdge\OEBusinessRules\sample\CorticonProject

to CorticonProject in Developer Studio.(Note: Overwrite the existing files if prompted)


Setting up the development environment

Before you get started, you need to set up an integrated development environment for OpenEdge and

Corticon. You begin by adding Corticon to your Developer Studio environment.

1. Double-click PROGRESS_CORTICON_5.5_STUDIO_WIN_64.exe in the installation directory.

The Progress Corticon Studio setup wizard appears.

2. Follow the wizard and select “Yes” when asked, “Do you want to configure Progress Corticon

Studio with Progress Developer Studio for OpenEdge”?


3. Keep the defaults in the remaining steps to complete the installation. Corticon is added to the

Developer Studio environment.

4. To start the OpenEdge web server, open the Proenv command prompt and enter protc start.


5. Next, modify PROPATH of OpenEdgeProject to access the OpenEdge BusinessRules API. Select

Progress OpenEdge>PROPATH.


6. On the Properties page, select Add External Library and then select the

OpenEdge.BusinessRules.pl file located at C:\Progress\OpenEdge\tty\rules and click OK.

7. For this sample application, you need to connect to the sports2000 database which is shipped

with the product. Ensure you create a database connection with the database for

OpenEdgeProject.


You have now set up the integrated development environment.


Exporting a dataset as a Business Rule Vocabulary

Definition file

In order for an OpenEdge application to use a Corticon Decision Service, the Corticon Vocabulary must

be aligned with data definitions in the OpenEdge application. One way you can do that is to use an

existing data definition (ProDataSet or temp-table) to create a Vocabulary in Corticon.

In our sample application, the ProDataSet, dsCust, contains information about the customer and

customer order. To align the rules vocabulary with the data definitions in our ProDataSet, you can

export the ProDataSet data definitions in a .brvd file. This file can then be imported into Corticon and

used to generate the Vocabulary.

Creating a .brvd file from an OpenEdge ProDataSet:

1. Open Developer Studio. From the menu bar, select File>Export>Progress OpenEdge>Business

Rules Vocabulary Definition.

The Export Business Rules Vocabulary Definition wizard appears.

By default, the wizard displays the Workspace Resources tab that lists files in the workspace.


2. In the left tab, select dsCustOrder.i. The ProDataSet and its temp-tables in dsCustOrder.i appear

on the right. Select all of them.

3. Next specify a file location and file name for your .brvd file. In the Definition file field, click

Browse to specify C:\progress_education\OpenEdge\OEBusinessRules and name it

FinanceReview.brvd and then click Finish.


You have now exported the data definition file as a .brvd file.

The .brvd file can now be imported into Corticon and used to create the rules Vocabulary which can

then be used to create a Decision Service. For this tutorial we will provide you with a Decision Service

called FinanceReview.


Accessing and Using a Decision Service from an

OpenEdge application

To access and use a Corticon Decision Service in an OpenEdge application you must add code that does

the following:

Establishes a connection to the Decision Service. You must do this once for each web session.

Invokes the Decision Service, passes data to it, and then receives the updated data.

Receives messages from the Decision Service.

Processes the messages and updates the database, as required

There is an API available in OpenEdge with classes and methods for using a Corticon Decision Service.

Developer Studio provides macros that make it easy to add code that uses the API to your application.

Connecting to the Decision Service

To add code that connects to a Corticon Decision Service, you use the BR-CONNECT macro.

1. Open the procedure file, InvokeFinanceReview.p, under OpenEdgeProject.


2. Type BR-CONNECT in the Main block after the Define statements and then press the Space bar.

3. Move the Using statements to the beginning of the Definitions section and keep the remaining

macro code in the Main block. (Ignore any compilation errors at this point.)

The file should look like this when you are done:


4. Modify the macro code to provide the URL for the Decision Service, the Version number of the

Decision Service and the name of the Decision Service as follows:

o Decision Service variable name : decisionservice

o URL: http://localhost:8980

o Version number: 1.0

o Service name: FinanceReview


5. Add a Connect() method statement after the Decision Service definition statement as follows:

oConnection:Connect().

6. Delete the catch block inserted by the BR-CONNECT macro.


You will use the catch block inserted by the BR-INVOKE macro.

Invoking the Decision Service

To add code that invokes the Corticon Decision Service, you use the BR-INVOKE macro.

1. Navigate to PROCEDURE invokeDS: and type BR-INVOKE and then press the Space bar. Since you

inserted the BR-INVOKE macro in the same file that you inserted the BR-CONNECT macro code,

you already have the required Using statements present in the file. So, delete the Using

statement inserted by the BR-INVOKE macro.

2. In OpenEdge you can pass data using a Single input-output parameter, or using Separate input

and output parameters. The macro inserts code for passing a ProDataSet as a Single input-

output parameter. In the sample application you will use this method. Modify the inserted code

as follows:

a. In this sample application you will pass the dsCust ProDataSet to the InvokeService()

method, so you do not have to pass the dataset handle. Delete the happ Data

variable definition. Also, delete the placeholder statement for passing the

datasethandle.

b. Replace the decisionserviceref placeholder with the Decision Service variable name

you used earlier: decisionservice.

c. You need to pass the dataset, dsCust, to the InvokeService() method. So replace the

dataset-handle placeholder in the InvokeService() method parameter with DATASET

and provide dsCust as the name of the dataset.

d. Move the catch block to after the code line:


e. RUN displayMessages.

This is what your procedure code should look like when you are done:

Receiving and processing rule messages

The Invokeservice method you just used sends data to the Decision Service and receives data back. In

addition, a Decision Service may create rule messages while processing a rule. To receive rule messages

created by the Decision Service you use the BR-GETMSG macro.

In the sample application you will use BR-GETMSG to receive a rule message from the FinanceReview

Decision Service and then you will add code to display the message.

1. Navigate to PROCEDURE displayMessages:, type BR-GETMSG, and press Space.

2. Move the following code to the Preprocessor Definitions section:

{OpenEdge/BusinessRules/ttRulesMessage.i}

3. Because you do not need to use the dataset here, instead of replacing datasethandle

with an actual value, simply delete the dataset handle definition for hbuffer.

4. Replace decisionserviceref with the actual Decision Service name: decisionservice.

5. The macro inserts starter code you can use to update the database. You need to decide

how you want to process the messages and update data in your application. In our

sample application, we simply want to display the message so:


a. Delete the following starter code within the FOR-EACH loop:

hBuffer = datasethandle:get-buffer-handle(RulesMessage.TableName).

IF NOT VALID-HANDLE(hBuffer) THEN

NEXT.

hBuffer:find-by-rowid(TO-ROWID(RulesMessage.DataKeyValue)) NO-ERROR.

b. Insert the following code within the FOR-EACH loop:

MESSAGE "Severity:" RulesMessage.Severity SKIP

"Message:" RulesMessage.MessageText SKIP

VIEW-AS ALERT-BOX.

This is what the displayMessages procedure should look like when you are done:


Testing your application

The last step to ensure that you can connect to and use the Decision Service is to test your application.

Before you test your application, you must publish the FinanceReview Decision Service to Corticon

server and ensure that the database connection of your application is present.

Follow these steps to publish the FinanceReview Decision Service.

o Switch to Corticon Designer mode in your Developer Studio

o Ensure that the Corticon server is started. To start the server, open the Proenv

command prompt and enter protc start.

o From the CorticonProject folder, select FinanceReview.erf and select Project>Publish in

the menu-bar to publish it to the Corticon server.

o In the Server Connect page, provide the following details and follow the wizard to

complete publishing.

URL: http://localhost:8980/axis

username: admin

password: admin

To ensure that the database connection of your application is present right click the

OpenEdgeProject folder>Properties>Progress OpenEdge> Database Connections.


Running the application

1. Right-click InvokeFinanceReview and then select Run as > Progress OpenEdge Application.

2. Enter Customer number 22.

You should see that the Rating is “good”. The order terms value is maintained at Net30.


3. Run the procedure again. Enter Customer number 4.

Note that the credit rating is “fair” and that the order terms value has decreased from Net30 to

Net15.

Congratulations! You have now successfully completed the Using Corticon Business Rules in a Progress

OpenEdge Application tutorial.

tutorial: using corticon business rules in a … · tutorial: using corticon business rules in a...

Documents