AWS IoT Events
Developer Guide

Conditional Expression Syntax

The following syntax is used in conditional expressions. For more information, see the field detectorDefinition.states.onInput|onEnter|onExit.events.condition in the input to the CreateDetectorModel API.

Note

The result of the evaluation of a condition expression should be a Boolean value. If the result isn't a Boolean value, it's equivalent to false and won't trigger the actions or transition to the nextState specified as part of the event in which it occurs.

Literals

  • Integer

  • Decimal

  • String

  • Boolean

Operators

Unary
  • Not (Boolean): !

  • Not (bitwise): ~

  • Minus (arithmetic): -

Arithmetic
  • Addition: +

    For strings, + performs concatenation: 'my' + 'string' -> 'mystring'

  • Subtraction: -

  • Division: /

    The result of the division is a rounded integer value unless at least one of the divisor or dividend is a decimal value.

  • Multiplication: *

Bitwise (Integer)
  • OR: |

    For example: 13 | 5 -> 13

  • AND: &

    For example: 13 & 5 -> 5

  • XOR: ^

    For example: 13 ^ 5 -> 8

  • NOT: ~

    For example: ~13 -> -14

Boolean
  • Less Than: <

  • Less Than Or Equal To: <=

  • Equal To: ==

  • Not Equal To: !=

  • Greater Than Or Equal To: >=

  • Greater Than: >

  • AND: &&

  • OR: ||

    Note

    When a subexpression of || contains undefined data, that subexpression is treated as false.

Parentheses

You can use parentheses to group terms within an expression.

Built-In Functions

timeout("<timer-name>")

Evaluates to true if the specified timer has elapsed. Replace "<timer-name>" with the name of a timer you have defined, in quotation marks. In an event action, you can define a timer and set it running, or reset or clear one you have previously defined. See the field detectorModelDefinition.states.onInput|onEnter|onExit.events.actions.setTimer.timerName. A timer set in one state can be referenced in another. But you must ensure that the state in which it is set is always visited before the state in which it's referenced.

To ensure accuracy, the minimum time to which a timer should be set is 60 seconds.

Note

timeout() returns true only the first time it's checked following the actual timer expiration and returns false thereafter.

convert(<type>, <expression>)

Evaluates to the value of the expression converted to the specified type. The type can be one of String, Boolean, or Decimal. Use one of these keywords or an expression that evaluates to a string containing the keyword. Only the following conversions will succeed and return a valid value:

  • Boolean -> String

    Returns the string "true" or "false".

  • Decimal -> String

  • String -> Boolean

  • String -> Decimal

    The string specified must be valid representation of a decimal number, or convert() fails.

If convert() fails to return a valid value, the expression that it's a part of is also invalid. This result is equivalent to false and won't trigger the actions or transition to the nextState specified as part of the event in which the expression occurs.

isNull(<expression>)

Evaluates to true if the expression returns null. For example, if the input MyInput receives the message { "a": null }, then the following evaluates to true, but isUndefined($input.MyInput.a) evaluates to false.

isNull($input.MyInput.a)
isUndefined(<expression>)

Evaluates to true if the expression is undefined. For example, if the input MyInput receives the message { "a": null }, then the following evaluates to false, but isNull($input.MyInput.a) evaluates to true.

isUndefined($input.MyInput.a)
triggerType("<type>")

The <type> can be "Message" or "Timer". Evaluates to true if the event condition in which it appears is being evaluated because a timer has expired like the following.

triggerType("Timer")

Or an input message has been received.

triggerType("Message")
currentInput("<input>")

Evaluates to true if the event condition in which it appears is being evaluated because the specified input message has been received. For example, if the input Command receives the message { "value": "Abort" }, then the following evaluates to true.

currentInput("Command")

Use this when you want to verify that the condition is being evaluated because a particular input has been received and a timer hasn't expired, as in the expression

currentInput("Command") && $input.Command.value == "Abort"

String Matching Functions

startsWith(<expression1>, <expression2>)

Evaluates to true if the first string expression starts with the second string expression. For example, if input MyInput receives the message { "value": "foobar" } then the following evaluates to true.

startsWith($input.MyInput.value, "foo")

Both expressions must evaluate to a string value. If either expression doesn't evaluate to a string value, then the result of the function is undefined. No conversions are performed.

endsWith(<expression1>, <expression2>)

Evaluates to true if the first string expression ends with the second string expression. For example, if input MyInput receives the message { "value": "foobar" } then the following evaluates to true.

endsWith($input.MyInput.value, "bar")

Both expressions must evaluate to a string value. If either expression doesn't evaluate to a string value, then the result of the function is undefined. No conversions are performed.

contains(<expression1>, <expression2>)

Evaluates to true if the first string expression contains the second string expression. For example, if input MyInput receives the message { "value": "foobar" } then the following evaluates to true.

contains($input.MyInput.value, "oba")

Both expressions must evaluate to a string value. If either expression doesn't evaluate to a string value, then the result of the function is undefined, No conversions are performed.

Bitwise Integer Manipulation Functions

bitor(<expression1>, <expression2>)

Evaluates the bitwise OR of the integer expressions (the binary OR operation is performed on the corresponding bits of the integers). For example, if input MyInput receives the message { "value1": 13, "value2": 5 } then the following evaluates to 13.

bitor($input.MyInput.value1, $input.MyInput.value2)

Both expressions must evaluate to an integer value. If either expression doesn't evaluate to an integer value, then the result of the function is undefined. No conversions are performed.

bitand(<expression1>, <expression2>)

Evaluates the bitwise AND of the integer expressions (the binary AND operation is performed on the corresponding bits of the integers). For example, if input MyInput receives the message { "value1": 13, "value2": 5 } then the following evaluates to 5.

bitand($input.MyInput.value1, $input.MyInput.value2)

Both expressions must evaluate to an integer value. If either expression doesn't evaluate to an integer value, then the result of the function is undefined. No conversions are performed.

bitxor(<expression1>, <expression2>)

Evaluates the bitwise XOR of the integer expressions (the binary XOR operation is performed on the corresponding bits of the integers). For example, if input MyInput receives the message { "value1": 13, "value2": 5 } then the following evaluates to 8.

bitxor($input.MyInput.value1, $input.MyInput.value2)

Both expressions must evaluate to an integer value. If either expression doesn't evaluate to an integer value, then the result of the function is undefined. No conversions are performed.

bitnot(<expression>)

Evaluates the bitwise NOT of the integer expression (the binary NOT operation is performed on the bits of the integer). For example, if input MyInput receives the message { "value": 13 } then the following evaluates to -14.

bitnot($input.MyInput.value)

The expression must evaluate to an integer value. If the expression doesn't evaluate to an integer value, then the result of the function is undefined. No conversion is performed.

References

Inputs

$input.<input-name>.<path-to-datum>

<input-name> is an input you have created using the CreateInput operation.

For example, given an input named TemperatureInput for which you have defined inputDefinition.attributes.jsonPath entries that amount to the following available fields:

{ "temperature": 78.5, "date": 2018-10-03T16:09:09Z }

To reference the value of the temperature field, use the following.

$input.TemperatureInput.temperature

For fields whose values are arrays, members of the array can be referenced using [n]. For example, given the following values:

{ "temperatures": [ 78.4, 77.9, 78.8 ], "date": 2018-10-03T16:09:09Z }

The value 78.8 can be referenced with the following.

$input.TemperatureInput.temperatures[2]
Variables

$variable.<variable-name>

<variable-name> is a variable you have defined using CreateDetectorModel.

For example, given a variable named TechnicianID that you have defined using detectorDefinition.states.onInputEvents.actions.setVariable.variableName, you can reference the (string) value most recently given to the variable with the following.

$variable.TechnicianID

You can set the values of variables only using the setVariable action. They can't be assigned a value in an expression. A variable can't be unset. That is, you can't assign it the value null.

Note

In references that use identifiers that don't follow the (regular expression) pattern [a-zA-Z][a-zA-Z0-9_]*, you must enclose those identifiers in backticks (`). For example, a reference to an input named MyInput with a field named _value must specify this field as $input.MyInput.`_value`.