ThingSpeak Queue and Execute TalkBack Command

arazzo: 1.0.1
info:
  title: ThingSpeak Queue and Execute TalkBack Command
  summary: Add a command to a TalkBack queue, then dequeue it as a device would.
  description: >-
    The round trip for cloud-to-device command delivery. It adds a command to a
    TalkBack queue from the cloud side, then performs the device-side execute call
    that atomically receives and dequeues the next pending command. The flow
    branches on whether the execute call returned a command string or an empty
    queue. Every step spells out its request inline so the flow can be read and
    executed without opening the underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: talkbackApi
  url: ../openapi/thingspeak-talkback-api-openapi.yml
  type: openapi
workflows:
- workflowId: queue-and-execute-talkback-command
  summary: Queue a TalkBack command and dequeue it from the device side.
  description: >-
    Adds a command to the queue, then executes the next command and branches on
    whether a command was returned.
  inputs:
    type: object
    required:
    - talkbackId
    - apiKey
    - commandString
    properties:
      talkbackId:
        type: integer
        description: Numeric id of the TalkBack queue.
      apiKey:
        type: string
        description: TalkBack API Key (api_key query parameter).
      commandString:
        type: string
        description: The command text to queue for the device.
      position:
        type: integer
        description: Optional position in the queue for the new command.
  steps:
  - stepId: addCommand
    description: >-
      Add a command to the TalkBack queue from the cloud side.
    operationId: addCommand
    parameters:
    - name: talkback_id
      in: path
      value: $inputs.talkbackId
    requestBody:
      contentType: application/json
      payload:
        api_key: $inputs.apiKey
        command_string: $inputs.commandString
        position: $inputs.position
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      commandId: $response.body#/id
      commandString: $response.body#/command_string
  - stepId: executeNextCommand
    description: >-
      Perform the device-side call that receives and dequeues the next command.
    operationId: executeNextCommand
    parameters:
    - name: talkback_id
      in: path
      value: $inputs.talkbackId
    - name: api_key
      in: query
      value: $inputs.apiKey
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      executedCommandId: $response.body#/id
      executedCommandString: $response.body#/command_string
    onSuccess:
    - name: commandReturned
      type: end
      criteria:
      - context: $response.body
        condition: $.command_string != null
        type: jsonpath
    - name: queueEmpty
      type: end
      criteria:
      - context: $response.body
        condition: $.command_string == null
        type: jsonpath
  outputs:
    queuedCommandId: $steps.addCommand.outputs.commandId
    executedCommandId: $steps.executeNextCommand.outputs.executedCommandId