Defining an Amazon IoT Events alarm (CLI)
You can use the Amazon Command Line Interface (Amazon CLI) to define an Amazon IoT Events alarm that monitors an asset property. You can define the alarm on a new or existing asset model. After you define the alarm on the asset model, you create an alarm in Amazon IoT Events and connect it to the asset model. In this process, you do the following:
Steps
Step 1: Defining an alarm on an asset model
Add an alarm definition and associated properties to a new or existing asset model.
To define an alarm on an asset model (CLI)
-
Create a file called
asset-model-payload.json
. Follow the steps in these other sections to add your asset model's details to the file, but don't submit the request to create or update the asset model. In this section, you add an alarm definition to the asset model details in theasset-model-payload.json
file.-
For more information about how to create an asset model, see Creating an asset model (Amazon CLI).
-
For more information about how to update an existing asset model, see Updating an asset model or component model (Amazon CLI).
Note
Your asset model must define at least one asset property, including the asset property to monitor with the alarm.
-
-
Add an alarm composite model (
assetModelCompositeModels
) to the asset model. An Amazon IoT Events alarm composite model specifies theIOT_EVENTS
type and specifies an alarm source property. You add the alarm source property after you create the alarm model in Amazon IoT Events.Important
The alarm composite model must have the same name as the Amazon IoT Events alarm model you create later. Alarm model names can contain only alphanumeric characters. Specify a unique, alphanumeric name so that you can use the same name for the alarm model.
{
...
"assetModelCompositeModels": [ { "name": "BoilerTemperatureHighAlarm", "type": "AWS/ALARM", "properties": [ { "name": "AWS/ALARM_TYPE", "dataType": "STRING", "type": { "attribute": { "defaultValue": "IOT_EVENTS" } } }, { "name": "AWS/ALARM_STATE", "dataType": "STRUCT", "dataTypeSpec": "AWS/ALARM_STATE", "type": { "measurement": {} } } ] } ] } -
Add an alarm threshold attribute to the asset model. Specify the default value to use for this threshold. You can override this default value on each asset based on this model.
Note
The alarm threshold attribute must be an
INTEGER
or aDOUBLE
.{
...
"assetModelProperties": [...
{ "name": "Temperature Max Threshold", "dataType": "DOUBLE", "type": { "attribute": { "defaultValue": "105.0" } } } ] } -
Create the asset model or update the existing asset model. Do one of the following:
-
To create the asset model, run the following command.
aws iotsitewise create-asset-model --cli-input-json file://asset-model-payload.json
-
To update the existing asset model, run the following command. Replace
asset-model-id
with the ID of the asset model.aws iotsitewise update-asset-model \ --asset-model-id
asset-model-id
\ --cli-input-json file://asset-model-payload.json
After you run the command, note the
assetModelId
in the response. -
The following asset model represents a boiler that reports temperature data. This asset model defines an alarm that detects when the boiler overheats.
{ "assetModelName": "Boiler Model", "assetModelDescription": "Represents a boiler.", "assetModelProperties": [ { "name": "Temperature", "dataType": "DOUBLE", "unit": "C", "type": { "measurement": {} } }, { "name": "Temperature Max Threshold", "dataType": "DOUBLE", "type": { "attribute": { "defaultValue": "105.0" } } }, { "name": "identityStoreId", "dataType": "STRING", "type": { "attribute": { "defaultValue": "d-123EXAMPLE" } } }, { "name": "userId", "dataType": "STRING", "type": { "attribute": { "defaultValue": "123EXAMPLE-a1b2c3d4-5678-90ab-cdef-33333EXAMPLE" } } }, { "name": "senderId", "dataType": "STRING", "type": { "attribute": { "defaultValue": "MyFactory" } } }, { "name": "fromAddress", "dataType": "STRING", "type": { "attribute": { "defaultValue": "my.factory@example.com" } } }, { "name": "emailSubject", "dataType": "STRING", "type": { "attribute": { "defaultValue": "[ALERT] High boiler temperature" } } }, { "name": "additionalMessage", "dataType": "STRING", "type": { "attribute": { "defaultValue": "Turn off the power before you check the alarm." } } } ], "assetModelHierarchies": [ ], "assetModelCompositeModels": [ { "name": "BoilerTemperatureHighAlarm", "type": "AWS/ALARM", "properties": [ { "name": "AWS/ALARM_TYPE", "dataType": "STRING", "type": { "attribute": { "defaultValue": "IOT_EVENTS" } } }, { "name": "AWS/ALARM_STATE", "dataType": "STRUCT", "dataTypeSpec": "AWS/ALARM_STATE", "type": { "measurement": {} } } ] } ] }
Step 2: Defining an Amazon IoT Events alarm model
Create the alarm model in Amazon IoT Events. In Amazon IoT Events, you use expressions to specify values in alarm models. You can use expressions to specify values from Amazon IoT SiteWise to evaluate and use as inputs to the alarm. When Amazon IoT SiteWise sends asset property values to the alarm model, Amazon IoT Events evaluates the expression to get the value of the property or the ID of the asset. You can use the following expressions in the alarm model:
-
Asset property values
To get the value of an asset property, use the following expression. Replace
assetModelId
with the ID of the asset model and replacepropertyId
with the ID of the property.$sitewise.assetModel.`
assetModelId
`.`propertyId
`.propertyValue.value -
Asset IDs
To get the ID of the asset, use the following expression. Replace
assetModelId
with the ID of the asset model and replacepropertyId
with the ID of the property.$sitewise.assetModel.`
assetModelId
`.`propertyId
`.assetId
Note
When you create the alarm model, you can define literals instead of expressions that evaluate to Amazon IoT SiteWise values. This can reduce the number of attributes that you define on your asset model. However, if you define a value as a literal, you can't customize that value on assets based on the asset model. Your Amazon IoT SiteWise Monitor users also can't customize the alarm, because they can configure alarm settings on assets only.
To create an Amazon IoT Events alarm model (CLI)
-
When you create the alarm model in Amazon IoT Events, you must specify the ID of each property that the alarm uses, which includes the following:
-
The alarm state property in the composite asset model
-
The property that the alarm monitors
-
The threshold attribute
-
(Optional) The IAM Identity Center identity store ID attribute
-
(Optional) The IAM Identity Center user ID attribute
-
(Optional) The SMS sender ID attribute
-
(Optional) The email from address attribute
-
(Optional) The email subject attribute
-
(Optional) The additional message attribute
Run the following command to retrieve the IDs of these properties on the asset model. Replace
asset-model-id
with the ID of the asset model from the previous step.aws iotsitewise describe-asset-model --asset-model-id
asset-model-id
The operation returns a response that contains the asset model's details. Note the ID of each property that the alarm uses. You use these IDs when you create the Amazon IoT Events alarm model in the next step.
-
-
Create the alarm model in Amazon IoT Events. Do the following:
-
Create a file called
alarm-model-payload.json
. -
Copy the following JSON object into the file.
-
Enter a name (
alarmModelName
), description (alarmModelDescription
), and severity (severity
) for your alarm. For severity, specify an integer that reflects your company's severity levels.Important
The alarm model must have the same name as the alarm composite model that you defined on your asset model earlier.
Alarm model names can contain only alphanumeric characters.
{ "alarmModelName": "
BoilerTemperatureHighAlarm
", "alarmModelDescription": "Detects when the boiler temperature is high.
", "severity":3
} -
Add the comparison rule (
alarmRule
) to the alarm. This rule defines the property to monitor (inputProperty
), the threshold value to compare (threshold
), and the comparison operator to use (comparisonOperator
).-
Replace
assetModelId
with the ID of the asset model. -
Replace
alarmPropertyId
with the ID of the property that the alarm monitors. -
Replace
thresholdAttributeId
with the ID of the threshold attribute property. -
Replace
GREATER
with the operator to use to compare the property values with the threshold. Choose from the following options:-
LESS
-
LESS_OR_EQUAL
-
EQUAL
-
NOT_EQUAL
-
GREATER_OR_EQUAL
-
GREATER
-
{ "alarmModelName": "
BoilerTemperatureHighAlarm
", "alarmModelDescription": "Detects when the boiler temperature is high.
", "severity":3
, "alarmRule": { "simpleRule": { "inputProperty": "$sitewise.assetModel.`assetModelId
`.`alarmPropertyId
`.propertyValue.value", "comparisonOperator": "GREATER
", "threshold": "$sitewise.assetModel.`assetModelId
`.`thresholdAttributeId
`.propertyValue.value" } } } -
-
Add an action (
alarmEventActions
) to send alarm state to the Amazon IoT SiteWise when the alarm changes state.Note
For advanced configuration, you can define additional actions to perform when the alarm changes state. For example, you might call an Amazon Lambda function or publish to an MQTT topic. For more information, see Working with other Amazon services in the Amazon IoT Events Developer Guide.
-
Replace
assetModelId
with the ID of the asset model. -
Replace
alarmPropertyId
with the ID of the property that the alarm monitors. -
Replace
alarmStatePropertyId
with the ID of the alarm state property in the alarm composite model.
{ "alarmModelName": "
BoilerTemperatureHighAlarm
", "alarmModelDescription": "Detects when the boiler temperature is high.
", "severity":3
, "alarmRule": { "simpleRule": { "inputProperty": "$sitewise.assetModel.`assetModelId
`.`alarmPropertyId
`.propertyValue.value", "comparisonOperator": "GREATER
", "threshold": "$sitewise.assetModel.`assetModelId
`.`thresholdAttributeId
`.propertyValue.value" } }, "alarmEventActions": { "alarmActions": [ { "iotSiteWise": { "assetId": "$sitewise.assetModel.`assetModelId
`.`alarmPropertyId
`.assetId", "propertyId": "'alarmStatePropertyId
'" } } ] } } -
-
(Optional) Add the alarm capabilities (
alarmCapabilities
) to the payload inalarm-model-payload.json
. In this object, you can specify if the acknowledge flow is enabled and the default enable state for assets based on the asset model. For more information about the acknowledge flow, see Alarm states.{ "alarmModelName": "
BoilerTemperatureHighAlarm
", "alarmModelDescription": "Detects when the boiler temperature is high.
", "severity":3
, "alarmRule": { "simpleRule": { "inputProperty": "$sitewise.assetModel.`assetModelId
`.`alarmPropertyId
`.propertyValue.value", "comparisonOperator": "GREATER
", "threshold": "$sitewise.assetModel.`assetModelId
`.`thresholdAttributeId
`.propertyValue.value" } }, "alarmEventActions": { "alarmActions": [ { "iotSiteWise": { "assetId": "$sitewise.assetModel.`assetModelId
`.`alarmPropertyId
`.assetId", "propertyId": "'alarmStatePropertyId
'" } } ] }, "alarmNotification": { "notificationActions": [ { "action": { "lambdaAction": { "functionArn": "alarmNotificationFunctionArn
" } }, "smsConfigurations": [ { "recipients": [ { "ssoIdentity": { "identityStoreId": "$sitewise.assetModel.`assetModelId
`.`identityStoreIdAttributeId
`.propertyValue.value", "userId": "$sitewise.assetModel.`assetModelId
`.`userIdAttributeId
`.propertyValue.value" } } ], "senderId": "$sitewise.assetModel.`assetModelId
`.`senderIdAttributeId
`.propertyValue.value", "additionalMessage": "$sitewise.assetModel.`assetModelId
`.`additionalMessageAttributeId
`.propertyValue.value" } ], "emailConfigurations": [ { "from": "$sitewise.assetModel.`assetModelId
`.`fromAddressAttributeId
`.propertyValue.value", "recipients": { "to": [ { "ssoIdentity": { "identityStoreId": "$sitewise.assetModel.`assetModelId
`.`identityStoreIdAttributeId
`.propertyValue.value", "userId": "$sitewise.assetModel.`assetModelId
`.`userIdAttributeId
`.propertyValue.value" } } ] }, "content": { "subject": "$sitewise.assetModel.`assetModelId
`.`emailSubjectAttributeId
`.propertyValue.value", "additionalMessage": "$sitewise.assetModel.`assetModelId
`.`additionalMessageAttributeId
`.propertyValue.value" } } ] } ] }, "alarmCapabilities": { "initializationConfiguration": { "disabledOnInitialization":false
}, "acknowledgeFlow": { "enabled":true
} } } -
Add the IAM service role (
roleArn
) that Amazon IoT Events can assume to send data to Amazon IoT SiteWise. This role requires theiotsitewise:BatchPutAssetPropertyValue
permission and a trust relationship that allowsiotevents.amazonaws.com
to assume the role. For more information, see Alarm service roles in the Amazon IoT Events Developer Guide.-
Replace the
roleArn
with the ARN of the role that Amazon IoT Events can assume to perform these actions.
{ "alarmModelName": "
BoilerTemperatureHighAlarm
", "alarmModelDescription": "Detects when the boiler temperature is high.
", "severity":3
, "alarmRule": { "simpleRule": { "inputProperty": "$sitewise.assetModel.`assetModelId
`.`alarmPropertyId
`.propertyValue.value", "comparisonOperator": "GREATER
", "threshold": "$sitewise.assetModel.`assetModelId
`.`thresholdAttributeId
`.propertyValue.value" } }, "alarmEventActions": { "alarmActions": [ { "iotSiteWise": { "assetId": "$sitewise.assetModel.`assetModelId
`.`alarmPropertyId
`.assetId", "propertyId": "'alarmStatePropertyId
'" } } ] }, "alarmNotification": { "notificationActions": [ { "action": { "lambdaAction": { "functionArn": "alarmNotificationFunctionArn
" } }, "smsConfigurations": [ { "recipients": [ { "ssoIdentity": { "identityStoreId": "$sitewise.assetModel.`assetModelId
`.`identityStoreIdAttributeId
`.propertyValue.value", "userId": "$sitewise.assetModel.`assetModelId
`.`userIdAttributeId
`.propertyValue.value" } } ], "senderId": "$sitewise.assetModel.`assetModelId
`.`senderIdAttributeId
`.propertyValue.value", "additionalMessage": "$sitewise.assetModel.`assetModelId
`.`additionalMessageAttributeId
`.propertyValue.value" } ], "emailConfigurations": [ { "from": "$sitewise.assetModel.`assetModelId
`.`fromAddressAttributeId
`.propertyValue.value", "recipients": { "to": [ { "ssoIdentity": { "identityStoreId": "$sitewise.assetModel.`assetModelId
`.`identityStoreIdAttributeId
`.propertyValue.value", "userId": "$sitewise.assetModel.`assetModelId
`.`userIdAttributeId
`.propertyValue.value" } } ] }, "content": { "subject": "$sitewise.assetModel.`assetModelId
`.`emailSubjectAttributeId
`.propertyValue.value", "additionalMessage": "$sitewise.assetModel.`assetModelId
`.`additionalMessageAttributeId
`.propertyValue.value" } } ] } ] }, "alarmCapabilities": { "initializationConfiguration": { "disabledOnInitialization":false
}, "acknowledgeFlow": { "enabled":false
} }, "roleArn": "arn:aws:iam::123456789012
:role/MyIoTEventsAlarmRole
" } -
-
Run the following command to create the Amazon IoT Events alarm model from the payload in
alarm-model-payload.json
.aws iotevents create-alarm-model --cli-input-json file://alarm-model-payload.json
-
The operation returns a response that includes the ARN of the alarm model,
alarmModelArn
. Copy this ARN to set in the alarm definition on your asset model in the next step.
-
Step 3: Enabling data flow between Amazon IoT SiteWise and Amazon IoT Events
After you create the required resources in Amazon IoT SiteWise and Amazon IoT Events, you can enable data flow between the resources to enable your alarm. In this section, you update the alarm definition in the asset model to use the alarm model that you created in the previous step.
To enable data flow between Amazon IoT SiteWise and Amazon IoT Events (CLI)
-
Set the alarm model as the alarm's source in the asset model. Do the following:
-
Run the following command to retrieve the existing asset model definition. Replace
asset-model-id
with the ID of the asset model.aws iotsitewise describe-asset-model --asset-model-id
asset-model-id
The operation returns a response that contains the asset model's details.
-
Create a file called
update-asset-model-payload.json
and copy the previous command's response into the file. -
Remove the following key-value pairs from the
update-asset-model-payload.json
file:-
assetModelId
-
assetModelArn
-
assetModelCreationDate
-
assetModelLastUpdateDate
-
assetModelStatus
-
-
Add the alarm source property (
AWS/ALARM_SOURCE
) to the alarm composite model that you defined earlier. ReplacealarmModelArn
with the ARN of the alarm model, which sets the value of the alarm source property.{
...
"assetModelCompositeModels": [...
{ "name": "BoilerTemperatureHighAlarm", "type": "AWS/ALARM", "properties": [ { "id": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE", "name": "AWS/ALARM_TYPE", "dataType": "STRING", "type": { "attribute": { "defaultValue": "IOT_EVENTS" } } }, { "id": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE", "name": "AWS/ALARM_STATE", "dataType": "STRUCT", "dataTypeSpec": "AWS/ALARM_STATE", "type": { "measurement": {} } }, { "name": "AWS/ALARM_SOURCE", "dataType": "STRING", "type": { "attribute": { "defaultValue": "alarmModelArn
" } } } ] } ] } -
Run the following command to update the asset model with the definition stored in the
update-asset-model-payload.json
file. Replaceasset-model-id
with the ID of the asset model.aws iotsitewise update-asset-model \ --asset-model-id
asset-model-id
\ --cli-input-json file://update-asset-model-payload.json
-
Your asset model now defines an alarm that detects in Amazon IoT Events. The alarm monitors the target property in all assets based on this asset model. You can configure the alarm on each asset to customize properties such as the threshold or IAM Identity Center recipient for each asset. For more information, see Configuring alarms on assets.