Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application

Transcription

1 Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application Product Version: OpenEdge 11.5 and Corticon 5.5 Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 1

2 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 Creating a.brvd file from an OpenEdge ProDataSet: Accessing and Using a Decision Service from an OpenEdge application Connecting to the Decision Service Invoking the Decision Service Receiving and processing rule messages Testing your application Running the application Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 2

3 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 Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 3

4 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 4

5 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 o \sample (contains the files that you must use to start the sample application) FinanceReview.brvd (The Decision Service business rule vocabulary definition file for reference) 3. Open Developer Studio. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 5

6 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) Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 6

7 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? Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 7

8 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 8

9 5. Next, modify PROPATH of OpenEdgeProject to access the OpenEdge BusinessRules API. Select Progress OpenEdge>PROPATH. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 9

10 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 10

11 You have now set up the integrated development environment. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 11

12 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 12

13 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 13

14 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 14

15 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 15

16 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: Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 16

17 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: o Version number: 1.0 o Service name: FinanceReview Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 17

18 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 18

19 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 inputoutput 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: Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 19

20 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: Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 20

21 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: Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 21

22 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 o o o Switch to Corticon Designer mode in your Developer Studio Ensure that the Corticon server is started. To start the server, open the Proenv command prompt and enter protc start. From the CorticonProject folder, select FinanceReview.erf and select Project>Publish in the menu-bar to publish it to the Corticon server. In the Server Connect page, provide the following details and follow the wizard to complete publishing. URL: 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 22

23 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. Tutorial: Using Corticon Business Rules in a Progress OpenEdge Application 23

24 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 Progress OpenEdge Application 24