Operational Decision Manager Worklight Integration

Copyright IBM Corporation 2013 All rights reserved IBM Operational Decision Manager V8.5 Lab exercise Operational Decision Manager Worklight Integration Integrate dynamic business rules into a Worklight mobile application What this exercise is about... 1 Lab requirements... 1 What you should be able to do... 2 Introduction... 2 Part 1: Deploy the rule project... 5 Part 2: Deploy the mobile application... 12 Part 3: Run the Assistance Application in the Worklight console... 18 Part 4: Change rules (Optional)... 31 What you did in this exercise... 38 What this exercise is about This lab explains how you can integrate decision services managed in IBM Operational Decision Manager (ODM) into a Worklight mobile application. This lab is provided AS-IS, with no formal IBM support. Lab requirements List of system and software required to complete the lab. IBM Operational Decision Manager V8.5 with sample server profile IBM Worklight Studio V5.0.5 Google Chrome Throughout the lab, references to these products drop the brand prefix and the version, calling them Operational Decision Manager or in short ODM, Worklight, and Chrome. IBM Operational Decision Manager Worklight Integration Lab exercise Page 1 of 38

What you should be able to do At the end of this lab you should be able to know: How to structure a Worklight Mobile application and use Worklight adapters to connect the mobile application to the REST Operational Decision Manager decision service How ODM rules can be used to provide dynamic decisions in Worklight mobile solutions How an ODM rule project can be structured to take advantage of the mobile environment How to deploy and invoke decision services using REST protocols allowing easy invocation from mobile and client based applications Introduction Mobile Auto Insurance Assistance Scenario The scenario used in the lab is based on an auto insurance company that wants to provide assistance to their customers in the event of a breakdown or accident. This is provided as an Assistance Application running on the Android mobile device. The Mobile development and execution environment is provided by Worklight. In the lab you will use the Worklight Mobile Browser Simulator to explore the impact of this information on the Assistance Application as shown below. This allows the location of the mobile and the battery level to be configured through the simulator. IBM Operational Decision Manager Worklight Integration Lab exercise Page 2 of 38

The assistance provided in this application is determined by rules running on Operational Decision Manager. To determine the advice provided to the mobile user, the rules are based on this information: Customer information: Customer name, age, and code name for policy coverage (bronze, silver, or gold) Customer vehicle brand, model and year Customer home location specified in latitude and longitude Mobile device information: Geolocation allowing the rules to provide advice based on where the incident has occurred Battery level allowing the rules to send asynchronous alerts or text messages with advice rather than relying on permanent network connectivity Note: the device specific information is accessed through a Cordova API (previously called Phonegap) which allows a consistent approach to be applied across devices, for example: Android versus iphone versus browser. This lab contains four main parts to help you understand how an ODM Worklight integration solution can be realized as shown in the diagram below. Deploy the rule project. This part shows you the structure of the sample rule project called myinsurance-rules. You will learn the detail of the rules that provide assistance to a mobile user in the event of an accident using both the mobile user characteristics and information provided by the mobile device. With the sample command, you then deploy the rule project to the decision server. IBM Operational Decision Manager Worklight Integration Lab exercise Page 3 of 38

Deploy the mobile application. In this part, you first learn the structure of the sample Worklight project: myinsurance-wl. Then you deploy the adapter to the Worklight server and the application to the Worklight Browser Simulator. Run the Assistance Application in the Worklight environment. You run the application and observe how the rules determine the advice based on the different user characteristics and location of the mobile device. (Optional) Update the redeploy rules. You can experiment with changing and redeploying rules and observe the changed response of the Assistance Application. IBM Operational Decision Manager Worklight Integration Lab exercise Page 4 of 38

Part 1: Deploy the rule project 1. Start the Operational Decision Manager sample server. a. Select Start All Programs IBM Operational Decision Manager V8.5 Sample server Start server. b. Wait a few moments until the server starts. When it is ready, you should see this window with a successful message: Press any key to close the command window. 2. Launch the Sample Console and import the sample project. a. Select Start All Programs IBM Operational Decision Manager V8.5 Sample server Samples Console(en_US). Enter the workspace location. For example: C:\IBM\workspaces\WorklightSample. IBM Operational Decision Manager Worklight Integration Lab exercise Page 5 of 38

b. Once the Sample Console is opened, on Samples and Tutorials page, navigate to Rule Execution Server > Samples > Worklight ODM adapter. c. Click Import Projects. In the Rule perspective, several projects which are used in the myinsurance-rules decision are imported. myinsurance-rules: a sample rule project containing the vocabulary, interfaces, and rules used to determine the Assistance reports. myinsurance-xom: a Java project containing the definition of the information exchanged with the application. While most of the classes are Java beans representing the user, vehicle and cover, there are also some utility functions that can be invoked by the rules. cordova-bom: contains an example of how the Cordova APIs can be exposed to the rules in a business friendly manner. cordova-xom: contains Java beans representing the objects available from the mobile device such as geolocation and battery status. myinsurance-ruleapp: provides the definition of the deployable ruleapp that contains the myinsurance-rules project. IBM Operational Decision Manager Worklight Integration Lab exercise Page 6 of 38

3. Understand Cordova projects The cordova-bom project provides the Business Object model and verbalization that allows the mobile device characteristics specified in the Cordova API to be referenced in the rules. You can find detailed information about those BOMs under cordova-bom > bom > cordova > cordova. The cordova-xom project defines the Java beans used to define the structure of this information used at runtime. To explore this vocabulary, expand the Rule Explorer view and double click the classes of interest to see how they are represented in the rules. 4. Understand myinsurance-rules rule project The myinsurance-xom project contains Java beans that represent the mobile user characteristics and include helper functions for calculating the distance to home. IBM Operational Decision Manager Worklight Integration Lab exercise Page 7 of 38

a. Double click myinsurance-xom > src > myinsurance > Customer.java to see the implementation of the getdistancetohome() method. The myinsurance-rules project is the main rule project used by the Assistance Application to make the assistance decisions. It has dependencies on the cordova-bom project for the mobile device characteristics allowing the vocabulary to be shared across the projects. The decision is invoked as a decision service with parameters that define the information required to make the decision and returns parameters containing the report information provided by the decision. These parameters are shown as JavaScript variables in the Assistance Application. b. Select the myinsurance-rules project, right click and select Properties. c. In the properties panel, select Ruleset Parameters. IBM Operational Decision Manager Worklight Integration Lab exercise Page 8 of 38

When the decision is invoked with the input parameters (Customer, Position, Battery), the rule engine applies the rules in a sequence. It is defined by the my insurance rule flow before returning the Report parameter. d. Double click myinsurance-rules > rules > my insurance to open the rule flow editor. IBM Operational Decision Manager Worklight Integration Lab exercise Page 9 of 38

The flow runs through these steps: Init report initializes the fields in the Report parameter with default values. Check position determines if positional information is available from the mobile device. If not, only the general rules about position task is applied which runs the rules in the package position.general. country and timezone init calculates the country and time zone based on the position.contextual.country decision table. position contextual applies these rules: position.contextual.country checking, position.contextual.night exception and position.contextual.position policy. general rules applies the decision table general conditions. battery applies the rules in the battery package. vehicle applies the rules in the vehicle package. You can double click any of the rules or decision tables in the Rule Explorer to see the appropriate rule. For example, to open position.contextual.position policy: e. Double click myinsurance-rules > rules > position > contextual > position policy as shown below. 5. Deploy the rule project The steps provided below use pre-configured sample ant scripts to deploy the rule project. You can also deploy the rule project directly from Rule perspective in Rule Designer. See Part 4 Deploy modified ruleset section for more details. IBM Operational Decision Manager Worklight Integration Lab exercise Page 10 of 38

a. Switch back to Samples Console perspective and choose Samples Commands tab. b. Navigate to Samples Commands > Rule Execution Server > Worklight ODM adapter. c. Double click run. At the end of Sample Server Console log, you should see the deployment successful message. You have deployed myinsurance-ruleapp to the Rule Execution Server. IBM Operational Decision Manager Worklight Integration Lab exercise Page 11 of 38

Part 2: Deploy the mobile application 1. Create a Worklight project named myinsurance-wl. a. Start the Worklight Studio and switch to the Design perspective. b. From the menu, choose File > New > Worklight Project. c. Type myinsurance-wl in the name field and select Hybrid Application as the project template. Click Next. d. Type MyInsuranceWL in the application name field, and select Add Dojo Toolkit. Click Finish. IBM Operational Decision Manager Worklight Integration Lab exercise Page 12 of 38

2. Copy the project implementation into workspace In the previous step, you have created myinsurance-wl Worklight project. The Operational Decision Manager Worklight sample provides the full implementation. You can copy the sample implementation into the workspace. a. Right click myinsurance-wl project, click Close Project. b. On your local system, navigate to <ODM>/executionserver/samples/worklight/myinsurance-wl-files. c. Copy all the content under myinsurance-wl-files folder and paste to your workspace myinsurance-wl folder. Overwrite the existing content. d. In the Eclipse, right click myinsurance-wl project, choose Open Project. Press F5 to refresh the project content. 3. Establish mobile environments a. From Project Explorer view, expand myinsurance-wl > apps > MyInsuranceWL folder and double click the application-descriptor.xml file. The application descriptor provides the ability to define the common structure for the application and the mobile environments to which it can be deployed. This lab uses the Android environment for the MyInsuranceWL hybrid application. Alternatively, you can add Android by creating a new Worklight Environment from Eclipse menu. b. In Overview section, click Add button. c. Select Android phones and tablets environment, and click OK. IBM Operational Decision Manager Worklight Integration Lab exercise Page 13 of 38

d. Wait for the workspace to complete the building of the Android environment. In the Worklight Console, you get an error indicating that the Android ADT is missing. Failed importing native project for 'Android phones and tablets'. Missing ADT plugin or Android SDK. For more details see http://developer.android.com/sdk/eclipse-adt.html Application 'MyInsuranceWL' with environment 'android' build finished. This is expected as the Android development environment has not been installed. It is not needed for this lab which works in the Mobile Browser Simulator. But if you were developing on Android devices, it needs to be installed. You have generated an Android folder under apps. The Android folder contains custom Androidspecific materials that you can use to build an Android application. e. Expand MyInsuranceWL > Common and double click MyInsuranceWL.html to see the structure and customizations that have been added for the Assistance Application. IBM Operational Decision Manager Worklight Integration Lab exercise Page 14 of 38

Worklight allows all the application code to be written in a common fashion consisting of HTML files and JavaScript routines. In this lab, the top level application definition is provided by the HTML file: MyInsuranceWL.html. It is pre-generated when you re-create an application in Worklight and can be customized to produce the pages that are required in the device. The HTML file references several CSS and JavaScript files that can also be customized making it very quick to develop Apps. Two key JavaScript files are: initoptions.js: This defines how the Application starts up and makes any connections back to the Worklight server MyInsuranceWL.js: This defines the main JavaScript functions provided for the mobile Insurance Assistance Application. 4. Configure the ODM Worklight adapter a. From the Project Explorer view, expand myinsurance-wl > adapters > myinsurance_adapter_rest_xml folder. Open the myinsurance_adapter_rest_xml.xml file. b. Update the Connection Policy to reference the URL of the decision server to which you deployed the rule project. IBM Operational Decision Manager Worklight Integration Lab exercise Page 15 of 38

c. Open the myinsurance_adapter_rest_xml-impl.js file to see the implementation. IBM Operational Decision Manager Worklight Integration Lab exercise Page 16 of 38

The getreport function takes three JavaScript variables (customer, position, battery) and sends them to the correct ruleset running in Decision server. The path defines the endpoint for the REST decision service execution point that should be invoked. This is determined by the path to which you deployed the ruleset. The body defines the XML content that is sent to ODM. This is obtained by using the computerestpayload function to map from the JavaScript (JSON) representation passed into the function to an XML request document that can be sent to the decision service. 5. Deploy the Assistance Application a. From Project Explorer view, select myinsurance-wl > apps> MyInsuranceWL application. b. Right click and select Run As > Build All and Deploy. It should start the Worklight server, build the application, and deploy it to the development Worklight server running on port 8080 by default. The Worklight Console view shows the progress of the build and deploy. 6. Deploy the Worklight adapter a. From Project Explorer view, select myinsurance-wl > adapters > myinsurance_adapter_xml adapter. b. Right click and select Run As > Deploy Worklight Adapter. You should see Adapter deployed successful message in the Worklight Console view. You have now deployed your mobile application and adapter to the development Worklight server and device simulator. IBM Operational Decision Manager Worklight Integration Lab exercise Page 17 of 38

Part 3: Run the Assistance Application in the Worklight console 1. Open the Worklight console and launch Mobile Browser Simulator a. Launch Google Chrome with URL: http://localhost:8080/console. Under MyInsuranceWL application section, click the Android icon. It starts the Mobile Browser Simulator using an Android device. IBM Operational Decision Manager Worklight Integration Lab exercise Page 18 of 38

2. Configure the Assistance Application settings a. Click the Settings button and enter values of your choice or the defaults used in this lab. Name: John Home latitude: 52 Home Longitude: 0 b. Click Age. Use the scrolling widget to select 36. Then click Settings to go back to main settings widget. IBM Operational Decision Manager Worklight Integration Lab exercise Page 19 of 38

c. For the Policy, select bronze. You can experiment with different values later. d. To set the Vehicle, navigate through three screens to select Brand: BrandA Vehicle Model: compact Vehicle Year: 2012 IBM Operational Decision Manager Worklight Integration Lab exercise Page 20 of 38

e. Click Done button on the Vehicle Year widget to complete the settings. f. With all the settings established, click Done on Settings page to return to the main panel. Notice that the mobile user s name is shown in the welcome message. You are now ready to use the Assistance Application to evaluate the specific situations controlled by the rules. IBM Operational Decision Manager Worklight Integration Lab exercise Page 21 of 38

Scenario 1: Incident close to Home This situation occurs when the mobile user requests assistance when they are within 20 km of home. The main rule being applied here can be found in the Rule Designer workspace at: myinsurance-rules > rules > position > contextual > position policy. Note that the policy needs to be bronze for this rule to apply. Other policies (silver and gold) do not have this limitation. a. In Cordova Geolocation section, set your location to latitude 52, longitude 0.1, so you are close to your home. IBM Operational Decision Manager Worklight Integration Lab exercise Page 22 of 38

b. Click the Get Assistance button. On the first call to the ODM decision service, it can take a while to respond and you will see a message as shown below while the ruleset is being loaded into Decision Server. This only occurs on the very first usage of the ruleset within the decision server. Once loaded, you should see four vertical tabs displayed. c. Click the Location tab to see the report based on your geographic location. It shows the comparison being made in the rules between the home location and current location and thus generating a warning if the distance is less than 20 KMs. d. Click the Recovery, Policy cover, and Policy summary tabs. You should see the information as below. IBM Operational Decision Manager Worklight Integration Lab exercise Page 23 of 38

The messages displayed for the Recovery and Policy cover panels are generated by a decision table that defines the different cover messages for each type of the policy code. In Rule Designer workspace, you can find the decision table at myinsurance-rules > rules > general conditions. For bronze cover, towing on highways is not covered. If you select silver or gold in the settings, this message is different. IBM Operational Decision Manager Worklight Integration Lab exercise Page 24 of 38

Scenario 2: change the location This scenario shows how the geolocation information can be used within the rules. a. Set your position to be in France at 48, 2. b. Click the Get Assistance button. The information provided by the Cordova API specifies location in latitude and longitude. This is not easy for business users to manipulate, and so normally the rules invoke a geolocation service to convert from latitude, longitude into the country (or state). To minimize the dependencies on the external services, this lab uses a decision table to look up the country and its time zone based on the supplied latitude and longitude. You can find the decision table in Rule Designer workspace at: myinsurance-rules > rules > position > contextual > country. IBM Operational Decision Manager Worklight Integration Lab exercise Page 25 of 38

c. Expand the Location tab. You should see the result of the country checking rule displayed. Once the country and time zone have been determined for the home location and current location, the information can then be used to determine if the mobile user is in their home country or not. The country checking rule can be seen at: myinsurance-rules > rules > position > contextual > country checking. IBM Operational Decision Manager Worklight Integration Lab exercise Page 26 of 38

Scenario 3: Time based rules In this scenario, the rules are trying to determine whether it is night time at the user s current location. And thus provide them with appropriate telephone numbers to call. The night exception rule can be seen in the Rule Designer workspace at: myinsurance-rules > rules > position > contextual > night exception. It uses the absolute time provided by the device to calculate the local time in the current location. It adds the message to an alert report which is then used in the Assistance Application to raise an alert as a popup. a. Set your location to New Zealand at -42, 174, where the local time should be at night. b. Click the Get Assistance button. IBM Operational Decision Manager Worklight Integration Lab exercise Page 27 of 38

c. A notification is sent to inform you of who to call. Click OK to close the alert and the Assistance screen will then open. IBM Operational Decision Manager Worklight Integration Lab exercise Page 28 of 38

Scenario 4: Use of battery level in rules The rules in this scenario also make use of the battery level available from the device. When the battery is low (less than 10%), an additional message is added to the alert indicating that an SMS message is sent. The low battery rule can be seen in the Rule Designer workspace at: myinsurance-rules > rules > battery > low. Note this sample does not actually include the infrastructure to send the SMS message. a. Set the battery to 5% in the Cordova panel. b. Click Get Assistance. IBM Operational Decision Manager Worklight Integration Lab exercise Page 29 of 38

c. An alert pops up. It indicates that the rules have detected the low battery and have initiated an SMS message to be sent with further instructions allowing the mobile user to turn off their cellphone network connection and not miss any instructions. Click OK to close the alert and see the Assistance panel showing the battery level change. IBM Operational Decision Manager Worklight Integration Lab exercise Page 30 of 38

Part 4: Change rules (Optional) You might have noticed that the location report provided no information if you were close to your home location and were a silver or gold customer. In this part, you learn how to change a rule, redeploy the ruleset and observe the change in behavior of the Assistance Application. 1. Check the Assistance Application location report for a Silver policy type a. In the Cordova, reset the Battery settings to 90% and Geolocation to 52, 0.1 in London. b. On the mobile simulator screen, click Settings button. IBM Operational Decision Manager Worklight Integration Lab exercise Page 31 of 38

c. Select the Policy and change it to silver. And click Settings to save the value. Then click Done to save the settings change. d. Click Get Assistance button to run the rules and obtain a report as shown below. There is no information in the location panel. You will modify the position policy rule to provide a message for gold and silver policy codes. IBM Operational Decision Manager Worklight Integration Lab exercise Page 32 of 38

2. Change the rule a. Open the Sample Console by selecting Start All Programs IBM Operational Decision Manager V8.5 Sample server Samples Console(en_US). Enter the rule project workspace location. For example: C:\IBM\workspaces\WorklightSample. b. In the Rule Explorer view, double click myinsurance-rules > rules > position > contextual > position policy. c. Click at the end of the rule and press Ctrl + Space keys to bring up the Intellirule autocompletion editor and select else phrase. Double click to add else term. d. Copy the expression below and paste after the else term. add "INFORMATION: You are at " + the distance between 'the customer' home and 'current location + " kms from your home. Towing is covered in your policy" to the location report of 'the report' ; e. It should result in the rule content as shown below. Click the Save button on the toolbar. IBM Operational Decision Manager Worklight Integration Lab exercise Page 33 of 38

3. Deploy the modified ruleset a. Right click myinsurance-ruleapp, choose RuleApp > Deploy b. On the Deployment Wizard, select Replace RuleApp version to overwrite any existing deployments. Click Next. c. If a Java version notification pops up, click OK. IBM Operational Decision Manager Worklight Integration Lab exercise Page 34 of 38

d. Select Create a temporary Rule Execution Server configuration and use the default values provided. Click Finish. The Console view should show the successful deployment. 4. Rerun the Assistance Application location scenario IBM Operational Decision Manager Worklight Integration Lab exercise Page 35 of 38

a. Go back to the Mobile Browser Simulator you used before with silver policy code. Enter geolocation: 52, 0.1. b. Click Get Assistance. IBM Operational Decision Manager Worklight Integration Lab exercise Page 36 of 38

As you have just redeployed the rules, you will have a short wait before the updated response is provided. You can see your modified rule is executed. IBM Operational Decision Manager Worklight Integration Lab exercise Page 37 of 38

What you did in this exercise In this exercise, you First imported the sample myinsurance-rules rule project and examined the details of the rules that provide assistance to a mobile user in the event of an accident. Then you deployed it to the Decision Server of the Operational Decision Manager. Next, you started a Worklight project called myinsurance-wl using Worklight Studio. You created an Android environment and configured the Operational Decision Manager adapter. You deployed the Android application to the Worklight Browser Simulator and the adapter to the Worklight server. You ran four different end mobile user scenarios and observed how the rules determine the advice based on the different user characteristics and location of the mobile device. In the last part, you changed a specific rule, redeployed the ruleset, and reran the location scenario to observe the changed response of the Assistance Application. This completes the Operational Decision Manager Worklight Integration lab. But you are welcome to continue exploring with changing rules or Mobile device settings. IBM Operational Decision Manager Worklight Integration Lab exercise Page 38 of 38