Step 1. Define the entities Step 2. Upload the entity definitions Step 3. Associate devices with things

Creating and uploading entities

Creating entities for a flow involves three main tasks:

Defining the entities (including the devices) in the flow.
Uploading the entities to your private namespace.
Associating things in your registry with the devices that you've defined and uploaded.

This topic describes how to complete these tasks by using either the AWS CLI or the AWS IoT Things Graph console.

Step 1. Define the entities

The following GraphQL contains a complete definition of entities that compose the flow described in Working with flows. (For an overview of how GraphQL is used in the Things Graph Data Model (TDM), see AWS IoT Things Graph data model and GraphQL.

These definitions create a barcode reader and another device that does something with the reader output, with all of the TDM entities that compose the devices.

Note

Before uploading your models, you must wrap all of your definitions between opening and closing curly braces, as in the following example.



{
  # Basic type definitions
  type
  String @propertyType(id: "urn:tdm:REGION/ACCOUNT ID/default:property:String", dataType: String) {
    IGNORE: VOID
  }

  type
  Boolean @propertyType(id: "urn:tdm:REGION/ACCOUNT ID/default:property:Boolean", dataType: Boolean) {
    IGNORE: VOID
  }

  # Complex Type (State) definitions
  type
  BarcodeType @stateType(id: "urn:tdm:REGION/ACCOUNT ID/default:state:BarcodeType") {
    id: Property @property(id: "urn:tdm:REGION/ACCOUNT ID/default:property:String")
  }

  type
  Barcode @propertyType(id: "urn:tdm:REGION/ACCOUNT ID/default:property:Barcode", instanceOf: "urn:tdm:REGION/ACCOUNT ID/default:state:BarcodeType") {
    IGNORE: VOID
  }

  # Action definitions
  type
  DeviceA_ReadBarcode @actionType(id: "urn:tdm:REGION/ACCOUNT ID/default:action:DeviceA_ReadBarcode") {
    return: Property @property(id: "urn:tdm:REGION/ACCOUNT ID/default:property:Barcode")
  }

  type
  DeviceB_Action @actionType(id: "urn:tdm:REGION/ACCOUNT ID/default:action:DeviceB_Action") {
    input: Property @property(id: "urn:tdm:REGION/ACCOUNT ID/default:property:Barcode")
  }

  # Capability definitions
  type
  DeviceA @capabilityType(id: "urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceA") {
    readBarcode: Action @action(id: "urn:tdm:REGION/ACCOUNT ID/default:action:DeviceA_ReadBarcode")
  }

  type
  DeviceB @capabilityType(id: "urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceB") {
    doSomething: Action @action(id: "urn:tdm:REGION/ACCOUNT ID/default:action:DeviceB_Action")
  }

  # Device model definitions (abstract device)
  type
  DeviceB @deviceModel(id: "urn:tdm:REGION/ACCOUNT ID/default:deviceModel:DeviceB", capability: "urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceB") {
    IGNORE: VOID
  }

  type
  DeviceA @deviceModel(id: "urn:tdm:REGION/ACCOUNT ID/default:deviceModel:DeviceA", capability: "urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceA") {
    IGNORE: VOID
  }

  # Device definitions (physical device)
  query
  DeviceA @device(id: "urn:tdm:REGION/ACCOUNT ID/default:device:DeviceA", deviceModel: "urn:tdm:REGION/ACCOUNT ID/default:deviceModel:DeviceA") {
    MQTT {
      Capability(id: "urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceA") {
        Action(name: "readBarcode") {
          Publish {
            Request(topic: "DeviceA/in") {
              params
            }
            Response(topic: "DeviceA/out") {
              responsePayload(property: "urn:tdm:REGION/ACCOUNT ID/default:property:Barcode")
            }
          }
        }
      }
    }
  }

  query
  DeviceB @device(id: "urn:tdm:REGION/ACCOUNT ID/default:device:DeviceB", deviceModel: "urn:tdm:REGION/ACCOUNT ID/default:deviceModel:DeviceB") {
    MQTT {
      Capability(id: "urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceB") {
        Action(name: "doSomething") {
          params {
            param(name: "input", property: "urn:tdm:REGION/ACCOUNT ID/default:property:Barcode")
          }
          Publish {
            Request(topic: "DeviceB/in") {
              params {
                param(name: "readId", property: "urn:tdm:REGION/ACCOUNT ID/default:property:Barcode", value: "${input.value}")
              }
            }
          }
        }
      }
    }
  }
}

These models create the properties, states, actions, and capabilities, and the two devices that contain these other entities.

Step 2. Upload the entity definitions

After you have finished writing the entity definitions that compose your flow, you upload the definitions to your private namespace. You can do this in two ways, by using the UploadEntityDefinitions API and the CLI or by using the AWS IoT Things Graph console.

Create the JSON definition document.

The UploadEntityDefinitions API consumes a JSON object with two parameter values: language and text.

Currently, the only supported value for language is GraphQL. The value of text is a set of TDM definitions implemented in GraphQL. The resulting JSON looks like the following example.



{
    "language": "GRAPHQL",
    "text" : "string containing the GRAPHQL models"
 }

You can construct the JSON payload in any way that your development framework and language support. For convenience, the following example contains a valid JSON object that you can copy into a file if you don't want to create one yourself.




{
    "language": "GRAPHQL",
    "text": "{type String @propertyType(id: 'urn:tdm:REGION/ACCOUNT ID/default:property:String', dataType: String) {IGNORE: VOID} type Boolean @propertyType(id: 'urn:tdm:REGION/ACCOUNT ID/default:property:Boolean', dataType: Boolean) {IGNORE: VOID} type BarcodeType @stateType(id: 'urn:tdm:REGION/ACCOUNT ID/default:state:BarcodeType') {id: Property @property(id: 'urn:tdm:REGION/ACCOUNT ID/default:property:String')} type Barcode @propertyType(id: 'urn:tdm:REGION/ACCOUNT ID/default:property:Barcode', instanceOf: 'urn:tdm:REGION/ACCOUNT ID/default:state:BarcodeType') { IGNORE: VOID} type DeviceA_ReadBarcode @actionType(id: 'urn:tdm:REGION/ACCOUNT ID/default:action:DeviceA_ReadBarcode') {return: Property @property(id: 'urn:tdm:REGION/ACCOUNT ID/default:property:Barcode')} type DeviceB_Action @actionType(id: 'urn:tdm:REGION/ACCOUNT ID/default:action:DeviceB_Action') { input: Property @property(id: 'urn:tdm:REGION/ACCOUNT ID/default:property:Barcode')} type DeviceA @capabilityType(id: 'urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceA') { readBarcode: Action @action(id: 'urn:tdm:REGION/ACCOUNT ID/default:action:DeviceA_ReadBarcode')} type DeviceB @capabilityType(id: 'urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceB') {doSomething: Action @action(id: 'urn:tdm:REGION/ACCOUNT ID/default:action:DeviceB_Action')} type DeviceB @deviceModel(id: 'urn:tdm:REGION/ACCOUNT ID/default:deviceModel:DeviceB', capability: 'urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceB') {IGNORE: VOID} type DeviceA @deviceModel(id: 'urn:tdm:REGION/ACCOUNT ID/default:deviceModel:DeviceA', capability: 'urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceA') {IGNORE: VOID} query DeviceA @device(id: 'urn:tdm:REGION/ACCOUNT ID/default:device:DeviceA', deviceModel: 'urn:tdm:REGION/ACCOUNT ID/default:deviceModel:DeviceA') { MQTT { Capability(id: 'urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceA') { Action(name: 'readBarcode') { Publish {Request(topic: 'DeviceA/in') {params} Response(topic: 'DeviceA/out') {responsePayload(property: 'urn:tdm:REGION/ACCOUNT ID/default:property:Barcode')}}}}}} query DeviceB @device(id: 'urn:tdm:REGION/ACCOUNT ID/default:device:DeviceB', deviceModel: 'urn:tdm:REGION/ACCOUNT ID/default:deviceModel:DeviceB') { MQTT {Capability(id: 'urn:tdm:REGION/ACCOUNT ID/default:capability:DeviceB') {Action(name: 'doSomething') {params {param(name: 'input', property: 'urn:tdm:REGION/ACCOUNT ID/default:property:Barcode')} Publish { Request(topic: 'DeviceB/in') { params {param(name: 'readId', property: 'urn:tdm:REGION/ACCOUNT ID/default:property:Barcode', value: '${input.value}')}}}}}}}}"
}

Upload the JSON definition document.

After you construct the JSON payload that contains the GraphQL definitions, upload it to your namespace by using the following CLI command.
```
aws iotthingsgraph upload-entity-definitions --document file://entity file name                  
        
```
This command is executed asynchronously. Before using any of these entities, check whether the execution is complete by using the get-upload-status command, as in the following example.
```
aws iotthingsgraph get-upload-status --upload-id UPLOAD ID
        
```

In the AWS IoT Things Graph console, select the menu icon at the upper left of the page. Choose Models.
On the Models page, choose Create model.
On the Create device model page, enter a name for your model. You can choose Upload a GraphQL file or Code in a GraphQL editor.

If you choose to upload a GraphQL file, you can use the same JSON definition document that you created in Upload the Entity Definition (CLI).

For this example, choose Code in a GraphQL editor. Then choose Next.
On the Provide GraphQL page, copy the GraphQL for your model into the editor. Then choose Import. Verify that your new model is included in the list on the Models page.

Step 3. Associate devices with things

Now that you've created two devices, you associate them with things in your registry. (If you haven't created things for your devices already, see Register a device in the registry for instructions on how to create things.)

When you have two configured things to associate with your abstract devices, you can associate them with your devices by using the following CLI command.



aws iotthingsgraph associate-entity-to-thing --thing-name DeviceA --entity-id "urn:tdm:REGION/ACCOUNT_ID/default:device:DeviceA"                    
aws iotthingsgraph associate-entity-to-thing --thing-name DeviceB --entity-id "urn:tdm:REGION/ACCOUNT_ID/default:device:DeviceB"

On the AWS IoT Things Graph console home page, select the menu icon at the upper left of the page. Choose Models.
On the Things page, select the check box next to the AWS IoT thing from your registry to associate with a device that you created. Choose Associate.
On the Select device model page, choose the device to associate with your thing. Then choose Associate.
On the Things page, reload the page and verify that your device and thing are associated.
Repeat steps 2 and 3 for ThingB and any other things you want to associate with devices.

For more information about creating and managing a flow that contains these entities, see Creating and deploying flows.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Service modeling 101

Versioning and entity modeling