Configure the expression rule

The Configure the expression rule page allows you to add a new expression rule to the Platform and to edit an existing expression rule. This topic explains the two main areas of this page and then provides a general procedure for creating a new expression rule. Once you are familiar with the page and how to create an expression rule, you can find details concerning the syntax for expression rules in the following topics:

o General information about the syntax - Syntax rules for Expression Rules

o Best practices - Best Practices for Expression Rules and Custom Objects

o Variables - Namespaces in Expression Rules

o Functions - Functions reference for expression rules

o Operators - Supported Operators for Expression Rules

o Actions - Actions Reference for Expression Rules

o Links to topics about expression rules, custom objects, and extended UI modules - Developing Groovy Scripts for the Axeda Platform

Then, you can find details on testing your expression rule in the following topics:

o Test Expression Rule

o View Test Results

The Tools Pane

On the left side of the page, there is tab group called the Tools Pane that helps you create and debug your expression rules. The Tools Pane has three tabs: Create (Select Functions, Actions, and Variables), Test (Test Expression Rule), and View (View Test Results). When you display this page for a new expression rule, The Create tab is always displayed "on top".

o Create Tab - Create your expression rules by building If, Then, and Else expressions with the objects in the Expression Tree. The Expression Tree lists the available objects for an expression rule in three categories: Variables, Functions, and Actions.. A message or trigger serves as the Type for an expression rule. Each Type has a set of related Variables (including namespaces), Functions, and Actions that you can use to create expressions. When creating an expression rule, you select the Type of trigger first and then select the objects for the If, Then, and Else expressions of the rule. Refer to the procedure, To create or edit an expression rule, to learn how to use the Expression Tree.

Note: Then and Else expressions are not required for validation. A rule will validate with only a defined If expression.

o Test Tab - 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.

o View Tab - 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 occurring over the last 24 hours are available per asset. The results can be grouped by Test type, or by Asset name.

The Rule Builder

On the right side of the page are all the fields for creating the expression. The fields include the overall information for the rule, including Name, Type, Description, Enabled, and the option, "Execute action each timer rule evaluates to true", and then the actual expression fields, If, Then, and Else. Finally, this area provides the buttons for applying, validating, and saving the expression rule. The following procedure provides details about the fields.

To create or edit an expression rule

1. In the Name field, type the name of the expression rule. This is required information and can be edited. You can use up to 50 alphanumeric and special characters. The rule appears by this name in the pages of the Axeda Applications.

2. From the Type list, select the type of trigger message for this expression rule. This is required information and specifies what condition in the Platform causes this rule to execute. For complete details about the available triggers, refer to the topic, Triggers for Expression Rules.

3. Optional: Type a description of the rule. Any description you define will appear in the View and manage expression rules page and can be used to determine the functionality of your rule. You can use up to 2000 characters (no limitations on types of characters).

4. Click the Apply to asset button to apply an expression rule to specific models so that the rule runs only for those models and for all assets of those models. You can also include and exclude assets of a particular model, such that the rule runs for included assets but not for excluded assets. View the Apply expression rule to models and assets page topic for more help with this step.

5. By default, a new expression rule is enabled (the check box is selected). If you want to disable the rule, clear the check box next to Enabled.

6. If the actions for this expression rule are to be executed each time the rule evaluates, select the check box next to Execute action each time rule evaluates to true (selected by default). If you do not select this option, the actions for this rule (defined in the Then and Else expressions) will be executed upon the first evaluation to true or false. Then, the If expression must evaluate to the opposite Boolean value and back to the original one for any actions to execute.

For example, with this option selected: a rule that creates an alarm when a temperature is higher than 82 degrees (for example, If: temp > 82) would create an alarm every time the temperature is over the limit. If this option is not selected, one alarm will be created when temp first exceeds 82 (the first time the expression evaluates to true), then the temp must go below 82 (the temp > 82 expression must evaluate to false) and then rise above it (that is, the temp > 82 expression must evaluate to true) again before another alarm is created.

7. For ConfigurationValidation triggers only: Select what source will be used when evaluating the associated ConfigurationEvent messages, as follows:

§ Agent reported configuration validation rule - only ConfigurationEvent messages related to agents posting configurations (new or changed) cause this rule to evaluate

§ SDK/UI configuration validation rule - only ConfigurationEvent messages related to new or changed configurations provided via the SDK/API (or through any UI provided via Asset Configuration SDK/API) cause this rule to evaluate

§ Both - any ConfigurationEvent messages received by the server cause this rule to evaluate

Next you will create the If, Then, and Else expressions for the rule. Although you can specify the expressions in any order, this procedure explains how to create the If expression first.

Note: For all DefinedConfiguration rules and for ConfigurationValidation rules configured to run based on Asset Configuration API/SDK (or related UI) configuration changes, you can only specify If expressions. If this is a ConfigurationValidation rule configured to run based on Agent-provided configuration changes, then you can specify Then and Else expressions also. Additionally, for the latter case, you can also define a Validation message that will be returned to the user when the rule is false.

Also note that DefinedConfiguration and ConfigurationValidation rules are only available with an Axeda ConnectedConfiguration license. If the Axeda Platform is not licensed for ConnectedConfiguration, you will not have access to these rules.

1. If it is not displayed in the Tools Pane, click the Create tab to view the Expression Tree. You can take the following actions:

§ Click the $image\icon_filterexprules_right_arrow.gif$ icon next to Variables, Functions, or Actions to display the list of related objects that are available for the trigger Type selected.

§ To see details for an object, click the name of the object once. A definition and information about what the variable returns are displayed in the Details pane below the expressions.

§ To collapse a list of objects, click $image\icon_hide_expression_rules_details.gif$ .

For information on specifying alarms, data items, locations, and assets in the expression, refer to Namespaces in Expression Rules.

2. Position the cursor in the If expression field. In the Expression Tree (Create tab), double-click the names of the objects (Variables, Functions) you want to use. Then type any appropriate operators or parameters. (Actions are not valid in the If expression.) Make sure the If expression will evaluate to true or false. (For DefinedConfiguration and ConfigurationValidation rules, see above note.)

3. To create the Then and Else expressions, position the cursor in the field. In the Expression Tree, review the available objects (Variables, Functions, and Actions) to find the ones you need and then double-click the name of each object to insert it in the field. As needed, type any additional operators or parameters in the fields. For the Then expression, choose the Actions that the Platform will run when the condition evaluates to true. For the Else expression, choose the actions that the server will run when the condition evaluates to false. Use variables and functions to complete these expressions. Depending on the If expression, the Else expression may be optional. When you validate the rule, a message that indicates the Else expression is required appears if you do not provide one and the If expression requires it. (For DefinedConfiguration and ConfigurationValidation rules, see above note.)

Note: Then and Else expressions are not required for validation. A rule will validate with only a defined If expression.

4. At any point you can validate your expression rule and 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 Platform detects invalid syntax, the field containing the invalid syntax is outlined in red. Move the cursor over the red field to display a message from the parser about the invalid syntax. Once you have corrected the syntax, click Validate again. Once the syntax is valid, the fields should all be shaded in green.

5. For ConfigurationValidation rules that will be evaluated for SDK configurations: In the Validation message box, type the message you want displayed back to the user when the rule is false. Use variables supported by the current context to provide real data and object information. You can use any supported expression variables and any cfg*() functions to create the data for your message.

Example: Assume your If expression determines if the model and serial for the asset defined in the configuration path matches a specified model and serial number.

If expression: CfgStrValue("/DeviceSync/ManagedDevice/@deviceModel") == "c6000" && CfgStrValue("/DeviceSync/ManagedDevice/@serialNumber") == "1010-2"

The end user will want to know when the model and serial number are not as expected (that is, when the rule is false). To relay this information to the end user, you can configure a validation message similar to the following:

Validation message: contactableDevice '" + Device.serial + "|" + Device.model + "' had the wrong serial number in the configuration. Model=" + CfgStrValue("/DeviceSync/ManagedDevice/@deviceModel") + " and Serial=" + CfgStrValue("/DeviceSync/ManagedDevice/@serialNumber")"

When the expression evaluates to true, the Platform will replace variables and functions in the validation message with actual data for the asset in context and display a message similar to the following to the user: Device CG2000 | CG200-model had the wrong serial number in configuration. Model= CG200-model and Serial= CG2000 (for example).

6. When you are ready to save your expression rule, click:

§ Save and New - To save the expression rule and clear the form so that you can add another expression rule.

§ Save - To save the expression rule.

§ Cancel - To discard your entries and return to the View and manage expression rules page.

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 expression rules page.

Now you are ready to test your rule.