Arthur Online - maintenance dispatch

arazzo: 1.0.1
info:
  title: Arthur Online - maintenance dispatch
  version: 1.0.0
  description: >-
    Raise a maintenance task against a property, break it into subtasks, dispatch it to a
    contractor as a work order, open the conversation and read back quotes and invoices.
    Approval steps (manager approves completion, owner accepts a quote) are UI-only in Arthur
    and appear here as read-backs rather than calls.
sourceDescriptions:
- name: tasksApi
  url: ../openapi/arthur-online-tasks-api-openapi.yml
  type: openapi
- name: workordersApi
  url: ../openapi/arthur-online-workorders-api-openapi.yml
  type: openapi
workflows:
- workflowId: maintenanceDispatch
  summary: Task to work order to quote to invoice.
  inputs:
    type: object
    required: [entityId, propertyId, task]
    properties:
      entityId: {type: string, description: Sent as X-EntityID on every call.}
      propertyId: {type: integer, description: The property the issue belongs to.}
      task: {type: object, description: Task fields as documented on Add Task on Property.}
      subtask: {type: object, description: Subtask fields.}
      workorder: {type: object, description: Work order fields including the contractor assignment.}
      message: {type: object, description: Conversation fields for the contractor thread.}
      statusUpdate: {type: object, description: The task status transition payload.}
  steps:
  - stepId: raiseTask
    description: Raise the task against the property. Not idempotent - never auto-retry.
    operationId: $sourceDescriptions.tasksApi.addTaskOnProperty
    parameters:
    - {name: property_id, in: path, value: $inputs.propertyId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    - {name: strict, in: query, value: true}
    requestBody:
      contentType: application/json
      payload: $inputs.task
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      taskId: $response.body#/data/id
  - stepId: addSubtask
    operationId: $sourceDescriptions.tasksApi.createSubtaskOnTask
    parameters:
    - {name: task_id, in: path, value: $steps.raiseTask.outputs.taskId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    - {name: strict, in: query, value: true}
    requestBody:
      contentType: application/json
      payload: $inputs.subtask
    successCriteria:
    - condition: $statusCode == 200
  - stepId: moveTaskLive
    operationId: $sourceDescriptions.tasksApi.updateStatusOnTask
    parameters:
    - {name: task_id, in: path, value: $steps.raiseTask.outputs.taskId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    - {name: strict, in: query, value: true}
    requestBody:
      contentType: application/json
      payload: $inputs.statusUpdate
    successCriteria:
    - condition: $statusCode == 200
  - stepId: dispatchWorkorder
    description: Create the work order from the task and assign the contractor.
    operationId: $sourceDescriptions.tasksApi.createWorkorderOnTask
    parameters:
    - {name: task_id, in: path, value: $steps.raiseTask.outputs.taskId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    - {name: strict, in: query, value: true}
    requestBody:
      contentType: application/json
      payload: $inputs.workorder
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      workorderId: $response.body#/data/id
  - stepId: confirmContractor
    operationId: $sourceDescriptions.workordersApi.listContractorsOnWorkorder
    parameters:
    - {name: workorder_id, in: path, value: $steps.dispatchWorkorder.outputs.workorderId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    successCriteria:
    - condition: $statusCode == 200
  - stepId: whoCanBeMessaged
    operationId: $sourceDescriptions.workordersApi.getRecipientsForWorkorder
    parameters:
    - {name: workorder_id, in: path, value: $steps.dispatchWorkorder.outputs.workorderId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    successCriteria:
    - condition: $statusCode == 200
  - stepId: openConversation
    operationId: $sourceDescriptions.workordersApi.createConversationOnWorkorder
    parameters:
    - {name: workorder_id, in: path, value: $steps.dispatchWorkorder.outputs.workorderId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    - {name: strict, in: query, value: true}
    requestBody:
      contentType: application/json
      payload: $inputs.message
    successCriteria:
    - condition: $statusCode == 200
  - stepId: readQuotes
    description: Quote acceptance happens in the Arthur apps; read the state back here.
    operationId: $sourceDescriptions.workordersApi.listQuotesOnWorkorder
    parameters:
    - {name: workorder_id, in: path, value: $steps.dispatchWorkorder.outputs.workorderId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    successCriteria:
    - condition: $statusCode == 200
  - stepId: readInvoices
    operationId: $sourceDescriptions.workordersApi.listInvoicesOnWorkorder
    parameters:
    - {name: workorder_id, in: path, value: $steps.dispatchWorkorder.outputs.workorderId}
    - {name: X-EntityID, in: header, value: $inputs.entityId}
    successCriteria:
    - condition: $statusCode == 200
  outputs:
    taskId: $steps.raiseTask.outputs.taskId
    workorderId: $steps.dispatchWorkorder.outputs.workorderId