Expressions
AWS IoT Events provides several ways to specify values when you create and update detector models. You can use expressions to specify literal values, or AWS IoT Events can evaluate the expressions before you specify particular values.
Syntax
You can use literals, operators, functions, references, and substitution templates in the AWS IoT Events expressions.
Literals
-
Integer
-
Decimal
-
String
-
Boolean
Operators
- Unary
-
-
Not (Boolean):
!
-
Not (bitwise):
~
-
Minus (arithmetic):
-
-
- String
-
-
Concatenation:
+
Both operands must be strings. String literals must be enclosed in single quotes (').
For example:
'my' + 'string'
->'mystring'
-
- Arithmetic
-
-
Addition:
+
Both operands must be numeric.
-
Subtraction:
-
-
Division:
/
The result of the division is a rounded integer value unless at least one of the operands (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 asfalse
.
-
- Parentheses
-
You can use parentheses to group terms within an expression.
Functions
- 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 fielddetectorModelDefinition.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()
returnstrue
only the first time it's checked following the actual timer expiration and returnsfalse
thereafter. convert(
type
,expression
)-
Evaluates to the value of the expression converted to the specified type. The
type
value must beString
,Boolean
, orDecimal
. 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 tofalse
and won't trigger theactions
or transition to thenextState
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 inputMyInput
receives the message{ "a": null }
, then the following evaluates totrue
, butisUndefined($input.MyInput.a)
evaluates tofalse
.isNull($input.MyInput.a)
isUndefined(
expression
)-
Evaluates to
true
if the expression is undefined. For example, if the inputMyInput
receives the message{ "a": null }
, then the following evaluates tofalse
, butisNull($input.MyInput.a)
evaluates totrue
.isUndefined($input.MyInput.a)
triggerType("
type
")-
The
type
value can be"Message"
or"Timer"
. Evaluates totrue
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 inputCommand
receives the message{ "value": "Abort" }
, then the following evaluates totrue
.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 inputMyInput
receives the message{ "status": "offline"}
, then the following evaluates totrue
.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 inputMyInput
receives the message{ "status": "offline" }
, then the following evaluates totrue
.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 inputMyInput
receives the message{ "status": "offline" }
, then the following evaluates totrue
.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 to13
.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 to5
.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 to8
.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.
References
- Inputs
-
$input.
input-name
.path-to-data
input-name
is an input that you create using the CreateInput action.For example, if you have an input named
TemperatureInput
for which you definedinputDefinition.attributes.jsonPath
entries, the values might appear in the following available fields.{ "temperature": 78.5, "date": "2018-10-03T16:09:09Z" }
To reference the value of the
temperature
field, use the following command.$input.TemperatureInput.temperature
For fields whose values are arrays, you can reference members of the array using
[
. For example, given the following values:n
]{ "temperatures": [ 78.4, 77.9, 78.8 ], "date": "2018-10-03T16:09:09Z" }
The value
78.8
can be referenced with the following command.$input.TemperatureInput.temperatures[2]
- Variables
-
$variable.
variable-name
The
is a variable that you defined using the CreateDetectorModel action.variable-name
For example, if you have a variable named
TechnicianID
that you defined usingdetectorDefinition.states.onInputEvents.actions.setVariable.variableName
, you can reference the (string) value most recently given to the variable with the following command.$variable.TechnicianID
You can set the values of variables only using the
setVariable
action. You can't assign values for variables in an expression. A variable can't be unset. For example, you can't assign it the valuenull
.
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`
.
When you use references in expressions, check the following:
-
When you use a reference as an operand with one or more operators, make sure that all data types that you reference are compatible.
For example, in the following expression, integer
2
is an operand of both the==
and&&
operators. To ensure that the operands are compatible,$variable.testVariable + 1
and$variable.testVariable
must reference an integer or decimal.In addition, integer
1
is an operand of the+
operator. Therefore,$variable.testVariable
must reference an integer or decimal.‘$variable.testVariable + 1 == 2 && $variable.testVariable’
-
When you use a reference as an argument passed to a function, make sure that the function supports the data types that you reference.
For example, the following
timeout("
function requires a string with double quotes as the argument. If you use a reference for thetime-name
")timer-name
value, you must reference a string with double quotes.timeout("
timer-name
")Note
For the
convert(
function, if you use a reference for thetype
,expression
)type
value, the evaluated result of your reference must beString
,Decimal
, orBoolean
.
AWS IoT Events expressions support integer, decimal, string, and Boolean data types. The following table provides a list of incompatible pairs of types.
Incompatible pairs of types |
---|
Integer, string |
Integer, Boolean |
Decimal, string |
Decimal, Boolean |
String, Boolean |
Substitution templates
-
'${
expression
}'The
${}
identifies the string as an interpolated string. Theexpression
can be any AWS IoT Events expression. This includes operators, functions, and references.For example, you used the SetVariableAction action to define a variable. The
variableName
isSensorID
, and thevalue
is10
. You can create the following substitution templates.Substitution template Result string '${'Sensor ' + $variable.SensorID}'
"Sensor 10"
'Sensor ' + '${$variable.SensorID + 1}'
"Sensor 11"
'Sensor 10: ${$variable.SensorID == 10}'
"Sensor 10: true"
'{\"sensor\":\"${$variable.SensorID + 1}\"}'
"{\"sensor"\:\"11\"}"
'{\"sensor\":${$variable.SensorID + 1}}'
"{\"sensor\":11}"