State Namespace

The State namespace enables expression rules to evaluate symbols of the state machine related to the trigger message. Using the supported symbols, an expression rule can determine if a state machine is entering or exiting a defined state; the state to which the state machine is transitioning, the state that the state machine is leaving, and the state that the state machine is in when the related message caused the rule to run.

State transitions

The order of states in a state machine is very important. The Platform always treats the first state in the list as the "initial" state for the state machine and defaults to this state. You cannot set this initial state using the setState action, even after the state machine has moved to another state. When an asset associated with a state machine registers for the very first time, you cannot programmatically determine its current state. However, for a newly registered asset, it is safe to assume that the state machine is in its first or "initial" state.

Once the state machine moves from the initial state to another state, the Platform creates a data item with the same name as the state machine. The data item has a string value of the current state of the state machine; the data item is visible in the Asset dashboard. You should be able to use this data item (to test its value), but you cannot manually set the value of this data item.

When a state of a state machine changes, the Platform generates a StateChange message. Using the isentry symbol, you can configure rules that run actions depending on whether the state machine is entering (true) or leaving (false) a state:

If StateChange.isentry tests if the state machine is entering the state (true)

If !StateChange.isentry tests if the state machine is leaving the state (using the NOT operator(!))

Note that the leaving a state message is a separate message from the entering another state message. You need separate rules to respond to each of these messages.

If the symbol provides a string that will be used in comparisons, that value will be case-sensitive. For example, make sure the State current value is written in the correct case for comparison (If State.current == "Loading Dock" Then ).

Use this namespace with asset-related triggers and NOT with system-related triggers. See Using Appropriate Actions and Namespaces with Triggers for Expression Rules.

Symbols:

o        current - current state of the state machine when the trigger is evaluated

o        from - previous state of the state machine when the trigger is evaluated

o        to - state to which the state machine is transitioning when the trigger is evaluated

o        isentry - Boolean indicating whether this message is an "enter" or "exit" state StateChange message

You can use the GetState function to retrieve the current state of a named state machine. Use the SetState action to set the value of a state.

The following table lists and describes the symbols for a State:

* The isentry symbol returns a Boolean. Do NOT use an operator and value. To test for a value of true, use the namespace and symbol (State.isentry). To test for a value of false, use the NOT (!) operator with the namespace and symbol (!State.isentry). See also Creating IF comparisons with Boolean and non-Boolean values.

Example

The following example shows how you can use the State namespace and its symbols in an expression rule:

 Trigger=StateChange

 If (State.from =="Loading Dock" && !State.isentry && Trigger.time < Now()-60)

In this example, the Platform receives a StateChange message, and determines if the state machine is leaving the "Loading Dock" state and if the trigger occurred more than a minute before the current Platform time. If all conditions are true, the Platform executes whatever action is set in the Then expression. If any one condition is false, the Platform executes whatever action is set in the Else expression (if an Else is configured).