Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Connect Amazon IoT SiteWise Alarms to Amazon IoT TwinMaker Grafana dashboards

Amazon IoT TwinMaker is able import Amazon IoT SiteWise and Events alarms into Amazon IoT TwinMaker components. This allows you to be able to query alarm status and configure alarm thresholds without implementing a custom data connector for Amazon IoT SiteWise data migration. You can use the Amazon IoT TwinMaker Grafana plugin to visualize the alarm status and configure the alarm threshold in Grafana, without making API calls to Amazon IoT TwinMaker or interacting directly with Amazon IoT SiteWise alarms.

Amazon IoT SiteWise alarm configuration prerequisites

Before creating alarms and integrating them into your Grafana dashboard, make sure you have reviewed the following prerequisites:

Define the Amazon IoT SiteWise alarm component IAM role

Amazon IoT TwinMaker uses the workspace IAM role to query and configure the alarm threshold in Grafana. The following permissions are required in the Amazon IoT TwinMaker workspace role, in order to interact with Amazon IoT SiteWise alarms in Grafana:

{
"Effect": "Allow",
    "Action": [
        "iotevents:DescribeAlarmModel",
    ],
    "Resource": ["{IoTEventsAlarmModelArn}"]
},{
"Effect": "Allow",
    "Action": [
        "iotsitewise:BatchPutAssetPropertyValue"
    ],
    "Resource": ["{IoTSitewiseAssetArn}"]
}

In the Amazon IoT TwinMaker console, create an entity that represents your Amazon IoT SiteWise asset. Make sure you add a component for that entity using com.amazon.iotsitewise.alarm as the component type, and pick the corresponding asset and alarm models.

The above screenshot is example of creating this entity with the type com.amazon.iotsitewise.alarm.

When you create this component, Amazon IoT TwinMaker automatically imports the related alarm properties from Amazon IoT SiteWise and Amazon IoT Events. You can the repeat this alarm component type pattern to create alarm components for all the assets needed in your workspace.

Query and update through the Amazon IoT TwinMaker API

After creating alarm components, you can query the alarm status, threshold, and update alarm thresholds through the Amazon IoT TwinMaker API.

Below is a sample request to query alarm status:

aws iottwinmaker get-property-value-history --cli-input-json \
'{
    "workspaceId": "{workspaceId}",
    "entityId": "{entityId}",
    "componentName": "{componentName}",
    "selectedProperties": ["alarm_status"],
    "startTime": "{startTimeIsoString}",
    "endTime": "{endTimeIsoString}"
}'

Below is a sample request to query the alarm threshold.

aws iottwinmaker get-property-value-history --cli-input-json \
'{
    "workspaceId": "{workspaceId}",
    "entityId": "{entityId}",
    "componentName": "{componentName}",
    "selectedProperties": ["alarm_threshold"],
    "startTime": "{startTimeIsoString}",
    "endTime": "{endTimeIsoString}"
}'

Below is a sample request to update the alarm threshold:

aws iottwinmaker batch-put-property-values --cli-input-json \
'{
    "workspaceId": "{workspaceId}",
    "entries": [
        {
            "entityPropertyReference": {
                "entityId": "{entityId}",
                "componentName": "{componentName}",
                "propertyName": "alarm_threshold"
            },
            "propertyValues": [
                {
                    "value": {
                        "doubleValue": "{newThreshold}"
                    },
                    "time": "{effectiveTimeIsoString}"
                }
            ]
        }
    ]
}'

Configure your Grafana dashboard for alarms

A second write enabled dashboard IAM role needs to be created , that is a normal role but with permission for the action iottwinmaker:BatchPutPropertyValues to add to the TwinMaker workspace arn like in the example below.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iottwinmaker:Get*",
               "iottwinmaker:List*",
                "iottwinmaker:BatchPutPropertyValues"
            ],
            "Resource": [
                "{workspaceArn}",
                "{workspaceArn}/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "iottwinmaker:ListWorkspaces",
            "Resource": "*"
        }
    ]
}

Alternatively you can add this statement at the end of your IAM role instead:

{
    "Effect": "Allow",
    "Action": [
        "iottwinmaker:BatchPutPropertyValues"
    ],
    "Resource": [
        "{workspaceArn}",
        "{workspaceArn}/*"
    ]
}

The datasource needs to have it’s write arn set with the dashboard write role you created.

After you modify your IAM role, login into your Grafana dashboard to assume the updated role arn. Select the checkbox for Define write permissions for Alarm Configuration Panel and copy in the arn for the Write role.

Use Grafana dashboard for alarm visualization

Use the following procedure to add an alarm configuration panel to your dashboard and configure it: :