Map industrial data streams to asset properties - AWS IoT SiteWise
Set a property alias (console)Set a property alias (AWS CLI)

Map industrial data streams to asset properties

You can define a property alias on asset property. This helps you identify an asset property when you ingest or retrieve asset data. If your asset has measurement properties, you can define the property aliases to map your data streams to those measurement properties.

This process requires that you know your property alias.

  • If you ingest data from OPC UA servers using an OPC UA data source in a SiteWise Edge gateway, your property alias is the path to a variable under the Objects node, starting with /.

    Example

    If the path to your variable is company/windfarm/3/turbine/7/temperature, then your property alias is /company/windfarm/3/turbine/7/temperature.

    For more information about OPC UA information architecture, see Information Model and Address Spacing mapping in the OPC UA Online Reference.

    Notes

    • If you configure a data stream prefix for your OPC UA source, you must include that prefix in the property alias for all data streams from that source.

      Example

      If /RentonWA is a prefix, then the previous alias is /RentonWA/company/windfarm/3/turbine/7/temperature.

    • Property aliases can contain up to 1,000 bytes. OPC UA variables paths can contain up to 4,096 bytes. Currently, AWS IoT SiteWise doesn't support ingesting data from OPC UA variables with long paths.

  • If you ingest data from other sources, such as using AWS IoT rules or the API, you must define your property aliases. You can define a property alias naming system that is applicable to your device configuration. For example, if you ingest data from AWS IoT things, you can include the thing name in property aliases to uniquely identify data streams. For more information about this example, see the Ingesting data from AWS IoT things tutorial.

Property aliases must be unique within a Region and AWS account. AWS IoT SiteWise returns an error if you set a property alias to one that already exists on another asset property.

If you have multiple OPC UA sources with identical data stream paths, add a prefix to each source's paths to form unique aliases. For more information, see OPC UA data sources for SiteWise Edge.

Note

This section describes how to set property aliases for measurement properties. For more information about how to set property aliases for external alarm state properties, see Map external alarm state streams in AWS IoT SiteWise.

Set a property alias (console)

You can use the AWS IoT SiteWise console to set an alias for an asset property.

To set a property alias (console)

  1. Navigate to the AWS IoT SiteWise console.

  2. In the navigation pane, choose Assets.

  3. Choose the asset for which you want to set a property alias.

    Tip

    You can choose the arrow icon to expand an asset hierarchy to find your asset.

  4. Choose Edit.

  5. Find the property for which you want to set an alias, and then enter the property alias.

    AWS IoT SiteWise "Edit asset" page screenshot with a property alias highlighted.

  6. Choose Save.

Set a property alias (AWS CLI)

Use the AWS Command Line Interface (AWS CLI) to set an alias for an asset property.

You must know your asset's assetId and property's propertyId to complete this procedure. You can also use the external ID. If you created an asset and don't know its assetId, use the ListAssets API to list all the assets for a specific model. Use the DescribeAsset operation to view your asset's properties including property IDs.

Use the UpdateAssetProperty operation, to map a data stream to your asset's property. Specify the following parameters:

  • assetId – The asset's ID or external ID. For more information, see Reference objects with external IDs in the AWS IoT SiteWise User Guide.

  • propertyId – The asset property's ID or external ID.

  • propertyAlias – The data stream's path to alias to the property.

  • propertyNotificationState – The property value notification state: ENABLED or DISABLED. Specify the property's existing notification state when you update the property alias. You can retrieve the existing notification state with the DescribeAssetProperty operation.

    If you omit this parameter, the new notification state is DISABLED. For more information about property notifications, see Interact with other AWS services.

To set a property alias (AWS CLI)

  1. Run the following command to retrieve the property's current notification state. Replace asset-id and property-id with the asset property's IDs.

    aws iotsitewise describe-asset-property \
  --asset-id asset-id \
  --property-id property-id

    The operation returns a response that contains the asset property's details in the following format. The property notification state is in assetProperty.notification.state in the JSON object.

    {
  "assetId": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE",
  "assetName": "Wind Turbine 7",
  "assetModelId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
  "assetProperty": {
    "id": "a1b2c3d4-5678-90ab-cdef-33333EXAMPLE",
    "name": "Wind Speed",
    "notification": {
      "topic": "$aws/sitewise/asset-models/a1b2c3d4-5678-90ab-cdef-11111EXAMPLE/assets/a1b2c3d4-5678-90ab-cdef-22222EXAMPLE/properties/a1b2c3d4-5678-90ab-cdef-33333EXAMPLE",
      "state": "ENABLED"
    },
    "dataType": "DOUBLE",
    "unit": "m/s",
    "type": {
      "measurement": {}
    }
  }
}

  2. Run the following command to set the asset property's alias. Replace property-alias with the property alias and notification-state with the notification state, or omit --property-notification-state to disable notifications. You can optionally update the asset's unit with a new unit and --property-unit.

    aws iotsitewise update-asset-property \
  --asset-id asset-id \
  --property-id property-id \
  --property-alias property-alias \
  --property-notification-state notification-state \
  --property-unit unit

  3. To verify the alias has been set, run the following command to retrieve the property's details. Replace asset-id and property-id with the asset property's IDs.

    aws iotsitewise describe-asset-property \
  --asset-id asset-id \
  --property-id property-id

    The operation returns a response that contains the asset property's details in the following format. The property alias is assetProperty.alias in the JSON object and is set to myAlias in this example.

    {
  "assetId": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE",
  "assetName": "Wind Turbine 7",
  "assetModelId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
  "assetProperty": {
    "alias": "myAlias",
    "id": "a1b2c3d4-5678-90ab-cdef-33333EXAMPLE",
    "name": "Wind Speed",
    "notification": {
      "topic": "$aws/sitewise/asset-models/a1b2c3d4-5678-90ab-cdef-11111EXAMPLE/assets/a1b2c3d4-5678-90ab-cdef-22222EXAMPLE/properties/a1b2c3d4-5678-90ab-cdef-33333EXAMPLE",
      "state": "ENABLED"
    },
    "dataType": "DOUBLE",
    "unit": "m/s",
    "type": {
      "measurement": {}
    }
  }
}