Amazon IoT SiteWise - Amazon IoT Core
RequirementsParametersExamplesSee also
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).

Amazon IoT SiteWise

The Amazon IoT SiteWise (iotSiteWise) action sends data from an MQTT message to asset properties in Amazon IoT SiteWise.

You can follow a tutorial that shows you how to ingest data from Amazon IoT things. For more information, see the Ingesting data to Amazon IoT SiteWise from Amazon IoT things tutorial or the Ingesting data using Amazon IoT Core rules section in the Amazon IoT SiteWise User Guide.

Requirements

This rule action has the following requirements:

  • An IAM role that Amazon IoT can assume to perform the iotsitewise:BatchPutAssetPropertyValue operation. For more information, see Granting an Amazon IoT rule the access it requires.

    You can attach the following example trust policy to the role.

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iotsitewise:BatchPutAssetPropertyValue",
            "Resource": "*"
        }
    ]
}

    To improve security, you can specify an Amazon IoT SiteWise asset hierarchy path in the Condition property. The following example is a trust policy that specifies an asset hierarchy path.

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iotsitewise:BatchPutAssetPropertyValue",
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "iotsitewise:assetHierarchyPath": [
                        "/root node asset ID",
                        "/root node asset ID/*"
                    ]
                }
            }
        }
    ]
}

  • When you send data to Amazon IoT SiteWise with this action, your data must meet the requirements of the BatchPutAssetPropertyValue operation. For more information, see BatchPutAssetPropertyValue in the Amazon IoT SiteWise API Reference.

Parameters

When you create an Amazon IoT rule with this action, you must specify the following information:

putAssetPropertyValueEntries

A list of asset property value entries that each contain the following information:

propertyAlias

(Optional) The property alias associated with your asset property. Specify either a propertyAlias or both an assetId and a propertyId. For more information about property aliases, see Mapping industrial data streams to asset properties in the Amazon IoT SiteWise User Guide.

Supports substitution templates: Yes

assetId

(Optional) The ID of the Amazon IoT SiteWise asset. Specify either a propertyAlias or both an assetId and a propertyId.

Supports substitution templates: Yes

propertyId

(Optional) The ID of the asset's property. Specify either a propertyAlias or both an assetId and a propertyId.

Supports substitution templates: Yes

entryId

(Optional) A unique identifier for this entry. Define the entryId to better track which message caused an error if failure occurs. Defaults to a new UUID.

Supports substitution templates: Yes

propertyValues

A list of property values to insert that each contain timestamp, quality, and value (TQV) in the following format:

timestamp

A timestamp structure that contains the following information:

timeInSeconds

A string that contains the time in seconds in Unix epoch time. If your message payload doesn't have a timestamp, you can use timestamp(), which returns the current time in milliseconds. To convert that time to seconds, you can use the following substitution template: ${floor(timestamp() / 1E3)}.

Supports substitution templates: Yes

offsetInNanos

(Optional) A string that contains the nanosecond time offset from the time in seconds. If your message payload doesn't have a timestamp, you can use timestamp(), which returns the current time in milliseconds. To calculate the nanosecond offset from that time, you can use the following substitution template: ${(timestamp() % 1E3) * 1E6}.

Supports substitution templates: Yes

Regarding Unix epoch time, Amazon IoT SiteWise accepts only entries that have a timestamp of up to 7 days in the past up to 5 minutes in the future.

quality

(Optional) A string that describes the quality of the value. Valid values: GOOD, BAD, UNCERTAIN.

Supports substitution templates: Yes

value

A value structure that contains one of the following value fields, depending on the asset property's data type:

booleanValue

(Optional) A string that contains the Boolean value of the value entry.

Supports substitution templates: Yes

doubleValue

(Optional) A string that contains the double value of the value entry.

Supports substitution templates: Yes

integerValue

(Optional) A string that contains the integer value of the value entry.

Supports substitution templates: Yes

stringValue

(Optional) The string value of the value entry.

Supports substitution templates: Yes

roleArn

The ARN of the IAM role that grants Amazon IoT permission to send an asset property value to Amazon IoT SiteWise. For more information, see Requirements.

Supports substitution templates: No

Examples

The following JSON example defines a basic IoT SiteWise action in an Amazon IoT rule.

{
    "topicRulePayload": {
        "sql": "SELECT * FROM 'some/topic'",
        "ruleDisabled": false,
        "awsIotSqlVersion": "2016-03-23",
        "actions": [
            {
                "iotSiteWise": {
                    "putAssetPropertyValueEntries": [
                        {
                            "propertyAlias": "/some/property/alias",
                            "propertyValues": [
                                {
                                    "timestamp": {
                                        "timeInSeconds": "${my.payload.timeInSeconds}"
                                    },
                                    "value": {
                                        "integerValue": "${my.payload.value}"
                                    }
                                }
                            ]
                        }
                    ],
                    "roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
                }
            }
        ]
    }
}

The following JSON example defines an IoT SiteWise action in an Amazon IoT rule. This example uses the topic as the property alias and the timestamp() function. For example, if you publish data to /company/windfarm/3/turbine/7/rpm, this action sends the data to the asset property with a property alias that's the same as the topic that you specified.

{
    "topicRulePayload": {
        "sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+'",
        "ruleDisabled": false,
        "awsIotSqlVersion": "2016-03-23",
        "actions": [
            {
                "iotSiteWise": {
                    "putAssetPropertyValueEntries": [
                        {
                            "propertyAlias": "${topic()}",
                            "propertyValues": [
                                {
                                    "timestamp": {
                                        "timeInSeconds": "${floor(timestamp() / 1E3)}",
                                        "offsetInNanos": "${(timestamp() % 1E3) * 1E6}"
                                    },
                                    "value": {
                                        "doubleValue": "${my.payload.value}"
                                    }
                                }
                            ]
                        }
                    ],
                    "roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
                }
            }
        ]
    }
}

See also