When building expression rules, you can specify Platform objects (such as assets, alarms, data items, events, locations, states, files, registrations, and triggers) in the If, Then, and Else expressions by using Variables. Variables consist of namespaces, a delimiter (period or dot), and a symbol (or attribute). For the DataItem namespace only, Variables can also contain the name of a data item (a "local variable"). Consider the following example for the DataItem namespace:
If DataItem.temp.value > 8
In this example, the variable DataItem.temp.value is comprised of DataItem (the namespace), temp (name of the data item, a local variable), and value (the symbol). This expression tests whether the value of the data item, temp, is greater than 8. If this condition evaluates to true, the Then component of the expression rule will run. If this condition evaluates to false, the Else component of the expression rule will run (if it exists). Note that the name of the data item must be specified with the namespace and symbol.
Namespaces are primary objects that are used to enable the Platform to differentiate between local variables and symbols of domain (or business) objects. In expression rules, namespaces are fixed and always start with a capital letter. The namespaces fall into three categories: asset-related, system-related, and universal. Asset-related namespaces are specific to assets and managing their activity and information; system-related namespaces refer to messages or activity related to the Platform as whole; universal namespaces may apply to asset or Platform activity.
The following asset-related namespaces are currently available:
Alarm - the alarm message that causes the expression rule to be evaluated.
DataItem - a data item that the rule will process.
Device - the current asset; that is, the asset for which the expression rule is being processed.
Event - the event message that causes the expression rule to be evaluated.
File - the upload of a file (compressed or uncompressed) to the Platforms. The File trigger fires when the file upload completes.
Location - the current mobile location of the asset. The asset may not always be "moving", but this namespace always references a "mobile" location. Wireless devices and Axeda® IDM Agents can send in "mobile locations," which can cause an expression rule to be processed.
Registration - the act of an asset contacting the Axeda Platform either for the first time or after having been offline; applies to wireless devices that are tracking assets (for example, edge devices) and to intelligent, wired assets that are running Axeda® Gateway, Axeda® Connector, and Axeda IDM Agents.
State - the state machine for which the rule is being processed.
The following system-related namespace is available:
User - reference to the Platform user whose login or logout event triggered the expression rule. (The triggering events are UserLogin and UserLogout.)
The following universal namespace is available:
Trigger - reference to any trigger that occurs in the Platform.
By default, the Platform tries to resolve a variable using the namespace that matches the generated message. For example, suppose an Alarm message caused the expression rule to be processed. When evaluating the expression rule, the Platform first tries to resolve a variable (for example, "previousstate") that does not contain a namespace as an attribute of the Alarm namespace.
In general, using the namespace component of a variable is optional when the namespace matches the trigger message. For example, for an expression rule that is processed by an Alarm message, use of the Alarm namespace is optional. However, if the namespace does not match the trigger, you must use the namespace. For example, if the trigger is an Alarm message and you want to reference a DataItem, then you must use the DataItem namespace in the expression rule. Note that for a Trigger message, the Trigger namespace is required.
Best practices would be to always use the namespace. When the namespace is used with one of its symbols (for example, "Alarm.state"), the usage is said to be "Qualified." When a symbol is used without the namespace (for example, "state" rather than "Alarm.state"), the usage is said to be "Unqualified."
1. If the variable has a "Trigger" namespace, try to resolve the variable for that namespace first.
2. If the variable has a “ Device” namespace, try to resolve the variable in that namespace. Otherwise, the Device namespace is skipped.
3. Try
to resolve the variable as an attribute of a data item. For example, if
the variable is "DataItem.temp.value"
or "temp.value",
"DataItem"
is the namespace, "temp"
is the name of the data item and "value"
is the symbol. When resolving either of these variables, they resolve
as an attribute of a data item. The “
DataItem”
namespace prefix is optional, but if the variable has another namespace,
the resolution will fail in the Data Item attribute category.
Important!
When parsing an expression for
a data item name, the rules engine interprets a space as separating the
names of two variables. Therefore, it is very important that the names
of data items NOT contain any spaces.
In addition, the parser interprets the string that follows the last dot
(.) in the variable as the symbol of the namespace. If the name of a data
item contains dots, make sure that you use the symbol name. For example,
if you want to test the value of the data item called "temp.AMreading.1",
you must include the value symbol, as follows: DataItem.temp.AMreading.1.value
Although you could use the name of a data item without using the value
symbol, the rules engine cannot parse the expression if the name of the
data item is (or contains) the name of a symbol for the DataItem namespace.
For example, the symbol age might be
the name of a data item or the name might include .age,
as in temp.age.
To get the actual value of that data item, you must use at least age.value
(instead of just .age) or temp.age.value (instead
of just temp.age),
and it would be even better to include the namespace, DataItem.age.value
or DataItem.temp.age.value.
For this reason Axeda recommends that you always include the value symbol when
you want to retrieve the value of the data item for comparison.
4. Try to resolve the variable as an message-specific variable:
§ Alarm message is the trigger for the expression rule (Alarm namespace is optional). If the Alarm namespace is NOT used, then the Platform will
a. Try to resolve the variable as an Alarm attribute.
b. Try to resolve as a DataItem unless it has another namespace like Location.location. In that case, it is resolved as a location. If the variable is simply location, it is resolved as a DataItem first, then as a location.
§ Location message is the trigger for the expression rule (Location namespace optional). If the Location namespace is NOT used, then the Platform will
a. Try to resolve the variable as “ location” .
b. Try to resolve variable as a data item.
§ DataItem message is the trigger for the expression rule (DataItem namespace is optional. For example, the variable may contain either “ DataItem.temp or “ temp” ). The Platform will:
a. Try to resolve as a data item if the variable does not have the “ Location” namespace.
b. Try to resolve the variable as a location.
(The following messages are listed in no particular
order)
§ Registration message - if you want to resolve a Location, Data Item, Device, File, Alarm, or State symbol in a rule generated by a Registration message, then you must use those namespaces in the expression rule (Location, Data Item, Device, Alarm, File, or State).
§ File (upload) message - if you want to resolve a Location, Data Item, Device, Registration, Alarm, or State symbol in a rule generated by a File upload message, then you must use those namespaces in the expression rule (Location, Data Item, Device, Registration, Alarm, or State).
§ State message - if you want to resolve a Location, Data Item, Device, Registration, Alarm, or File symbol in a rule generated by a State message, then you must use those namespaces in the expression rule (Location, Data Item, Device, Registration, Alarm, or File).
Based on this variable resolution scheme, it may seem as though the logic for resolving a Device variable differs from that for the other variables in that the Device namespace is currently required. This requirement ensures that if you have a data item with the name “ model” or “ serial” , it will be resolved in the DataItem namespace.
For an expression rule generated by an Alarm message, the following example would resolve correctly because the Device namespace is included:
If(Device.model == "Model2000"
&&
Alarm.name == "AlarmName2000")
If the “ model” is actually an existing data item, the rule should use the DataItem namespace and the value symbol and be written as follows to resolve correctly:
If (DataItem.model.value
== "Model2000" && Alarm.name == "AlarmName2000")
Note that “ location” is always resolved as a data item first before it is tried as a real location. This resolution sequence allows you to have a “ location” data item. To reference the actual location, you must use the qualified name: Location.location.