# Asset synchronization with AWS IoT SiteWise AWS IoT TwinMaker supports asset synchronization (asset sync) for your AWS IoT SiteWise assets and asset models. Using the AWS IoT SiteWise component type, asset sync takes existing AWS IoT SiteWise assets and asset models and converts these resources into AWS IoT TwinMaker entities, components, and component types. The following sections walk you through how to configure asset sync and which AWS IoT SiteWise assets and asset models can be synced to your AWS IoT TwinMaker workspace. **Topics** + [ # Using asset sync with AWS IoT SiteWise ](tm-sw-asset-sync-use.md) + [ # Differences between custom and default workspaces ](tm-sw-default-ws-diffs.md) + [ # Resources synced from AWS IoT SiteWise ](tm-sw-asset-sync-map.md) + [ # Analyze sync status and errors ](tm-sw-asset-sync-ts.md) + [ # Delete a sync job ](tm-sw-asset-sync-delete.md) + [ # Asset sync limits ](tm-sw-asset-sync-limits.md) # Using asset sync with AWS IoT SiteWise This topic shows you how to turn on and configure AWS IoT SiteWise asset sync. Follow the appropriate procedures based on which type of workspace you're using. **Important** See [Differences between custom and default workspaces](tm-sw-default-ws-diffs.md) for information about the differences between the custom and default workspaces. **Topics** + [ # Using a custom workspace ](tm-sw-custom-ws.md) + [ # Using the IoTSiteWiseDefaultWorkspace ](tm-sw-default-ws.md) # Using a custom workspace Review these prerequisites before turning on asset sync. ## Prerequisites Before using AWS IoT SiteWise, the following must be completed: + You have an AWS IoT TwinMaker workspace. + You have assets and asset models in AWS IoT SiteWise. For more information, see [Creating asset models](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/create-asset-models.html). + An existing IAM role with read permissions for the following AWS IoT SiteWise actions: + `ListAssets` + `ListAssetModels` + `DescribeAsset` + `DescribeAssetModel` + The IAM role must have the following write permissions for AWS IoT TwinMaker: + `CreateEntity` + `UpdateEntity` + `DeleteEntity` + `CreateComponentType` + `UpdateComponentType` + `DeleteComponentType` + `ListEntities` + `GetEntity` + `ListComponentTypes` Use the following IAM role as a template for the required role: ``` // trust relationships { { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "iottwinmaker.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } // permissions - replace ACCOUNT_ID, REGION, WORKSPACE_ID with actual values { "Version": "2012-10-17", "Statement": [{ "Sid": "SiteWiseAssetReadAccess", "Effect": "Allow", "Action": [ "iotsitewise:DescribeAsset" ], "Resource": [ "arn:aws:iotsitewise:REGION:ACCOUNT_ID:asset/*" ] }, { "Sid": "SiteWiseAssetModelReadAccess", "Effect": "Allow", "Action": [ "iotsitewise:DescribeAssetModel" ], "Resource": [ "arn:aws:iotsitewise:REGION:ACCOUNT_ID:asset-model/*" ] }, { "Sid": "SiteWiseAssetModelAndAssetListAccess", "Effect": "Allow", "Action": [ "iotsitewise:ListAssets", "iotsitewise:ListAssetModels" ], "Resource": [ "*" ] }, { "Sid": "TwinMakerAccess", "Effect": "Allow", "Action": [ "iottwinmaker:GetEntity", "iottwinmaker:CreateEntity", "iottwinmaker:UpdateEntity", "iottwinmaker:DeleteEntity", "iottwinmaker:ListEntities", "iottwinmaker:GetComponentType", "iottwinmaker:CreateComponentType", "iottwinmaker:UpdateComponentType", "iottwinmaker:DeleteComponentType", "iottwinmaker:ListComponentTypes" ], "Resource": [ "arn:aws:iottwinmaker:REGION:ACCOUNT_ID:workspace/WORKSPACE_ID", "arn:aws:iottwinmaker:REGION:ACCOUNT_ID:workspace/WORKSPACE_ID/*" ] } ] } ``` Use the following procedure to turn on and configure AWS IoT SiteWise asset sync. 1. In the [AWS IoT TwinMaker console](https://console.aws.amazon.com/iottwinmaker/), navigate to the **Settings** page. 1. Open the **Model sources** tab. ![\[The AWS IoT TwinMaker console Setting page with the Model sources tab open.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/asset-sync-settings.png) 1. Choose **Connect workspace** to link your AWS IoT TwinMaker workspace to your AWS IoT SiteWise assets. **Note** You can only use asset sync with a single AWS IoT TwinMaker workspace. You must disconnect the sync from one workspace and connect to another workspace to if you wish to sync in a different workspace. 1. Next, navigate to the workspace in which you want to use asset sync. 1. Choose **Add sources**. This opens the **Add entity model source** page. ![\[The Add entity model source page.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/add-model-source.png) 1. On the **Add entity model source** page, confirm that the source field displays **AWS IoT SiteWise**. Select the IAM role you created as a prerequisite for the **IAM role**. 1. You have now turned on AWS IoT SiteWise asset sync. You should see a conformation banner appear at the top of the selected **Workspace** page confirming that asset sync is active. You should also now see a sync source listed in the **Entity model sources** section. ![\[The workspace page showing the list of Entity model sources.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/success-sync.png) # Using the IoTSiteWiseDefaultWorkspace When you opt in to the [AWS IoT SiteWiseAWS IoT TwinMaker integration](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/integrate-tm.html), a default workspace named `IoTSiteWiseDefaultWorkspace` is created and automatically synced with AWS IoT SiteWise. You can also use the AWS IoT TwinMaker `CreateWorkspace` API to create a workspace named `IoTSiteWiseDefaultWorkspace`. ## Prerequisites Before creating `IoTSiteWiseDefaultWorkspace`, make sure you have done the following: + Create an AWS IoT TwinMaker service-linked role. See [Using service-linked roles for AWS IoT TwinMaker](using-service-linked-roles.md) for more information. + Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). Review the role or user and verify that it has permission to `iotsitewise:EnableSiteWiseIntegration`. If needed, add permission to the role or user: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iotsitewise:EnableSiteWiseIntegration", "Resource": "*" } ] } ``` ------ # Differences between custom and default workspaces **Important** New AWS IoT SiteWise features, such as [https://docs.aws.amazon.com//iot-sitewise/latest/userguide/custom-composite-models.html](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/custom-composite-models.html), are only available in `IoTSiteWiseDefaultWorkspace`. We encourage you to use a default workspace instead of custom workspace. When using the `IoTSiteWiseDefaultWorkspace`, there are a few notable differences from using a custom workspace with asset sync. + When you create a default workspace, the Amazon S3 location and IAM role are optional. **Note** You can use `UpdateWorkspace` to provide the Amazon S3 location and IAM role. + The `IoTSiteWiseDefaultWorkspace` doesn't have a resource count limit to sync AWS IoT SiteWise resources to AWS IoT TwinMaker. + When you sync resources from AWS IoT SiteWise, their `SyncSource` will be `SITEWISE_MANAGED`. This includes `Entities` and `ComponentTypes`. + New AWS IoT SiteWise features, such as `CompositionModel` are only available in the `IoTSiteWiseDefaultWorkspace`. There are a few limitations specific to `IoTSiteWiseDefaultWorkspace`, they are: + The default workspace can't be deleted. + To delete resources, you must delete the AWS IoT SiteWise resources first, then the corresponding resources in AWS IoT TwinMaker are deleted. # Resources synced from AWS IoT SiteWise This topic lists which assets you can sync from AWS IoT SiteWise to your AWS IoT TwinMaker workspace. **Important** See [Differences between custom and default workspaces](tm-sw-default-ws-diffs.md) for information about the differences between the custom and default workspaces. ## Custom and default workspaces The following resources are synced and available in **both** custom and default workspaces: **Asset Models** AWS IoT TwinMaker creates a new component type for each asset model in AWS IoT SiteWise. + The component `TypeId` for the asset model will use one of the following patterns: + **Custom workspace - ** `iotsitewise.assetmodel:assetModelId` + **Default workspace -** `assetModelId` + Each property in the asset model is a new property in the component type, with one of the following naming patterns: + **Custom workspace - ** `Property_propertyId` + **Default workspace - ** `propertyId` The property name in AWS IoT SiteWise is stored as the `displayName` in the property definition. + Each hierarchy in the asset model is a new property of type `LIST` and the `nestedType` is `RELATIONSHIP` in the component type. The hierarchy is mapped to the property with a name prefixed by one of the following: + **Custom workspace - ** `Hierarchy_hierarchyId` + **Default workspace - ** `hierarchyId` **Asset** AWS IoT TwinMaker creates a new entity for each asset in AWS IoT SiteWise. + The `entityId` is the same as the `assetId` in AWS IoT SiteWise. + These entities have a single component called `sitewiseBase`, which has the component type corresponding to the asset model for this asset. + Any asset level overrides, such as setting property alias or unit of measure, are reflected in the entity in AWS IoT TwinMaker. ## Default workspace only The following assets are synced and **available in the default workspace only**, `IoTSiteWiseDefaultWorkspace`. **AssetModelComponents** AWS IoT TwinMaker creates a new component type for each `AssetModelComponents` in AWS IoT SiteWise. + The component `TypeId` for the asset model uses the following pattern: `assetModelId`. + Each property in the asset model is a new property in the component type, with the property name as `propertyId`. The property name in AWS IoT SiteWise is stored as the `displayName` in the property definition. + Each hierarchy in the asset model is a new property of type `LIST` and the `nestedType` is `RELATIONSHIP` in the component type. The hierarchy is mapped to the property with a name prefixed by `hierarchyId`. **AssetModelCompositeModel** AWS IoT TwinMaker creates a new component type for each `AssetModelCompositeModel` in AWS IoT SiteWise. + The component `TypeId` for the asset model uses the following pattern: `assetModelId_assetModelCompositeModelId`. + Each property in the asset model is a new property in the component type, with the property name as `propertyId`. The property name in AWS IoT SiteWise is stored as the `displayName` in the property definition. **AssetCompositeModels** AWS IoT TwinMaker creates a new composite component for each `AssetCompositeModel` in AWS IoT SiteWise. + The `componentName` is the same as the `assetModelCompositeModelId` in AWS IoT SiteWise. ## Resources not synced The following resources are not synced: **Non-synced assets and asset models** + Alarm models will be synced as compositeModels, but corresponding data in the asset related to alarms are not synced. + [AWS IoT SiteWise data streams](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/manage-data-streams.html) are not synced. Only properties modeled in the asset model are synced. + Property values for attributes, measurements, transforms, aggregates, and metadata calculation such as formula and window are not synced. Only the metadata about the properties, such as alias, unit of measure, and data type are synced. The values can be queried using the regular AWS IoT TwinMaker data connector API, [ GetPropertyValueHistory](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetPropertyValueHistory.html). ## Use synced entities and component types in AWS IoT TwinMaker Once assets are synced from AWS IoT SiteWise, the synced component types are read only in AWS IoT TwinMaker. Any update or delete action must be done in AWS IoT SiteWise, and those changes are synced to AWS IoT TwinMaker if the syncJob is still active. The synced entities and the AWS IoT SiteWise base component are also read only in AWS IoT TwinMaker. You can add additional non-synced components to the synced entity, as long as no entity-level attributes such as the description or `entityName` are updated. Some restrictions apply to how you can interact with synced entities. You can't create child entities under a synced entity in the synced entity's hierarchy. Additionally, you can't create non-synced component types that extend from a synced component type. **Note** Additional components are deleted along with the entity if the asset is deleted in AWS IoT SiteWise or if you delete the sync job. You can use these synced entities in Grafana dashboards and add them as tags in the scene composer like regular entities. You can also issue knowledge graph queries for these synced entities. **Note** Synced entities without modification are not charged, but you are charged for those entities if changes have been made in AWS IoT TwinMaker. For example, if you add a non-synced component to a synced entity, that entity is now charged in AWS IoT TwinMaker. For more information, see [AWS IoT TwinMaker Pricing](https://aws.amazon.com//iot-twinmaker/pricing/). # Analyze sync status and errors This topic provides guidance on how to analyze sync errors and statuses. **Important** See [Differences between custom and default workspaces](tm-sw-default-ws-diffs.md) for information about the differences between the custom and default workspaces. ## Sync job statuses A sync job has one of the following statuses depending on its state. + The sync job `CREATING` state means the job is checking for permissions and loading data from AWS IoT SiteWise to prepare the sync. + The sync job `INITIALIZING` state means all the existing resources in AWS IoT SiteWise are synced to AWS IoT TwinMaker. This step can take longer to complete if the user has a large number of assets and asset models in AWS IoT SiteWise. You can monitor the number of resources that have been synced by checking on the sync job in the [AWS IoT TwinMaker console](https://console.aws.amazon.com/iottwinmaker/), or by calling the `ListSyncResources` API. + The sync job `ACTIVE` state means the initialization step is done. The job is now ready to sync any new updates from AWS IoT SiteWise. + The sync job `ERROR` state indicates an error with any of the preceding states. Review the error message. There may be an issue with the IAM role setup. If you want to use a new IAM role, delete the sync job that had the error and create a new one with the new role. Sync errors appear in the model source page, which is accessed from the **Entity model sources** table in your workspace. The model source page displays a list of resources that failed to sync. Most errors are automatically retried by the sync job, but if the resource requires an action, then it remains in the `ERROR` state. You can also obtain a list of errors by using the [ ListSyncResources](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ListSyncResources.html) API. To see all the listed errors for the current source, use the following procedure. 1. Navigate to your workspace in the [AWS IoT TwinMaker console](https://console.aws.amazon.com/iottwinmaker/). 1. Select the AWS IoT SiteWise source listed in the **Entity model sources** modal to open the asset sync details page. ![\[The AWS IoT SiteWise source page shows asset sync details, including errors.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/synced-resources.png) 1. As shown in the preceding screenshot, any resources with persisting errors are listed in the **Errors ** table. You can use this table to track down and fix errors related to specific resources. Possible errors include the following: + While AWS IoT SiteWise supports duplicate asset names, AWS IoT TwinMaker only supports them at the `ROOT` level, not under the same parent entity. If you have two assets with the same name under a parent entity in AWS IoT SiteWise, one of them fails to sync. To fix this error, either delete one of the assets or move one under a different parent asset in AWS IoT SiteWise before you sync. + If you already have an entity with the same ID as the AWS IoT SiteWise asset ID, that asset fails to sync until you delete the existing entity. # Delete a sync job Use the following procedure to delete a sync job. **Important** See [Differences between custom and default workspaces](tm-sw-default-ws-diffs.md) for information about the differences between the custom and default workspaces. 1. Navigate to the [AWS IoT TwinMaker console](https://console.aws.amazon.com/iottwinmaker/). 1. Open the workspace from which you wish to delete the sync job. 1. Under **Entity model sources**, select the AWS IoT SiteWise source to open the source details page. 1. To stop the sync job, choose **Disconnect**. Confirm your choice to fully delete the sync job. ![\[The Disconnect AWS IoT SiteWise sync dialog box has buttons to Cancel or Disconnect the sync job.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/confirm-delete.png) Once a sync job is deleted, you can create the sync job again in the same or a different workspace. You can't delete a workspace if there are any sync jobs in that workspace. Delete the sync jobs first before deleting a workspace. If there are any errors during the deletion of the sync job, the sync job remains in the `DELETING` state and is automatically retried. You can now manually delete any of the synced entities or component types if there is any error related to deleting a resource. **Note** Any resources that were synced from AWS IoT SiteWise are deleted first, then the sync job itself is deleted. # Asset sync limits **Important** See [Differences between custom and default workspaces](tm-sw-default-ws-diffs.md) for information about the differences between the custom and default workspaces. Because the [AWS IoT SiteWise quotas](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/quotas.html) are higher than the default [AWS IoT TwinMaker quotas](https://docs.aws.amazon.com//general/latest/gr/iot-twinmaker.html), we are increasing the following limits for entities and component types synced from AWS IoT SiteWise. + 1000 synced component types in a workspace, since it can only sync 1000 asset models from AWS IoT SiteWise. + 100,000 synced entities in a workspace, since it can only sync 100,000 assets from AWS IoT SiteWise. + 2000 maximum child entities per parent entity. It syncs 2000 child assets per single parent asset. **Note** The [GetEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetEntity.html) API only returns the first 50 child entities for a hierarchy property, but you can use the [GetPropertyValue](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetPropertyValue.html) API to paginate and retrieve the list of all child entities. + 600 properties per synced component from AWS IoT SiteWise, which can sync asset models with 600 total properties and hierarchies. **Note** These limits are only applicable for the synced entities. Request a quota increase if you need these limits increased for non-synced resources.