Creating a flow configuration in the AWS CLI - AWS IoT Things Graph

Creating a flow configuration in the AWS CLI

These instructions are similar to the procedure for creating and deploying the flow in Creating a flow with devices and a service. That topic contains complete instructions on setting up your environment, creating things, creating the flow (and the system), and associating things with devices. Because this is a cloud deployment, instead of creating and configuring a AWS IoT Greengrass group, follow the instructions in Prepare for cloud deployments to create the IAM role that AWS IoT Things Graph assumes when it executes the flow.

Defining the flow configuration

The following AWS IoT Things Graph Data Model (TDM) shows the underlying definition of the flow configuration created in Creating a flow with devices and a service. Replace the REGION and ACCOUNT ID placeholders with your AWS Region and account ID.

query Lobby @deployment(id: "urn:tdm:REGION/ACCOUNT ID/default:Deployment:Lobby" systemId: "urn:tdm:REGION/ACCOUNT ID/default:System:RekognitionFlowSystem") { motionSensor(deviceId: "MotionSensor1") screen(deviceId: "Screen1") cameraRkgnExample(deviceId: "Camera1") triggers { MotionEventTrigger(description: 'a trigger') { condition(expr: "devices[name == 'motionSensor'].events[name == 'StateChanged'].lastEvent.value") action(expr: "ThingsGraph.startFlow('RekognitionFlow', bindings[name == 'cameraRkgnExample'].deviceId, bindings[name == 'screen'].deviceId)") } } }

In this deployment definition:

  • You create a deployment definition as a GraphQL query.

  • The @deployment declaration tells AWS IoT Things Graph to create a deployment definition whose identifier is the TDM URN inside the parentheses.

  • The next value inside the parentheses is the URN of the system that contains the workflow (also called a flow) or flows that deploy with this deployment.

  • The content inside the braces begins by assigning the names of the devices or device models in the flows (as specified in the system definition) to things that are registered in your AWS IoT registry. Before you make this assignment in the TDM, use the AssociateEntityToThing API to associate each device with each thing you're using in the deployment. The deviceId values are the names of the things in your registry.

  • The triggers block contains one or more triggers. The MotionEventTrigger in this example consists of a condition that triggers the flow and the action that starts when the trigger condition is met.

  • The condition uses two path expressions to identify a device that is used in a flow and one of that device's events, with a predicate expression that determines whether the device has detected motion. If the lastEvent value sent by the motionSensor device is true, a non-empty string, or a numeric value other than zero (0), the devices[name == 'motionSensor'].events[name == 'StateChanged'].lastEvent.value expression evaluates to true. This signifies that a motion detected event has occurred. If you want the expression to evaluate to true every time the event is fired, use devices[name == 'motionSensor'].events[name == 'StateChanged'].lastEvent.

  • The action uses the ThingsGraph.startFlow function, which initiates the specified flow. The flow name matches the name of the flow in the system definition. The bindings path expressions specify the names of the things that are used in the flow.

Now that you have a complete deployment definition, you can create the flow configuration by using the AWS CLI.

The values that follow the flow name inside the action can be any valid flow parameters. The following example triggers show some of the values and path expressions that you can use inside the action block of a trigger.

DataEmitterTrigger01(description: "trigger on integer events") { condition(expr: "devices[name == 'dataEmitter'].events[name == 'IntegerEvent'].lastEvent.val > 10") action(expr: "ThingsGraph.startFlow('exampleFlow1', devices[name == 'dataEmitter'].events[name == 'IntegerEvent'].lastEvent.val, False, 1.1, ((String)devices[name == 'dataEmitter'].events[name == 'IntegerEvent'].lastEvent.val).charAt(0))") } DataEmitterTrigger02(description: "trigger on json events") { condition(expr: "devices[name == 'dataEmitter'].events[name == 'JsonEvent'].lastEvent") action(expr: "ThingsGraph.startFlow('exampleFlow2', -100, True, -1.0000000001, devices[name == 'dataEmitter'].events[name == 'JsonEvent'].lastEvent)") }

For more information about triggers, see Trigger.

Creating the flow configuration

The following command shows how to create a flow configuration by using the AWS CLI.

aws iotthingsgraph create-system-instance --definition language=GRAPHQL,text="TDM Deployment Definition" \ --target CLOUD --flow-actions-role-arn IAM Role \ --metrics-configuration true/false
  • target parameter – Specifies the target type of the deployment. For cloud deployments, specify CLOUD.

  • flow-actions-role-arn parameter – Specifies the role that AWS IoT Things Graph assumes when it executes the flow in the cloud. For instructions on how to create this role, see Prepare for cloud deployments.

When the operation completes, the AWS CLI returns the following deployment summary (as a JSON object).

{ "summary": { "status": "PENDING_DEPLOYMENT", "greengrassGroupName": "AWS IoT Greengrass Group Name", "target": "GREENGRASS", "arn": "arn:aws:iotthingsgraph:REGION:ACCOUNT ID:default#Deployment#Lobby", "updatedAt": 1547245009.256, "id": "urn:tdm:REGION/ACCOUNT ID/default:Deployment:Lobby", "createdAt": 1547245009.256 } }

In this deployment summary:

  • The status value in the summary object is PENDING_DEPLOYMENT when a flow configuration is created.

  • The id value in the summary block is the TDM URN of the flow configuration.

The following command uses the id value to deploy the flow configuration to the target.

aws iotthingsgraph deploy-system-instance --id Flow Configuration Id

For more information about creating a flow configuration programmatically, see CreateSystemInstance in the AWS IoT Things Graph API Reference.