The purpose of this article is to describe how Expression Rules, Rule Timers, State Machine and Custom Objects interact. We'll focus on the interaction between these platform features, rather than describing them in detail. Details can be found in other articles:
In this article, we'll take an event-based view of the platform. (This is certainly not the only possible view: for example, it's important to understand the platform's data model.) There are three kinds of events on the platform:
- data arrives from an asset
- a timer fires
- a web service request arrives from a client application
In this article, we'll only consider the first two. An asset can send four kinds of data:
- one or more alarms
- one or more data items
- a location
- one or more files
We'll refer to these collectively as data.
We'll describe timers in more detail below.
When data arrives
Here's what happens when data arrives in the platform
- any model or asset associations are applied -- this has the effect of transforming the original data or generating more data
- Expression Rules are triggered
- the Expression Rule may trigger other Expression Rules
- the Expression Rule may execute a Custom Object
- the Custom Object may trigger more Expression Rules
When a timer fires, the associated Expression Rules are triggered. and the rest of the event flow is the same.
The rest of this article will consist of going through these steps in more detail, as well as providing references to further articles as well as the platform documentation.
Model and Asset Associations
The article on model and asset associations provides details of how they are defined and used.
A simple example will give you the flavor of how they apply here. A tracking device can be attached to a vehicle. When the tracking device reports its location, we want that to be treated by the platform as though the vehicle reported *its* location. An association allows you to logically link the tracking device to the vehicle so that that is exactly what happens.
Its relevance here is that the arrival of one datum (say, the location of the tracking device) will be treated by the platform as the arrival of another (say, the location of the vehicle). So when we say that data arrives from an asset, we're referring both to data sent directly from an asset, as well as data generated by the platform on behalf of an asset because of an association.
Triggering Expression Rules
To understand when Expression Rules run, you need to understand:
- the events which can trigger them
- which Expression Rules are run for a particular trigger
We'll discuss the first point in this section, and the second in the following section.
There are twelve types of triggering event:
- four types of alarm events
- two types of timers (asset and system)
- data
- file
- location
- registration
- state change (of a state machine)
- user login and logout
For example, a rule can be triggered when an alarm is created in the system. This happens when an alarm arrives from an asset, but also when an Expression Rule or Custom Object creates an alarm. In general, a rule can be triggered by:
- the arrival of data from an asset
- an action in another Expression Rule which (e.g.) sets a data item or creates an alarm
- code in a Custom Object which (e.g.) sets a data item or creates an alarm
The particular events which trigger Expression Rules are described in more detail in the documentation.
Which Expression Rules Run
With four exceptions, events which trigger Expression Rules are associated with a particular asset. The exceptions are:
- System and Asset Timer rules, and
- User Login and Logout rules
which we'll discuss in the next section.
It's straightforward which asset is meant. When an asset sends an alarm, data item or location information, that's the asset that is associated with the event. Similarly, when an Expression Rule or Custom Object creates an alarm or sets a data item, it does it for a particular asset.
When you define an Expression Rule, you define the models and assets that this Expression Rule will apply to. When an event occurs, such as receiving data from an asset, the Platform runs Expression Rules:
associated with the asset’s model, or explicitly associated with that asset,
where the type of event matches the triggering event for the rule.
The exceptions
When you define a system timer, you explicitly define the System Timer Expression Rules which will run when the timer fires. These Expression Rules are not associated with an asset.
User Login and Logout Expression Rules are run whenever a user logs in or logs out, respectively. These Expression Rules are not associated with an asset, but are associated with the particular user who is logging in or out. The documentation describes the user information which User Login and Logout Expression Rules can refer to.
When you define an asset timer, you define the Asset Timer Expression Rules which will run when the timer fires. When you define an Asset Timer Expression Rule, you define the models and assets to which the rule applies. When the timer fires, it runs each rule once for each asset to which the rule applies. Each time the rule is run, it therefore runs in the context of a particular asset, just like the alarm and data (etc.) rules described in the previous section.
State Machines
A state machine defines a list of states, and a list of Expression Rules which apply in each state. The Expression Rules are perfectly normal in structure and are triggered in the normal way, except that they are only triggered if the state machine is in the correct state.
When you define a state machine, you define the assets and models to which the state machine applies. (As before, a model is just shorthand for a list of assets.) Each of these assets potentially has a separate instance of the state machine, but these instances are not created when the state machine is defined, but rather the first time an Expression Rule triggers for a particular asset.
Each state machine has an initial state, which is the first state you define for the machine. Let's call this state S1. The Expression Rules you define for state S1 can be anything, but suppose we define an alarm rule. The first time an asset sends an alarm, the alarm rule will be triggered, and the state machine will automatically be created for that asset. The Expression Rule might leave the state machine in state S1, or it might change its state with a call to SetState.
Be careful to keep straight the distinction between:
- an ordinary Expression Rule triggered by a state change (which runs when an asset's state machine changes state), and
- Expression Rules defined as part of a state machine and attached to a particular state (which are triggered in the normal way, and only run when the state machine is IN a particular state).
State machines are described in MUCH more detail in the documentation.
Evaluation
When an Expression Rule is triggered, its IF clause is evaluated. This platform evaluates the IF clause in a context which is defined by the asset associated with the trigger. (This is equally true of Expression Rules defined as part of a state machine.) For example, the IF clause can refer to the asset's data items. This evaluation context is described further in the documentation.
Naturally, once the IF clause is evaluated, the platform evaluates either the THEN clause or the ELSE clause, although either can be empty. The execution context is the same for each part of the Expression Rule (i.e., IF, THEN or ELSE), and is inherited by any Custom Object which the Expression Rule executes.
The article on Expression Rules has more on variables and how to use them.
Side-effects of evaluating an Expression Rule
Evaluating an Expression Rule may trigger other Expression Rules by creating alarms, setting the value of data items and so on. Specifically, the actions:
- CreateAlarm
- SetAlarmExtendedData
- SetAlarmSeverity
- SetAlarmState
- SetDataItem
- SetState
will potentially trigger other Expression Rules.
Executing a Custom Object
An Expression Rule can call ExecuteCustomObject to (ahem) execute a Custom Object. The call can appear anywhere a value is expected, or as an action in the THEN or ELSE clause. The call may also make up the entire IF clause.
For example:
- IF ExecuteCustomObject("CheckSomething")
- IF ExecuteCustomObject("ReturnAValue") < 100
- THEN ExecuteCustomObject("PeformSomeAction")
- THEN SetDataItem("mydataitem", ExecuteCustomObject("ReturnAValue"))
- THEN CreateAlarm("myalarm", ExecuteCustomObject("ReturnAValue"))
As mentioned above, the execution context of the Custom Object is inherited from the Expression Rule which calls it. See the article on implicit objects for examples of Custom Objects called from Expression Rules which show how this context works in practice.
Custom Objects can trigger Expression Rules in the same way that one Expression Rule can trigger another, by creating an alarm or changing its state, setting the value of a data item or changing the state of a state machine and so on.
