How to connect my document files?

This article describes how to connect your documents into TwinMaker model.

Prerequisites

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

1. An AWS Account and the necessary permissions to use 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. An AWS IoT 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. An AWS Iot 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 intends to associate document links with TwinMaker models. These documents will be utilized by our operators for reference."

Assuming you have already created the Equipment entity named "Equipment1" and its child machine element entity named "Element1," please refer to the guide How to create my factory and equipment in TwinMaker? if you haven't created them yet.

TwinMaker offers a first-party component that simplifies the process of including documents within TwinMaker. This component enables you to map document titles to URLs, allowing you to provide access to documents containing relevant information about a specific entity.

AWS Console

In this section, we will create an Entity Component in the AWS Console to store time series data.

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

Step 2: Choose one of your Entities. For this example, let's use the "Element1" Entity that we created in the guide How to create my factory and equipment in TwinMaker?. Once you have selected the entity, click on the "Add component" button.

Step 3: On the "Component information" page, input the following details:

• Name field: Enter "Element_Document"
• Type drop-down list: Select "com.amazon.iottwinmaker.documents"

Upon selecting the component type, the page will refresh and display the related fields for the Document component.

In Document editor:

• Name field: Fill in "Equipment_Manual" or any desired value.
• External URL field: Enter "http://mocklink.com/" or the actual URL of the document you want to associate. Please note that this field only accepts URL format values.

Step 4. (Optional) Click "Add another document" button to add more document links to the component.

Step 5. Click "Add component" button to save the component. The component will be save to the entity. The component json will look like:

{
  "documents": {
    "definition": {
      "dataType": {
        "type": "MAP",
        "nestedType": {
          "type": "STRING"
        }
      },
      "isTimeSeries": false,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": false,
      "isImported": false,
      "isFinal": false,
      "isInherited": false
    },
    "value": {
      "mapValue": {
        "Equipment_ Manual": {
          "stringValue": "http://MockLink.com"
        }
      }
    }
  }
}

AWS CLI

The lifecycle of a component is tied to the TwinMaker entity it belongs to. Therefore, you can utilize entity-related CLI commands to manage your components. To add a component to an existing entity, you can use the AWS TwinMaker update-entity command.

In the example provided, we are using the CookieFactoryV2 workspace as a reference TwinMaker workspace. If you are using your own workspace please replace it with the ID of your own workspace. Similarly, ensure to replace the entity ID in the command with the ID of the specific entity you want to attach the component to.

aws iottwinmaker update-entity --workspace-id CookieFactoryV2 --entity-id <YourTargetEntityID> --component-updates '{
   "Element_Document": {
      "updateType": "CREATE",
      "description": "",
      "componentTypeId": "com.amazon.iottwinmaker.documents",
      "propertyUpdates": {
         "documents": {
            "definition": {
               "dataType": {
                  "type": "MAP",
                  "nestedType": {
                     "type": "STRING"
                  }
               }
            },
            "value": {
               "mapValue": {
                  "Equipment_ Manual": {
                     "stringValue": "http://MockLink.com"
                  }
               }
            }
         }
      }
   }
}'

Clean up

AWS Console

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

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

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

Step 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.  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 '{
   "Element_Document": {
      "updateType": "DELETE"
   }
}'