# Update assets and models


You can update your assets, asset models, component models, and interfaces in AWS IoT SiteWise to modify their names and definitions. These update operations are asynchronous and take time to propagate through AWS IoT SiteWise. Check the status of the asset or model before you make additional changes. You must wait until the changes propagate before you can continue to use the updated asset or model.

**Topics**
+ [

# Update assets in AWS IoT SiteWise
](update-assets.md)
+ [

# Update asset models, component models, and interfaces
](update-asset-models.md)
+ [

# Update custom composite models (components)
](update-custom-composite-models.md)
+ [

# Optimistic locking for asset model writes
](opt-locking-for-model.md)

# Update assets in AWS IoT SiteWise


You can use the AWS IoT SiteWise console or API to update an asset's name.

When you update an asset, the asset's status is `UPDATING` until the changes propagate. For more information, see [Asset and model states](asset-and-model-states.md).

**Topics**
+ [

## Update an asset (console)
](#update-asset-console)
+ [

## Update an asset (AWS CLI)
](#update-asset-cli)

## Update an asset (console)


You can use the AWS IoT SiteWise console to update asset details.

**To update an asset (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 to update.
**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. Update the asset's **Name**.

1. (Optional) On this page, update other information for the asset. For more information, see the following:
   + [Manage data streams for AWS IoT SiteWise](manage-data-streams.md)
   + [Update attribute values](update-attribute-values.md)
   + [Interact with other AWS services](interact-with-other-services.md)

1. Choose **Save**.

## Update an asset (AWS CLI)


You can use the AWS Command Line Interface (AWS CLI) to update an asset's name.

Use the [UpdateAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAsset.html) operation to update an asset. Specify the following parameters:
+ `assetId` – The ID of the asset. This is the actual ID in UUID format, or the `externalId:myExternalId` if it has one. For more information, see [Reference objects with external IDs](object-ids.md#external-id-references) in the *AWS IoT SiteWise User Guide*.
+ `assetName` – The asset's new name.

**To update an asset's name (AWS CLI)**
+ Run the following command to update an asset's name. Replace *asset-id* with the ID or external ID of the asset. Update the *asset-name* with the new name for the asset.

  ```
  aws iotsitewise update-asset \
    --asset-id asset-id \
    --asset-name asset-name
  ```

# Update asset models, component models, and interfaces


Use the AWS IoT SiteWise console or API to update an asset model, component model, or interface.

You can't change the type or data type of an existing property, or the window of an existing metric. You also can't change the type of the model from asset model to component model or interface, or the other way around.

**Important**  
If you remove a property from an asset model or component model, AWS IoT SiteWise deletes all previous data for that property. For component models, this affects **all asset models using that component model**, so be especially careful to understand how widely your change may apply.
If you remove a hierarchy definition from an asset model, AWS IoT SiteWise disassociates all assets in that hierarchy.

When you update an asset model, every asset based on that model reflects any changes that you make to the underlying model. Until the changes propagate, each asset has the `UPDATING` state. You must wait until those assets return to the `ACTIVE` state before you interact with them. During this time, the updated asset model's status will be `PROPAGATING`.

When you update a component model, every asset model that incorporates that component model reflects the changes. Until the component model changes propagate, each affected asset model has the `UPDATING` state, followed by `PROPAGATING` as it updates its associated assets, as described in the preceding paragraph. You must wait until those asset models return to the `ACTIVE` state before you interact with them. During this time, the updated component model's status will be `PROPAGATING`.

For more information, see [Asset and model states](asset-and-model-states.md).

**Topics**
+ [

## Updating an asset model, component model, or interface (console)
](#update-asset-model-console)
+ [

## Update an asset model, component model, or interface (AWS CLI)
](#update-asset-model-cli)

## Updating an asset model, component model, or interface (console)


You can use the AWS IoT SiteWise console to update an asset model, component model, or interface.

**To update an asset model, component model, or interface (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-models"></a>In the navigation pane, choose **Models**.

1. Choose the asset model, component model, or interface to update.

1. Choose **Edit**.

1. On the **Edit model** page, do any of the following:
   + In **Model details**, change the **Name** of the model.
   + Change any of the **Attribute definitions**. You can't change the **Data type** of existing attributes. For more information, see [Define static data (attributes)](attributes.md).
   + Change any of the **Measurement definitions**. You can't change the **Data type** of existing measurements. For more information, see [Define data streams from equipment (measurements)](measurements.md).
   + Change any of the **Transform definitions**. For more information, see [Transform data (transforms)](transforms.md).
   + Change any of the **Metric definitions**. You can't change the **Time interval** of existing metrics. For more information, see [Aggregate data from properties and other assets (metrics)](metrics.md).
   + (Asset models only) Change any of the **Hierarchy definitions**. You can't change the **Hierarchy model** of existing hierarchies. For more information, see [Define asset model hierarchies](define-asset-hierarchies.md).

1. Choose **Save**.

**Note**  
 Update requests made in the console are rejected, if another user successfully updates the asset model since you last opened the **Edit model** page. The console prompts the user to **Refresh** the **Edit model** page, to fetch the updated model. You must make your updates again, and retry your save. See [Optimistic locking for asset model writes](opt-locking-for-model.md) for more details. 

## Update an asset model, component model, or interface (AWS CLI)


Use the AWS Command Line Interface (AWS CLI) to update an asset model, component model, or interface.

Use the [UpdateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModel.html) API to update the name, description, and properties of an asset model, component model, or interface. For asset models only, you can update hierarchies. For interfaces, you can update properties and hierarchies. Specify the following parameters:
+ `assetModelId` – The ID of the asset. This is the actual ID in UUID format, or the `externalId:myExternalId` if it has one. For more information, see [Reference objects with external IDs](object-ids.md#external-id-references) in the *AWS IoT SiteWise User Guide*.

Specify the updated model in the payload. To learn about the expected format of an asset model or component model, see [Create asset models in AWS IoT SiteWise](create-asset-models.md). 

**Warning**  
The [UpdateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModel.html) API overwrites the existing model with the model that you provide in the payload. To avoid deleting your model's properties or hierarchies, you must include their IDs and definitions in the updated model payload. To learn how to query your model's existing structure, see the [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) operation.

**Note**  
The following procedure can only update composite models of type `AWS/ALARM`. If you want to update `CUSTOM` composite models, use [UpdateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModelCompositeModel.html) instead. For more information, see [Update custom composite models (components)](update-custom-composite-models.md).

**To update an asset model or component model (AWS CLI)**

1. Run the following command to retrieve the existing model definition. Replace *asset-model-id* with the ID or the external ID of the asset model or component model to update.

   ```
   aws iotsitewise describe-asset-model --asset-model-id asset-model-id
   ```

   The above command returns the model definition corresponding to model’s latest version.

    For an use case where an asset model is in a `FAILED` state, retrieve the valid model definition corresponding to its active version to build your update request. See [Asset model versions](model-active-version.md) for details. Run the following command to retrieve the active model definition:

   ```
   aws iotsitewise describe-asset-model --asset-model-id asset-model-id --asset-model-version ACTIVE 
   ```

   The operation returns a response that contains the model's details. The response has the following structure.

   ```
   {
       "assetModelId": "String",
       "assetModelArn": "String",
       "assetModelName": "String",
       "assetModelDescription": "String",
       "assetModelProperties": Array of AssetModelProperty,
       "assetModelHierarchies": Array of AssetModelHierarchyDefinition,
       "assetModelCompositeModels": Array of AssetModelCompositeModel,
       "assetModelCompositeModelSummaries": Array of AssetModelCompositeModelSummary,
       "assetModelCreationDate": "String",
       "assetModelLastUpdateDate": "String",
       "assetModelStatus": {
         "state": "String",
         "error": {
           "code": "String",
           "message": "String"
         },
       "assetModelType": "String"
       },
       "assetModelVersion": "String",
       "eTag": "String"
   }
   ```

   For more information, see the [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) operation.

1. Create a file called `update-asset-model.json` and copy the previous command's response into the file.

1. Remove the following key-value pairs from the JSON object in `update-asset-model.json`:
   + `assetModelId`
   + `assetModelArn`
   + `assetModelCompositeModelSummaries`
   + `assetModelCreationDate`
   + `assetModelLastUpdateDate`
   + `assetModelStatus`
   + `assetModelType`
   + `assetModelVersion`
   + `eTag`

   The [UpdateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModel.html) operation expects a payload with the following structure:

   ```
   {
     "assetModelName": "String",
     "assetModelDescription": "String",
     "assetModelProperties": Array of AssetModelProperty,
     "assetModelHierarchies": Array of AssetModelHierarchyDefinition,
     "assetModelCompositeModels": Array of AssetModelCompositeModel
   }
   ```

1. In `update-asset-model.json`, do any of the following:
   + Change the asset model's name (`assetModelName`).
   + Change, add, or remove the asset model's description (`assetModelDescription`).
   + Change, add, or remove any of the asset model's properties (`assetModelProperties`). You can't change the `dataType` of existing properties or the `window` of existing metrics. For more information, see [Define data properties](asset-properties.md).
   + Change, add, or remove any of the asset model's hierarchies (`assetModelHierarchies`). You can't change the `childAssetModelId` of existing hierarchies. For more information, see [Define asset model hierarchies](define-asset-hierarchies.md).
   + Change, add, or remove any of the asset model's composite models of type `AWS/ALARM` (`assetModelCompositeModels`). Alarms monitor other properties so that you can identify when equipment or processes require attention. Each alarm definition is a composite model that standardizes the set of properties that the alarm uses. For more information, see [Monitor data with alarms in AWS IoT SiteWise](industrial-alarms.md) and [Define alarms on asset models in AWS IoT SiteWise](define-alarms.md).

1. Run the following command to update the asset model with the definition stored in `update-asset-model.json`. 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://model-payload.json
   ```

**Important**  
 When multiple users update an asset model at the same time, an user's changes may be inadvertently overwritten by another user. To prevent this, you must define a conditional update request. See [Optimistic locking for asset model writes](opt-locking-for-model.md). 

# Update custom composite models (components)


You can use the AWS IoT SiteWise API to update a custom composite model, or the AWS IoT SiteWise console to update components.

**Topics**
+ [

## Update a component (console)
](#update-custom-composite-model-console)
+ [

## Update a custom composite model (AWS CLI)
](#update-custom-composite-model-cli)

## Update a component (console)


You can use the AWS IoT SiteWise console to update a component.

**To update a component (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-models"></a>In the navigation pane, choose **Models**.

1. Choose the asset model where the component is.

1. On the **Properties** tab, choose **Components**.

1. Choose the component that you want to update.

1. Choose **Edit**.

1. On the **Edit component** page, do any of the following:
   + In **Model details**, change the **Name** of the model.
   + Change any of the **Attribute definitions**. You can't change the **Data type** of existing attributes. For more information, see [Define static data (attributes)](attributes.md).
   + Change any of the **Measurement definitions**. You can't change the **Data type** of existing measurements. For more information, see [Define data streams from equipment (measurements)](measurements.md).
   + Change any of the **Transform definitions**. For more information, see [Transform data (transforms)](transforms.md).
   + Change any of the **Metric definitions**. You can't change the **Time interval** of existing metrics. For more information, see [Aggregate data from properties and other assets (metrics)](metrics.md).

1. Choose **Save**.

## Update a custom composite model (AWS CLI)


Use the AWS Command Line Interface (AWS CLI) to update a custom composite model.

To update the name or description, use the [UpdateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModelCompositeModel.html) operation. For inline custom composite models only, you can also update the properties. You can't update the properties of a component-model-based custom composite model, because its referenced component model provides its associated properties.

**Important**  
If you remove a property from a custom composite model, AWS IoT SiteWise deletes all previous data for that property. You can’t change the type or data type of an existing property.  
To replace an existing composite model property with a new one with the same `name`, do the following:  
Submit an `UpdateAssetModelCompositeModel` request with the entire existing property removed.
Submit a second `UpdateAssetModelCompositeModel` request that includes the new property. The new asset property will have the same `name` as the previous one and AWS IoT SiteWise will generate a new unique `id`.

**To update a custom composite model (AWS CLI)**

1. To retrieve the existing composite model definition, run the following command. Replace *composite-model-id* with the ID or the external ID of the custom composite model to update, and *asset-model-id* with the asset model that the custom composite model is associated with. For more information, see the *AWS IoT SiteWise User Guide*.

   1. Run the command below:

      ```
      aws iotsitewise describe-asset-model-composite-model \
      --asset-model-composite-model-id composite-model-id \
      --asset-model-id asset-model-id
      ```

   1.  The above command returns the composite model definition corresponding to associated model’s latest version. For an use case where an asset model is in a `FAILED` state, retrieve the valid model definition corresponding to its active version to build your update request. See [Asset model versions](model-active-version.md) for details. 

   1. Run the following command to retrieve the active model definition:

      ```
      aws iotsitewise describe-asset-model-composite-model \
      --asset-model-composite-model-id composite-model-id \
      --asset-model-id asset-model-id \
      --asset-model-version ACTIVE
      ```

   1. For more information, see the [DescribeAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModelCompositeModel.html) operation.

1. Create a file called `update-custom-composite-model.json`, and then copy the previous command's response into the file.

1. Remove every key-value pair from the JSON object in `update-custom-composite-model.json` except for the following fields:
   + `assetModelCompositeModelName`
   + `assetModelCompositeModelDescription` (if present)
   + `assetModelCompositeModelProperties` (if present)

1. In `update-custom-composite-model.json`, do any of the following:
   + Change the value of `assetModelCompositeModelName`.
   + Add or remove `assetModelCompositeModelDescription`, or change its value.
   + For inline custom composite models only: Change, add, or remove any of the asset model's properties in `assetModelCompositeModelProperties`.

   For more information about the required format for this file, see the request syntax for [UpdateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModelCompositeModel.html).

1. Run the following command to update the custom composite model with the definition stored in `update-custom-composite-model.json`. Replace *composite-model-id* with the ID of the composite model, and *asset-model-id* with the ID of the asset model it's in.

   ```
   aws iotsitewise update-asset-model-composite-model \
   --asset-model-composite-model-id composite-model-id \
   --asset-model-id asset-model-id \
   --cli-input-json file://update-custom-composite-model.json
   ```

**Important**  
 When multiple users update an asset model at the same time, an user's changes may be inadvertently overwritten by another user. To prevent this, you must define a conditional update request. See [Optimistic locking for asset model writes](opt-locking-for-model.md). 

# Optimistic locking for asset model writes


 When updating an asset model, an user does the following: 

1. Read the current asset model definition.

1. Edit the asset model definition with required changes.

1. Update asset model with the new definition.

 In a scenario with two users updating a model, the following is possible: 
+ User A reads the asset model X definition.
+ User B reads the asset model X definition and commits changes, modifying the definition of X.
+ User A commits and overwrites the change made by user B for asset model X, without verifying or incorporating User B's changes.

 Optimistic locking is a mechanism used by AWS IoT SiteWise to prevent accidental overwrites like the scenario above. Optimistic locking is a strategy to ensure the current version of asset model being updated or deleted, is the same as its current version in AWS IoT SiteWise. This protects asset model writes from being overwritten by accidental updates. 

Follow these steps to perform asset model writes with optimistic locking:

**Topics**
+ [

## Performing asset model writes with optimistic lock (console)
](#opt-locking-for-model-console)
+ [

## Performing asset model writes with optimistic lock (AWS CLI)
](#opt-locking-for-model-cli)

## Performing asset model writes with optimistic lock (console)


The procedure below describes how to perform asset model writes with an optimistic lock on the asset model's active version in the 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-models"></a>In the navigation pane, choose **Models**.

1. Choose the asset model or component model to update.

1. Choose **Edit**.

1. Make changes on the **Edit model** page.

1. Choose **Save**.
**Note**  
Sometimes, one or more successful model updates have happened between when the user starts editing the model, and saves the made edits to the model.  
To ensure the user does not accidentally overwrite over new successful updates, the user's write is rejected. The console disables the **Save** button, and prompts the user to refresh the **Edit model** page. The user must update the new active version of the model again. The user must perform the following additional steps: 

1. Choose **Refresh**.

1. Follow steps 5 and 6 again.

## Performing asset model writes with optimistic lock (AWS CLI)


The procedure below describes how to perform asset model writes with optimistic locking in the AWS CLI.

1. **Fetch the ETag associated with current model definition**

    `ETag` is a unique token generated for each new representation of an asset model. Call [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) API to fetch the current asset model definition, and associated `ETag` from the response. 

    During concurrent updates, users perform either successful updates (model in `ACTIVE` state), or unsuccessful updates (model in `FAILED` state). To ensure that an user does not accidentally overwrite a successful update, you must retrieve the active version of the asset model from [Asset model versions](model-active-version.md), and get the `ETag` value. 

   Run the following command:

   ```
   aws iotsitewise describe-asset-model --asset-model-id asset-model-id \
   --asset-model-version ACTIVE
   ```

    The response returns the following structure: 

   ```
   {
     "assetModelId": "String",
     "assetModelArn": "String",
     "assetModelName": "String",
     ...
     "eTag": "String"
   }
   ```
**Note**  
 You must retrieve the latest version of the asset model and its `ETag` in order to not overwrite any updates. 

1. **Perform UPDATE and DELETE operations with write conditions**

   The following asset model APIs support optimistic locking:
   + [UpdateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModel.html)
   + [DeleteAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DeleteAssetModel.html)
   + [CreateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModelCompositeModel.html)
   + [UpdateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModelCompositeModel.html)
   + [DeleteAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DeleteAssetModelCompositeModel.html)
**Note**  
 The below scenarios use `UpdateAssetModel` API as a reference. The conditions apply to all the operations listed above. 

   The below scenarios describe the different write conditions depending on concurrency control requirements:
   +  Run the following command in order not to overwrite any successful updates. A new active version must not exist, since the last read active version. Replace `e-tag` with the `ETag` returned in the API operation used in the read of the active version. 

     ```
     aws iotsitewise update-asset-model \
       --asset-model-id asset-model-id \
       --if-match e-tag \
       --match-for-version-type ACTIVE \
       --cli-input-json file://model-payload.json
     ```
   +  When a model creation fails, an active version does not exist for it yet, because it's in a `FAILED` state. It is still possible to overwrite a new active version that is present, before your changes are committed. Run the following command to not overwrite a new active version, when an active version does not exist during your last read.

     ```
     aws iotsitewise update-asset-model \
       --asset-model-id asset-model-id \
       --if-none-match "*" \
       --match-for-version-type ACTIVE \
       --cli-input-json file://model-payload.json
     ```
   +  Run the following command to avoid overwriting any successful or unsuccessful updates. This command defines a write condition which ensures that a latest version is not created since your last read latest version. Replace `e-tag` with the `ETag` returned in the API operation used in the read of the active version.

     ```
     aws iotsitewise update-asset-model \
       --asset-model-id asset-model-id \
       --if-match eTag \
       --match-for-version-type LATEST \
       --cli-input-json file://model-payload.json
     ```

     If the write condition evaluates to `FALSE`, the write request fails with the `PreconditionFailedException`.