How to add additional properties to my asset twin? - johnnyw-aws/aws-iot-twinmaker-samples GitHub Wiki

Prerequisites

To work with AWS IoT TwinMaker in this tutorial, you will need the following prerequisites:

1. An AWS Account and the necessary permissions to use AWS IoT TwinMaker. If you already have an AWS IoT TwinMaker set up, you can proceed to the next section. Otherwise, follow the instructions to set up an account and configure authentication. The instructions will guide you through the necessary steps to ensure successful completion.
2. A TwinMaker workspace. If you already have an AWS IoT TwinMaker workspace set up, you can proceed to the next section. Otherwise, follow the instructions to create one.
3. A TwinMaker Entity. If you already have an AWS IoT TwinMaker Entity set up, you can proceed to the next section. Otherwise, follow the instructions to create one.

Developer tools

This article highlights how to complete different management operations using the AWS IoT TwinMaker Console. You can also craft these same management calls using the other tools like AWS CLI

• AWS IoT TwinMaker Console: A web-based interface that offers a visual representation of your IoT TwinMaker data, enabling you to manage models and build workflows.
• AWS Command Line Interface (CLI): Provides a command-line interface to interact with and manage your IoT TwinMaker data using CLI commands.

By leveraging these developer tools and interfaces, you can effectively manage models within your AWS IoT TwinMaker, enabling seamless integration and orchestration of your IoT devices and services.

Goals

"My company is seeking to update the existing component type in our AWS IoT TwinMaker solution. The current component type has become outdated, and we need to add a new property to enhance its functionality."

AWS Console

Add a new property to an existing component type

Before adding a new property to an existing component type, you need to remove any existing instantiation of this component type. This scenario addresses the use case that a new property (e.g. sensor reading) has come online from the same data source associated with this component type.

Step1: Select “View component details” under “Actions”. Step2: Select “Delete” on the upper right corner on the component information page. Confirm delete when asked. Step3: Go to “Component types” page and select component type “com.example.cookiefactory.watertank”. Step 4: Select “Edit” on the top right corner. Add new property “valvePosition” to the component type as the new property. Step5: Click “Save” and you will see a message banner that component is updated successfully. Step6: Go to Entities page and select WaterTank entity. Click “Associated entities” tab to get EntityId for WaterTank which is required to add updated component. Step7: Click on “Add component” to add updated component type for WaterTank so the new property will be added for this entity. Select “com.example.cookiefactory.watertank” as the component type, paste EntityId for WaterTank in the “telemetryAssetid” field, and add component type name “WaterTank” as the “telemetryAssetType”. The newly added property “valvePosition” is already here. Step8: Now, you have successfully added a new property “valvePosition” to WaterTank entity. Before using the new property, please ensure the data connector for this component handles the new data stream that connected to the property so data will start flow to the entity.

AWS CLI

• Remove existing component from Entities

You can use AWS TwinMaker update-entity to delete the component from Entity.  Here we are using CookieFactoryV2 workspace as the example TwinMaker workspace, you could replace it into your own workspace Id.

aws iottwinmaker update-entity --workspace-id CookieFactoryV2 --entity-id <YourTargetEntityID> --component-updates '{
   "WaterTank": {
      "updateType": "DELETE"
   }
}'

• Update component type

You can use AWS TwinMaker update-component-type to update your component type.

aws iottwinmaker update-component-type --workspace-id CookieFactoryV2 --component-type-id com.example.cookiefactory.watertank --property-definitions '{
        "flowRate1": {
            "dataType": {
                "type": "DOUBLE"
            },
            "isExternalId": false,
            "isRequiredInEntity": false,
            "isStoredExternally": true,
            "isTimeSeries": true
        },
        "flowrate2": {
            "dataType": {
                "type": "DOUBLE"
            },
            "isExternalId": false,
            "isRequiredInEntity": false,
            "isStoredExternally": true,
            "isTimeSeries": true
        },
        "tankVolume1": {
            "dataType": {
                "type": "DOUBLE"
            },
            "isExternalId": false,
            "isRequiredInEntity": false,
            "isStoredExternally": true,
            "isTimeSeries": true
        },
        "tankVolume2": {
            "dataType": {
                "type": "DOUBLE"
            },
            "isExternalId": false,
            "isRequiredInEntity": false,
            "isStoredExternally": true,
            "isTimeSeries": true
        },
        "telemetryAssetId": {
            "dataType": {
                "type": "STRING"
            },
            "isExternalId": true,
            "isRequiredInEntity": true,
            "isStoredExternally": false,
            "isTimeSeries": false
        },
        "telemetryAssetType": {
            "dataType": {
                "type": "STRING"
            },
            "isExternalId": false,
            "isRequiredInEntity": true,
            "isStoredExternally": false,
            "isTimeSeries": false
        },
        "valvePosition": {
            "dataType": {
                "type": "DOUBLE"
            },
            "isExternalId": false,
            "isRequiredInEntity": false,
            "isStoredExternally": true,
            "isTimeSeries": true
        }
    }'

Goals

"My company is seeking to add one more property on our existing Entity."

AWS Console

Add a new static key-value pair property

In this example, you can add new property that is static key-value pair into an existing entity.

Step 1: Go to Entities page, select the entity and component that you want to add the new property. Watertank entity is selected in this example. Step 2: See “Add component” button at top right of the screen. "Add component" modal will pop up, add name and select "com.amazon.iottwinmaker.parameters" component type.

Step 3: Click on “Add property” to add the new property “manufacturer” to capture the new key-value pair property for WaterTank entity. Step 4: Click on “Add component” to complete the action. You will see new component “manufacturer_info” state transition from “CREATING” to “ACTIVE”.

AWS CLI

You can use AWS TwinMaker update-entity to add your component.

For examples of how to create a parameter component, please refer to this cli example.

You can also use AWS TwinMaker update-entity to update your component. Here is an example

aws iottwinmaker update-entity --workspace-id CookieFactoryV2 --entity-id <YourTargetEntityID > --component-updates '{
        "manufacturer_info": {
            "updateType": "UPDATE",
            "description": "",
            "propertyUpdates": {
                "<Target Key Name>": {
                    "value": {
                        "stringValue": "<Target Value Name>"
                    },
                    "definition": {
                        "dataType": {
                            "type": "STRING"
                        },
                        "isExternalId": false,
                        "isRequiredInEntity": true,
                        "isStoredExternally": false,
                        "isTimeSeries": false
                    },
                    "updateType": "CREATE"
                }
            },
            "componentTypeId": "com.amazon.iottwinmaker.parameters"
        }
}'

Clean up

If you would like to delete the component from your entity, please follow the steps below:

AWS Console

1. Log into your AWS account Console and select the workspace that you own.

2. In the left navigation tree, locate and select the entity your component belongs to. Then select the target component on the right page.

3. Click "Actions" dropdown list on the top right, select "View component details" button.

4. On the component detail page, click on the "Delete" button located at the top right corner to remove the component from Entity.

AWS CLI

You can use AWS TwinMaker update-entity to delete the component from Entity. 

In your terminal type the following command:

aws iottwinmaker update-entity --workspace-id CookieFactoryV2 --entity-id <YourTargetEntityID> --component-updates '{
   "<Your Target Component Name>": {
      "updateType": "DELETE"
   }
}'

In the above example, we are using CookieFactoryV2 workspace as the example TwinMaker workspace, you could replace the workspace Id `CookieFactoryV21 with your own workspace Id.