arazzo: 1.0.1
info:
  title: Autodesk Push Sensor Readings into a Tandem Stream
  summary: Resolve a twin's IoT streams, push time-series datapoints, and read the series back.
  description: >-
    Wiring physical sensors into a digital twin. The workflow lists the IoT streams a
    Tandem twin exposes, pushes a batch of time-stamped readings into the target
    stream, and reads the series back at a chosen resolution to confirm the datapoints
    landed and to drive a dashboard. This is the loop a building management system or
    IoT gateway runs continuously. 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: tandemDataApi
  url: ../openapi/autodesk-tandem-data-openapi.yml
  type: openapi
workflows:
- workflowId: push-and-read-stream-data
  summary: Ingest sensor readings into a twin stream and verify the series.
  description: >-
    Lists the twin's streams to resolve the target stream and the element it is bound
    to, pushes a batch of datapoints, and reads back the time-series over a window at
    a given resolution.
  inputs:
    type: object
    required:
    - twinId
    - datapoints
    properties:
      twinId:
        type: string
        description: The digital twin facility whose streams are being written to.
      datapoints:
        type: array
        description: >-
          Time-stamped readings to push. Each entry carries a timestamp and a value.
        items:
          type: object
          properties:
            timestamp:
              type: string
              description: ISO 8601 timestamp of the reading.
            value:
              description: The sensor reading value.
      from:
        type: string
        description: Start of the read-back window (ISO 8601 or Unix timestamp).
      to:
        type: string
        description: End of the read-back window (ISO 8601 or Unix timestamp).
      resolution:
        type: string
        description: >-
          Resolution to read the series at: raw, minute, hour, or day.
        default: raw
  steps:
  - stepId: listStreams
    description: >-
      List the IoT streams bound to the twin. Each stream is attached to an element
      and a property, which is how a raw sensor reading becomes facility data.
    operationId: getStreams
    parameters:
    - name: twinId
      in: path
      value: $inputs.twinId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      streams: $response.body#/streams
      streamId: $response.body#/streams/0/streamId
      streamName: $response.body#/streams/0/name
      elementKey: $response.body#/streams/0/elementKey
      lastTimestamp: $response.body#/streams/0/lastTimestamp
  - stepId: pushReadings
    description: >-
      Push the batch of readings into the stream. Batching datapoints rather than
      posting one request per reading is what keeps a busy gateway inside its rate
      limits. Requires data:write.
    operationId: pushTimeseriesData
    parameters:
    - name: streamId
      in: path
      value: $steps.listStreams.outputs.streamId
    requestBody:
      contentType: application/json
      payload:
        datapoints: $inputs.datapoints
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      pushed: $statusCode
  - stepId: readSeries
    description: >-
      Read the series back over the requested window to confirm the datapoints landed
      and to feed a chart. Coarser resolutions roll the raw readings up server-side.
    operationId: getTimeseriesData
    parameters:
    - name: streamId
      in: path
      value: $steps.listStreams.outputs.streamId
    - name: from
      in: query
      value: $inputs.from
    - name: to
      in: query
      value: $inputs.to
    - name: resolution
      in: query
      value: $inputs.resolution
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      timestamps: $response.body#/timestamps
      values: $response.body#/values
      count: $response.body#/count
  outputs:
    streamId: $steps.listStreams.outputs.streamId
    elementKey: $steps.listStreams.outputs.elementKey
    count: $steps.readSeries.outputs.count
    values: $steps.readSeries.outputs.values