Functions to use in AWS IoT Events expressions - AWS IoT Events

Functions to use in AWS IoT Events expressions

AWS IoT Events provides a set of built-in functions to enhance the capabilities of your detector model expressions. These functions enable timer management, type conversion, null checking, trigger type identification, input verification, string manipulation, and bitwise operations. By leveraging these functions, you can create a responsive AWS IoT Events processing logic, improving the overall effectiveness of your IoT applications.

Built-in Functions
timeout("timer-name")

Evaluates to true if the specified timer has elapsed. Replace "timer-name" with the name of a timer that you defined, in quotation marks. In an event action, you can define a timer and then start the timer, reset it, or clear one that you previously defined. See the field detectorModelDefinition.states.onInput|onEnter|onExit.events.actions.setTimer.timerName.

A timer set in one state can be referenced in a different state. You must visit the state in which you created the timer before you enter the state in which the timer is referenced.

For example, a detector model has two states, TemperatureChecked and RecordUpdated. You created a timer in the TemperatureChecked state. You must visit the TemperatureChecked state first before you can use the timer in the RecordUpdated state.

To ensure accuracy, the minimum time that 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 value must be String, Boolean, or Decimal. Use one of these keywords or an expression that evaluates to a string containing the keyword. Only the following conversions 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 a valid representation of a decimal number, or convert() fails.

If convert() doesn't 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 value 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 in the following example.

triggerType("Timer")

Or an input message was received. 

triggerType("Message")
currentInput("input")

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

currentInput("Command")

Use this function to verify that the condition is being evaluated because a particular input has been received and a timer hasn't expired, as in the following 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 { "status": "offline"}, then the following evaluates to true.

startsWith($input.MyInput.status, "off")

Both expressions must evaluate to a string value. If either expression does not 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 { "status": "offline" }, then the following evaluates to true.

endsWith($input.MyInput.status, "line")

Both expressions must evaluate to a string value. If either expression does not 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 { "status": "offline" }, then the following evaluates to true.

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

Both expressions must evaluate to a string value. If either expression does not 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 does not 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 does not 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 does not 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)

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