Expression Rules Debugger

An Overview of the Expression Rules Debugger

The Expression Rules Debugger allows you to conveniently debug rules, as you write them directly from the Configure the expression rule page of the Axeda Platform Configuration application. Expression Rules analysis can be triggered based on asset-related messages or system-related messages. For example, when an asset sends a message to the system, such as a data reading or alarm message, the platform runs any rules defined for that message.

The Expression Rules Debugger allows you to simulate messages for specific assets, in order to run the associated rules. This allows you to test the rule configuration and impact of your rules before using them in production.

The test results will show you any possible runtime issues with your rules (such as non-boolean If expressions, incorrect data type conversions, or recursive rules), as well as the actual runtime resolved expression variable values for the variables that were used in the expression.

The expression rules debugger allows you to create and execute rule tests, and to view the results of those tests. These tools are provided by the Test and View tabs of the "Configure the expression rule" page:

  • The Test tab allows you to test your expression rules by simulating messages for specific assets. The simulated messages are sent to the Axeda Platform as if they came from the actual asset. When the Platform receives a message, it runs the rules that are associated with the asset.
  • The View tab allows you to view test results from your message simulation. Results include the date and time the message was sent, the rule name, and the result. Test results for up to 50 rule evaluations occuring over the last 24 hours are available per asset. The results can be grouped by Test type, or by Asset name. If a rule resulted in an error, you will see the error icon next to the Rule Name in the Test Results table. Move your mouse over the error icon or click on the name of that rule to view an explanation of the error(s).

    You can also search for the results of previous tests from any assets, including any associated assets.

    Tip: If the Test results don't load immediately, click the Refresh button above the Test Results table. li>

Create and Test a New Rule

  1. Select the Create tab to view the Expression Tree. You can use it to reference the available objects for your expression rule, while defining the If conditions and the Then/Else expressions in step 2.

  2. Create the rule. When you create the rule, you select the Type of message that will trigger the rule, and define the If conditions and the Then/Else expressions. For example, if you create the following rule, enter the following information:

    3. Name: TestRule
    Type: Data
    Description:
    Enabled: Leave checked
    Execute action each time rule evaluates to true: Leave checked

    If: true
    Then: SetDataItem("value1", 250)

  3. Apply the rule to an asset. Click Apply to asset and specify the models and individual assets (for example, asset1) for which this expression rule will run. During runtime, only messages of those models or assets may trigger the rule.

  4. Before saving your rule, you should validate the rule to verify that the structure, syntax, and defined parameter values are correct.

    To validate your expression without saving it to the server, click Validate. This action will validate the syntax and format of your expression; it will NOT validate the objects that you define in your variables. If the syntax is valid, the expression fields are shaded in green. If the system detects invalid syntax, the field containing the invalid syntax is shaded in red. Move the cursor over the red field to display a message from the parser about the invalid syntax.

  5. When you are ready to save your expression rule, click Save.
  6. NOTE: If you have not made any changes since the last time you saved your expression rule, you will see an OK button instead of a Cancel button. You can click OK to return to the View and manage the expression rules page.

 

Now you can test the rule.

To Test Your Rule
Open the Test tab and click New Test. In the displayed Create Test page, do the following:

  1. Select the type of message to simulate (Data, Alarm, or Location). This will determine what condition in the system causes this rule to execute. For this example, select Data.
  2. Now specify the information needed to simulate a Data test message.
  3. Type a name for the test and select the asset for the simulated message. (For Alarm and Data tests: Only data items for that asset will be listed for selection as part of the test criteria. You must pre-create data items as part of your model configuration.) For this example, enter the following information, then click Add.

    NOTE: You can add additional data items to the Data items table by clicking , and remove them from the table by clicking .

    Test name: Test
    Search for asset: asset1
    Data items: Value1 Value: 150

  4. Once you create a test, it appears in the test table.
  5. All of the Test messages that you create appear in the Test table of the Test tab in their appropriate section (Data, Alarm, or Location). Click on a test type (Data, Alarm, or Location) to expand its section and view the list of test messages. For this example, select Data, and then view TempC 28.

  6. Click on the Execute Test icon next to the test(s) you want to send (this is the message that the Axeda Platform will evaluate). The icon will change to an open envelope when the test has run. To send the same message more than once, click on the open envelope to reset the message, and then click once more to send the test.
  7. To edit a Test message, click on the name of the Test message.
  8. To delete a single test message, click , or delete all test messages by clicking the Clear Tests button.

    NOTE: In the Beta version, tests are NOT saved when you leave the "Configure the expression rule" page.

    NOTE: The information required to simulate a test message varies based on the type of message you choose to simulate (Data, Alarm, or Location). For example:

    o If this is a data test: Specify the data item(s) and value(s) to create in the simulated data message.

    o If this is an alarm test: Type an alarm name (note that this should be a valid alarm for the selected asset). Type a severity, and select the data item(s) and value(s) to create in the simulated alarm message.

    o If this is a location test: type the location to create in the simulated location message. Use the format: latitude,longitude,altitude (optional); for example, 42.994532,-71.2938472. (The Axeda Platform Web services and SDK express latitude and longitude using the World Geodetic System (WSG 84) coordinate system. This coordinate system is the one used by the Global Positioning System (GPS). For more information, refer to http://earth-info.nga.mil/GandG/publications/tr8350.2/tr8350_2.html.)

Evaluating the Test Results
After running a test, you'll want to view the results and determine if you need to modify the rule configuration before using it in production.

The Expression Rules Debugger captures the following errors:

  • Recursion Errors - The condition in a rule is created either by an action in the same rule or by an action in another rule in a sequence, thus causing that rule to run over and over again, potentially in an infinite loop.
  • Non-Boolean If expressions - The If expression does not evaluate to true or false (1 or 0).
  • Non-existent Custom Object referenced in an ExecuteCustomObject action
  • Data type conversion errors
  • Any runtime exceptions thrown from functions or actions

View your test results by clicking the View tab. If you choose to automatically view test results when you Test the expression rule, you are automatically shown the View tab when you send a test, and results from the asset you just tested are displayed in the Test Results table.

Tip: If the Test results don't load immediately, click the Refresh button above the Test Results table.

  1. Search for Asset1 by typing in the Find rule results for asset field and clicking Search. The search will pull up all assets with names that begin with the string that you have typed in the search field.
  2. From the drop-down list above the Test Results table, select Group by Test type (to group the test results by Data, Alarm, or Location) or Group by Asset name.

    NOTE: If there are asset associations for the asset you created the test for (in this case, Asset1), then a drop-down list appears below the Find rule results for asset field that lists all associated assets. Select an associated asset to view the rule results for that asset instead.

  3. The test results for asset1 will appear in the table below, grouped according to your selection in step 2. Click on a Test type (Data, Alarm, or Location), or an Asset name to expand its section and view the list of results.
  4. Failed test results are marked with an error icon . Mouse over the error icon to view the explanation for the failure or click on the rule to view the expression in the Expression Rule Form. The expressions (If, Then, or Else) will be marked with the following icons (If there is no icon in front of an expression, then it was not executed at all):

    This expression of the expression rule was executed at runtime, but an error was thrown.

    This expression of the expression rule was executed, and no errors were detected.

  5. Use the expression rule form to edit the expression rule and fix any of the errors identified through testing.
  6. Click Clear to empty the list of test results and start a new search, or a new test.
Keywords: