Workflow - AWS IoT Things Graph


The Workflow construct (also called flow) describes an automated process that consists of multiple devices and stateful services.

Workflow takes a set of parameters and consists of an array of steps that are connected to events. Input events can trigger a step, and a step can generate an output event. Each step can represent a Lambda function, a device action, or a web application method.

The following pseudocode defines what happens at a conceptual level when you create a workflow.

CREATE Workflow workflowUrn ‘(‘ [paramName paramType [= defaultValue] [,]]* ‘)’ { [varName varType [= defaultValue] [,]]* STEPS { [STEP (NAME stepName, [CONDITION conditionExpr] [DESCRIPTION descriptionText]) { [EVENTS { [INPUT ( ${expression-over events} ) ] [OUTPUT ( [eventName, [eventUrn] [,]]* )] }]* [ACTIVITY ‘(‘ [paramName = paramExpr [,]]* [[,] out =$varName ‘)] [OnError {Retries{Retry (name=retryName, condition=booleanExpr, [ [interval=expr] [backoffRate=expr] [maxAttempts=expr]) }* Catches{Catch(name=catchName, condition=booleanExpr, raiseEvent[(eventName[,])* )} } ] [OnSuccess { (CHECK (name=chkName, condition=booleanExpr) THEN (onPassExpr, onFailExpr)* }] } }

Key concepts


Unique identifier of the workflow.


Data type of the workflow parameter.


Workflow parameter name.


Default parameter value.


Variable name.


Variable type.


Name of a step in the workflow. Unique to the workflow.


Optional description.


Optional condition. If it resolves to false, the step is skipped.


Input or output event name. The step either waits for it to start, or publishes it on completion.


Optional global event URN.


Placeholder for device activity, web activity, or a built-in control activity.


A Boolean condition.


Evaluated if CHECK(booleanExpr) evaluates to true.


Evaluated if CHECK(booleanExpr) evaluates to false.

onError, retries, retry, catches, catch

Error handling with the same semantics as AWS Step Functions.

OnError is evaluated when the activity fails or times out. The Retries are evaluated in the specified order. On exhaustion of all Retries, control falls to the Catch clause.

GraphQL Example

The following GraphQL creates a workflow that monitors door entry in a building. A camera takes a picture of the person entering the building, which triggers a face detection service. The face detection service then displays an image of the person on a screen. The example also handles camera errors and failure.

query monitorDoorEntry ($cameraId: DeviceId!, $screenId: DeviceId!, # Arguments and their data types $lampId: DeviceId!, $cameraDelay_ms : Number = 0, $cameraFailedImage: String = “http://abc/defaultCameraFailedImage.jpg”) @workflowType(id:"urn:tdm:aws:workflow:monitorDoorEntry") { # @workflowType directive and workflow unique URN # Declare workflow variables variables { # Workflow variables cameraImage @property(id:"urn:tdm:aws:property:image/imageUri") # Semantic property imageUri faceDetected @property(id:"urn:tdm:aws:property:bool/boolean") # Raw datatype property boolean } steps { # Set of steps. # Device activity step step(name:"camera", description:"Activate Camera" outEvent:["CameraClicked"]){ # Step name, description, and output event DeviceActivity(deviceModel:"urn:tdm:aws:device:camera" deviceId:"$cameraId"){ # Device activity ARN. Device ID capture(delay_ms:$cameraDelay_ms) } OnError { # Error handling Retries { Retry(name:"foo1", errorEquals:["ErrorA", "ErrorB"], interval:”1 sec”, backoffRate:2.0, maxAttempts:2), Retry(name:"foo2", errorEquals:["ErrorC"], interval:”5 sec”), Retry(name:"foo3", condition:"${Error IN ('ErrorD', 'ErrorE')}", interval:”5 sec”) } Catches { Catch(name:'catch1',condition:"${Error=='ErrorE'}", expr:”$cameraFailed.IsTrue=true]") } } OnSuccess { # Validation of image captured by the camera Check(name:"validation1", condition:"${lib.fileSize(cameraImage) > 100}" ) { OnPass { stmt(expr:"${imageOK=true}") } OnFail { stmt(expr:”$cameraFailed.IsTrue=true)"} # Raise cameraFailed Event } } } # Device activity step step (name:"Lamp") { # Step name DeviceActivity(deviceModel:"urn:tdm:aws:device:lightBulb",deviceId:"$lampId"){ # Device activity ARN. Device ID powerOn(param:$cameraDelay_ms) } } # Web service activity step step(name:"FaceDetectionService" condition:”${imageOK}” inEvent:["CameraClicked"], # Conditional web service activity. Condition is $imageOK outEvent:["FaceDetectedEvt"]) { # Input and output events WebServiceActivity(webservice:"urn:tdm:aws:service:faceDetection" out:”$faceDetected”) { detect(image:”$cameraImage”) } } # Device activity step step(name:"DisplayImage", inEvent:”${FaceDetectedEvt}" ) { # Conditional device activity. DeviceActivity(DeviceModel:"urn:tdm:aws:devicemodel:displayScreen" deviceId:"$screenId”) { # Device activity ARN. Device ID display(imageUri:”${cameraImage.lastClickedImage) # Display the image. } } } }

This example contains the following key elements that differ from the AWS Lambda service:

  • A set of arguments and their data types. This example passes three non-nullable device URNs, a camera burst delay setting with a default value of 0, and an image URL (with a default value) for failed image captures.

  • The workflowType directive and its unique URN.

  • A set of workflow variables and their data types (and property URNs).

  • A list of steps with names and descriptions.

  • Each step has an activity specification. Possible values are DeviceActivity and WebServiceActivity.

  • A DeviceActivity is specified by a device model and the ID of the concrete device in the workflow.

  • The device or service activity that the device or service in each step performs. These activities are specified in the device model's capability. They are implemented in the concrete device's definition.

  • Error handling with the OnError, Retries, Retry, Catches, and Catch. The OnError clause is evaluated when the activity fails or times out. The Retries clause is then evaluated in the specified order until all Retry clauses have been attempted. If all of the retries fail, control falls to the Catches clause. These clauses have the same semantics as Retry and Catch in AWS Step Functions. The OnSuccess clause also contains additional validation to ensure that the camera captured a valid image.

The workflow makes extensive use of Expressions to determine how the workflow proceeds, depending on whether the camera works and the condition of the image that it returns. The web service activity, for example, doesn't run unless a valid image is captured. See Expressions for more information about how to use expressions.