Update asset models and component models - AWS IoT SiteWise
Updating an asset or component model (console)Update an asset or component model (AWS CLI)

Update asset models and component models

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

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 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.

Updating an asset or component model (console)

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

To update an asset model or component model (console)

  1. Navigate to the AWS IoT SiteWise console.

  2. In the navigation pane, choose Models.

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

  4. Choose Edit.

  5. On the Edit model page, do any of the following:

  6. 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 for more details.

Update an asset or component model (AWS CLI)

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

Use the UpdateAssetModel API to update the name, description, and properties of an asset model or component model. For asset models only, you can update 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 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.

Warning

The UpdateAssetModel 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 operation.

Note

The following procedure can only update composite models of type AWS/ALARM. If you want to update CUSTOM composite models, use UpdateAssetModelCompositeModel instead. For more information, see Update custom composite models (components).

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 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 operation.

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

  3. 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 operation expects a payload with the following structure:

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

  4. 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.

    • 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.

    • 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 and Define alarms on asset models.

  5. 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.