Using Cloud Services in Rules

Axeda Custom Objects can be called from within rules to extend the power of the Axeda Rules Engine. Custom Objects are scripts, written using the Groovy scripting language. Custom Objects have complete access to the Axeda SDK, as well as really easy to use Groovy libraries for accessing remote services.

This tutorial will show you how to link a script to an ExpressionRule so that information retrieved from the cloud can be used to enrich information about an event.

Imagine that you are the developer of a vehicle monitoring application, built using the Axeda platform. Vehicles may report Alarm conditions with an On-Board-Diagnostics (OBD) code, but these codes alone may not be helpful to a human (unless you are familiar with P0010 faults and the like).  We'd like to receive the alarm information from the vehicle's telematics module, then retrieve a human-understandable description from an automotive knowledgebase. The runtime-workflow will be as follows:

1. An AWP-enabled vehicle telematics module detects an OBD fault and sends an alarm message to the Axeda Platform. The alarm message will include the OBD fault code that was retrieved from the vehicle. We'll use the Axeda Simulator to do this.
2. An ExpressionRule called EnrichOBDAlarm will process this alarm message, recognize it as an OBD fault, and call a CustomObject to retrieve the OBD description for the reported code.
3. The CustomObject called GetOBDDescription will make the call to the Web-based REST API to translate a code into a description string.
4. The result of GetOBDDescription will be placed into the alarm record

Side Note: We really liked this example scenario, but were very disappointed to find that there was no such OBD API/database in existence. Being the tenacious folks that we are, we scoured automotive forums and put together an OBD database of our own, and wrapped it with a simple REST API. You can browse the list of OBD codes at http://chicagodemo.axeda.com:8080/sample-apis/obd

So let's get started!

Create the EnrichOBDAlarm rule

Launch the Platform (Register to enable access to the platform)

After clicking on the Platform Access Link above, a new window will appear.

• Navigate to the Configuration tab

• Select New-Expression Rule

Add the following values to the new rule form:

Name: EnrichOBDAlarm
Type: Alarm
Description: Lookup the OBD code in the external KB and attach to the alarm.
Enabled: Leave checked

If: Alarm.name == "OBD Fault"
Then: SetAlarmExtendedData( ExecuteCustomObject("GetOBDDescription", Alarm.value) )

Then click the Save button at the bottom of the form. Your newly created rule will appear in the rules listing. Now we must associate this rule to your account's Model. Click the icon in the Applies To column for the EnrichOBDAlarm rule.

The Applies To dialog will appear. Click the search button  to find your model, then drag it into the right side of the dialog. The result should look like the following, with the selected model name being your account model.

Then click the Save button at the bottom of the dialog.

Your Expression Rule is now complete — and it does a lot in two lines. Every time an "OBD Fault" occurs for any asset of your model, the Expression Rule runs and calls a Custom Object with access to the complete platform SDK within a modern programming language environment. Now you'll see how easy it is to write the GetOBDDescription Custom Object.

Create the GetOBDDescription Custom Object

Click on New -> Custom Object

import  groovyx.net.http.RESTClient
import  groovy.util.slurpersupport.GPathResult
import static  groovyx.net.http.ContentType.*
import  groovy.xml.StreamingMarkupBuilder
import  javax.xml.transform.stream.StreamResult
import  javax.xml.transform.stream.StreamSource
import  javax.xml.transform.TransformerFactory
import  javax.xml.transform.OutputKeys

restclient= new RESTClient(  'http://chicagodemo.axeda.com:8080' )
restclient.client.params.setBooleanParameter  'http.protocol.expect-continue', false

def code =  parameters.code


groovyx.net.http.HttpResponseDecorator  response = 
         restclient.get( path : "/sample-apis/obd/q/$code",  contentType: XML)

assert response.success
assert  response.status == 200
assert response.data instanceof GPathResult

def  description = ''
if (response.data.text()  == 'not found') {
   description = "* Unknown OBD II Code *"
}
else {
  description =  response.data.description
}

logger.info "ODB Service  Response: $description"
return description.toString()

Variable Name: code
Display Name: OBD II Code

Click Add, then Save Changes.

Click on the Compile button and make sure there are no errors (please note a popup window will be displayed with the compilation results, so make sure to enable the popup for this page)

Good, there were no errors or warnings, so close the Compilation results window and click the Next >> button

In this step, we are going to test the Script output:

In the Asset Serial Number field, start typing asset1 and select your asset|model entry from the popup list. 

In the OBD Code field, type P0010

Click Test. Your script will actually run, and the log entries in the script will display in the result page, as follows:

Click the Close button and the Finish button and then Finish again to commit the Script

Simulate an OBD Alarm

 Launch the Axeda Simulator 

• The Axeda Simulator will launch in a new browser window
• Enter your registered email address, Developer Connection password, and click Login.

Select asset1 from the Asset dropdown.

Select the Alarm tab, and enter the following in the form:

Name: OBD Fault
Severity: 500
Data item Name: OBDCode
Type: String
Data Item Value: P0010

Then Click Send.

View the Alarm in the Axeda UI

Visit the Service tab in the platform UI and and click the link for asset1. note the newly created OBD Fault alarm. Click the link for the alarm and you'll see the Alarm Details popup. In the Extended Data field, you should see the description that was retrieved from the OBD API.

If you'd like to try out other OBD codes, you can clear this alarm from asset1 by clicking the "Close" link when viewing the alarm, then post another alarm with the same options, except choosing a new OBD code from this list:

http://chicagodemo.axeda.com:8080/sample-apis/obd/list

Congratulations! you have learned how to link rules processing to scripts, opening a world of possibilities for intelligent augmentation of platform data and integration possibilities with other cloud services.

Be sure to check out other tutorials and articles on Custom Object scripting and Expression Rules.