# Ingest an external alarm state in AWS IoT SiteWise
<a name="ingest-external-alarm-state"></a>

External alarms are alarms that you evaluate outside of AWS IoT SiteWise. You can use external alarms when you have a data source that reports alarm state that you want to ingest to AWS IoT SiteWise.

Alarm state properties require a specific format for alarm state data values. Each data value must be a JSON object serialized to a string. Then, you ingest the serialized string as a string value. For more information, see [Alarm state properties](industrial-alarms.md#alarm-state-properties).

**Example alarm state data value (not serialized)**  

```
{
  "stateName": "Active"
}
```

**Example alarm state data value (serialized)**  

```
{\"stateName\":\"Active\"}
```

**Note**  
If your data source can't report data in this format, or you can't convert your data to this format before you ingest it, you might choose not to use an alarm property. Instead, you can ingest the data as a measurement property with the string data type, for example. For more information, see [Define data streams from equipment (measurements)](measurements.md) and [Ingest data to AWS IoT SiteWise](industrial-data-ingestion.md).

# Map external alarm state streams in AWS IoT SiteWise
<a name="connect-alarm-data-streams"></a>

You can define property aliases to map your data streams to your alarm state properties. This helps you easily identify an alarm state property when you ingest or retrieve data. For more information about property aliases, see [Manage data streams for AWS IoT SiteWise](manage-data-streams.md).

**Topics**
+ [Map external alarm state streams (console)](#connect-alarm-data-stream-console)
+ [Map external alarm state streams (AWS CLI)](#connect-alarm-data-stream-cli)

## Map external alarm state streams (console)
<a name="connect-alarm-data-stream-console"></a>

You can define property aliases to map your data streams to your alarm state properties. This helps you easily identify an alarm state property when you ingest or retrieve data. For more information about property aliases, see [Manage data streams for AWS IoT SiteWise](manage-data-streams.md).

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

**To set a property alias for an alarm state property (console)**

1. <a name="sitewise-open-console"></a>Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).

1. <a name="sitewise-choose-assets"></a>In the navigation pane, choose **Assets**.

1. Choose the asset for which you want to set a property alias.
**Tip**  <a name="sitewise-expand-asset-hierarchy"></a>
You can choose the arrow icon to expand an asset hierarchy to find your asset.

1. Choose **Edit**.

1. Scroll to **Alarms** and expand the section.

1. Under **External Alarms**, enter the alias in **Property alias – *optional***.

1. Choose **Save**.

## Map external alarm state streams (AWS CLI)
<a name="connect-alarm-data-stream-cli"></a>

You can define property aliases to map your data streams to your alarm state properties. This helps you easily identify an alarm state property when you ingest or retrieve data. For more information about property aliases, see [Manage data streams for AWS IoT SiteWise](manage-data-streams.md).

You can use the AWS Command Line Interface (AWS CLI) to set an alias for an alarm state 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](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssets.html) API to list all the assets for a specific model. Use the [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) operation to view your asset's properties including property IDs.

**Note**  
The [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) response includes the list of composite asset models for the asset. Each alarm is a composite model. To find the `propertyId`, find the composite model for the alarm, and then find the `AWS/ALARM_STATE` property in that composite model.

For more information about how to set the property alias, see [Update an asset property alias](update-data-streams-method.md).

# Ingest alarm state data in AWS IoT SiteWise
<a name="ingest-alarm-state-data"></a>

Alarm state properties expect alarm state as a serialized JSON string. To ingest alarm state to an external alarm in AWS IoT SiteWise, you ingest this serialized string as a timestamped string value. The following example demonstrates a state data value for an active alarm.

```
{\"stateName\":\"Active\"}
```

To identify an alarm state property, you can specify one of the following:
+ The `assetId` and `propertyId` of the alarm property that you're sending data to.
+ The `propertyAlias`, which is a data stream alias (for example, `/company/windfarm/3/turbine/7/temperature/high`). To use this option, you must first set your alarm property's alias. To learn how to set property aliases for alarm state properties, see [Map external alarm state streams in AWS IoT SiteWise](connect-alarm-data-streams.md).

The following example [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) API payload demonstrates how to format the state of an external alarm. This external alarm reports when a wind turbine's rotations per minute (RPM) reading is too high.

**Example BatchPutAssetPropertyValue payload for alarm state data**  

```
{
    "entries": [
      {
        "entryId": "unique entry ID",
        "propertyAlias": "/company/windfarm/3/turbine/7/temperature/high",
        "propertyValues": [
          {
            "value": {
              "stringValue": "{\"stateName\":\"Active\"}"
            },
            "timestamp": {
              "timeInSeconds": 1607550262
            }
          }
        ]
      }
    ]
  }
```
For more information about how to use the `BatchPutAssetPropertyValue` API to ingest data, see [Ingest data with AWS IoT SiteWise APIs](ingest-api.md).  
For more information about other ways to ingest data, see [Ingest data to AWS IoT SiteWise](industrial-data-ingestion.md).