8x8 Workflow Instance Management API

openapi: 3.2.0
info:
  title: Automation Workflow Instance Management API
  version: '1.0'
  description: API for managing workflows on 8x8 Automation
  contact:
    name: 8x8 Inc
    url: https://cpaas.8x8.com
    email: cpaas-support@8x8.com
  termsOfService: https://cpaas.8x8.com/sg/terms-and-conditions/
servers:
- url: https://automation.8x8.com
security:
- bearerAuth: []
tags:
- name: Workflow Instance Management
paths:
  /api/v1/accounts/{accountId}/definitions/{definitionId}/workflows:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/definitionId'
    get:
      operationId: get-workflow-instances
      tags:
      - Workflow Instance Management
      summary: Retrieve a list of workflow instances
      description: Use this resource to explore workflows created based on a specific workflow definition. If the definition version is not specified, workflows for the latest version are returned. Results are ordered in descending order of their creation time. Use parameters `limit` and `offset` to paginate through the list.
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/version'
      - schema:
          type: string
          enum:
          - Runnable
          - Suspended
          - Complete
          - Terminated
          description: "Workflow instance status. Supported statuses are\n  * Runnable (workflows that are in progress)\n  * Complete (workflows that have completed without errors)\n  * Suspended (workflows that have been suspended)\n  * Terminated (workflows that have been manually terminated or faulted)"
        in: query
        name: status
      - schema:
          type: string
          example: '2021-06-24T09:33:06.60Z'
        in: query
        name: startTimeFrom
        description: Minimum workflow instance start time in ISO 8601 format
      - schema:
          type: string
          example: '2021-06-24T09:33:06.60Z'
        in: query
        name: startTimeTo
        description: Maximum workflow instance start time in ISO 8601 format
      responses:
        '200':
          description: List of workflow instances. If there are no workflows by the specified definition id, an empty list is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/workflowInstance'
              examples:
                workflowInstances:
                  $ref: '#/components/examples/workflowInstances'
        '400':
          description: Definition id is invalid (not a valid uuid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionIdError'
        '404':
          description: Workflow definition is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/definitionNotFoundError'
  /api/v1/accounts/{accountId}/definitions/{definitionId}/workflows/{workflowId}:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/definitionId'
    - $ref: '#/components/parameters/workflowId'
    get:
      operationId: get-instance-status
      tags:
      - Workflow Instance Management
      summary: Retrieve workflow instance status
      description: Use this resource to view the status of a workflow instance.
      parameters:
      - schema:
          type: boolean
          default: false
          example: true
        in: query
        name: includeLogs
        description: If set to true, response includes detailed execution logs of workflow steps. This information is useful when debugging a workflow definition.
      responses:
        '200':
          description: Workflow instance.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/workflowInstance'
                - $ref: '#/components/schemas/workflowInstanceWithLogs'
              examples:
                workflow instance:
                  $ref: '#/components/examples/workflowInstance'
                workflow instance with logs:
                  $ref: '#/components/examples/workflowInstanceWithLogs'
        '400':
          description: Workflow definition id or the workflow instance id is invalid (not a valid uuid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionIdError'
        '404':
          description: Workflow instance or definition is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/definitionNotFoundError'
    patch:
      operationId: patch-workflow-instance
      tags:
      - Workflow Instance Management
      summary: Update workflow instance status
      description: Use this resource to control the state of a workflow instance. For example, you can suspend a workflow to be resumed later or terminate a workflow due to an error.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - suspend
                  - resume
                  - terminate
                  description: "List of commands available. Supported commands are\n  * suspend (suspends a workflow that is currently in progress)\n  * resume (resumes a currently suspended workflow)\n  * terminate (terminates the workflow. A terminated workflow cannot be resumed)"
            example:
              status: suspend
      responses:
        '200':
          description: Workflow status successfully updated.
        '400':
          description: Request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionIdError'
        '404':
          description: Workflow instance or definition is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/definitionNotFoundError'
  /api/v1/accounts/{accountId}/definitions/{definitionId}/workflows/{workflowId}/errors:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/definitionId'
    - $ref: '#/components/parameters/workflowId'
    get:
      operationId: get-instance-errors
      tags:
      - Workflow Instance Management
      summary: Retrieve a list of errors for a workflow instance
      description: Use this resource to retrieve a list of runtime errors for a workflow instance. If the workflow definition is not working as expected, workflow errors help you figure out what went wrong.
      responses:
        '200':
          description: List of workflow instance errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/workflowErrors'
              examples:
                workflowError:
                  $ref: '#/components/examples/workflowError'
        '400':
          description: Request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/invalidDefinitionIdError'
        '404':
          description: Workflow instance or definition is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                error:
                  $ref: '#/components/examples/definitionNotFoundError'
components:
  examples:
    workflowInstanceWithLogs:
      value:
        workflowId: 60dbe307fe55d99fc083db61
        data:
          payload:
            umid: 9e09ac86-bd74-5465-851d-1eb5a5fdbb9a
            user:
              channelUserId: test_user_id
              name: test_user_name
            content:
              text: Hello, world!
          accountId: test_account_id
          subAccountId: test_subaccount_id
          triggeredAt: '2021-06-30T03:20:39.3857479Z'
        definitionId: 5870442f-3ddd-4657-b74c-6e17308f5230
        version: 1
        status: Complete
        startedAt: '2021-06-30T03:20:39.49Z'
        completedAt: '2021-06-30T03:21:25.83Z'
        logs:
        - id: b2c6185b-5bbd-424e-bea0-3d09d5d14566
          stepName: step1
          startedAt: '2021-06-30T03:20:39.68Z'
          completedAt: '2021-06-30T03:20:39.69Z'
          status: Complete
        - id: b2c6185b-5bbd-424e-bea0-3d09d5d14567
          stepName: step2
          startedAt: '2021-06-30T03:20:56.68Z'
          completedAt: '2021-06-30T03:20:58.69Z'
          status: Complete
    workflowInstances:
      value:
      - workflowId: 60dbe307fe55d99fc083db61
        data:
          payload:
            umid: 9e09ac86-bd74-5465-851d-1eb5a5fdbb9a
            user:
              channelUserId: test_user_id
              name: test_user_name
            content:
              text: Hello, world!
          accountId: test_account_id
          subAccountId: test_subaccount_id
          triggeredAt: '2021-06-30T03:20:39.3857479Z'
        definitionId: 5870442f-3ddd-4657-b74c-6e17308f5230
        version: 1
        status: Complete
        startedAt: '2021-06-30T03:20:39.49Z'
        completedAt: '2021-06-30T03:21:25.83Z'
      - workflowId: 60dbe307fe55d99fc083db62
        data:
          payload:
            umid: 9e09ac86-bd74-5465-851d-1eb5a5fdbb9a
            user:
              channelUserId: test_user_id
              name: test_user_name
            content:
              text: Hello, world!
          accountId: test_account_id
          subAccountId: test_subaccount_id
          triggeredAt: '2021-06-30T03:20:39.3857479Z'
        definitionId: 5870442f-3ddd-4657-b74c-6e17308f5230
        version: 1
        status: Complete
        startedAt: '2021-06-30T03:20:39.49Z'
        completedAt: '2021-06-30T03:21:25.83Z'
    workflowInstance:
      value:
        workflowId: 60dbe307fe55d99fc083db61
        data:
          payload:
            umid: 9e09ac86-bd74-5465-851d-1eb5a5fdbb9a
            user:
              channelUserId: test_user_id
              name: test_user_name
            content:
              text: Hello, world!
          accountId: test_account_id
          subAccountId: test_subaccount_id
          triggeredAt: '2021-06-30T03:20:39.3857479Z'
        definitionId: 5870442f-3ddd-4657-b74c-6e17308f5230
        version: 1
        status: Complete
        startedAt: '2021-06-30T03:20:39.49Z'
        completedAt: '2021-06-30T03:21:25.83Z'
    invalidDefinitionIdError:
      value:
        code: 1000
        message: Invalid definition id.
        errorId: 2558ff83-c8db-4890-805e-ad64001857a1
        timestamp: '2021-07-13T01:28:37.66Z'
    definitionNotFoundError:
      value:
        code: 1300
        message: Definition 2aa9465e-dec7-4c3e-8fa6-bd168af9eaca not found.
        errorId: 2558ff83-c8db-4890-805e-ad64001857a1
        timestamp: '2021-07-13T01:28:37.66Z'
    workflowError:
      value:
        workflowId: 60e6b22fc517c0785de3ca22
        step: step1
        message: Invalid subaccount id.
        errorTime: '2021-06-30T03:21:25.83Z'
  schemas:
    workflowInstanceWithLogs:
      type: object
      description: Workflow instance
      required:
      - workflowId
      - data
      - definitionId
      - version
      - status
      - startedAt
      - completedAt
      properties:
        workflowId:
          type: string
          description: Unique id of the workflow instance.
        data:
          type: object
          description: Workflow context.
          required:
          - accountId
          - triggeredAt
          properties:
            accountId:
              type: string
              description: Id of the account to which the workflow definition belongs.
            triggeredAt:
              type: string
              description: ISO 8601 formatted timestamp when the trigger that started the workflow was raised.
            subAccountId:
              type: string
              description: Subaccount id under which the workflow is running. Subaccount id is only available if the trigger was raised with the subaccount id. For inbound SMS and chat apps triggers subaccount id is usually available.
        definitionId:
          type: string
          description: Id of the workflow definition to which the workflow instance belongs to.
        version:
          type: integer
          minimum: 1
          description: Version of the workflow definition to which the workflow instance belongs to.
        status:
          type: string
          description: "Last known status of the workflow instance. Supported statuses are\n  * Runnable (Workflow is either currently running, waiting for an event, or pausing for a duration).\n  * Suspended (Workflow is suspended (usually by issuing the suspend command). A suspended workflow can be resumed by issuing the resume command).\n  * Complete (Workflow has run to completion without errors).\n  * Terminated (Workflow has either been terminated manually or faulted).\nIf the workflow has faulted, you can use the workflow error resource to figure out what caused the error."
        startedAt:
          type: string
          description: ISO 8601 formatted timestamp of the workflow start time.
        completedAt:
          type: string
          description: If the workflow has been completed, ISO 8601 formatted timestamp of the completion time. Otherwise, null.
          default: null
        logs:
          type: array
          description: Execution log of the workflow steps which is useful for debugging the workflow.
          items:
            $ref: '#/components/schemas/workflowLog'
    workflowInstance:
      type: object
      description: Workflow instance
      required:
      - workflowId
      - data
      - definitionId
      - version
      - status
      - startedAt
      - completedAt
      properties:
        workflowId:
          type: string
          description: Unique id of the workflow instance.
        data:
          type: object
          description: Workflow context.
          required:
          - accountId
          - triggeredAt
          properties:
            accountId:
              type: string
              description: Id of the account to which the workflow definition belongs.
            triggeredAt:
              type: string
              description: ISO 8601 formatted timestamp when the trigger that started the workflow was raised.
            subAccountId:
              type: string
              description: Subaccount id under which the workflow is running. Subaccount id is only available if the trigger was raised with the subaccount id. For inbound SMS and chat apps triggers subaccount id is usually available.
        definitionId:
          type: string
          description: Id of the workflow definition to which the workflow instance belongs to.
        version:
          type: integer
          minimum: 1
          description: Version of the workflow definition to which the workflow instance belongs to.
        status:
          type: string
          description: "Last known status of the workflow instance. Supported statuses are\n  * Runnable (Workflow is either currently running, waiting for an event, or pausing for a duration).\n  * Suspended (Workflow is suspended (usually by issuing the suspend command). A suspended workflow can be resumed by issuing the resume command).\n  * Complete (Workflow has run to completion without errors).\n  * Terminated (Workflow has either been terminated manually or faulted).\nIf the workflow has faulted, you can use the workflow error resource to figure out what caused the error."
        startedAt:
          type: string
          description: ISO 8601 formatted timestamp of the workflow start time.
        completedAt:
          type: string
          description: If the workflow has been completed, ISO 8601 formatted timestamp of the completion time. Otherwise, null.
          default: null
    workflowLog:
      type: object
      required:
      - id
      - stepName
      - startedAt
      - completedAt
      - status
      properties:
        id:
          type: string
          description: Unique step execution id.
        stepName:
          type: string
          description: Id of the step provided by the user when creating the workflow definition.
        startedAt:
          type: string
          description: ISO 8601 formatted timestamp of the step start time.
        completedAt:
          type: string
          description: ISO 8601 formatted timestamp of the step completion time.
        status:
          type: string
          description: "Last known status of the step. Available statuses are\n  * Pending (step is waiting to be executed)\n  * Running (step is currently in progress)\n  * Complete (step has completed without errors)\n  * Sleeping (step is waiting for a duration like in the case of a Wait step)\n  * WaitingForEvent (step is waiting for an event like a reply to a message)\n  * Failed (step execution has faulted)\n  * Cancelled (step has been cancelled like in the case of an event timeout)"
    error:
      type: object
      description: Error response.
      properties:
        code:
          type: integer
          description: Error code.
        message:
          type: string
          description: Description of the error.
        errorId:
          type: string
          description: Unique error id.
        timestamp:
          type: string
          description: Timestamp when the error occurred.
      required:
      - code
      - message
      - errorId
      - timestamp
    workflowErrors:
      type: object
      required:
      - workflowId
      - step
      - message
      - errorTime
      properties:
        workflowId:
          type: string
          description: Unique id of the workflow instance to which the error belongs to.
        step:
          type: string
          description: Id of the step that faulted.
        message:
          type: string
          description: Reason for failure.
        errorTime:
          type: string
          description: ISO 8601 formatted timestamp of the time the error occurred.
  parameters:
    workflowId:
      name: workflowId
      in: path
      description: Workflow instance id.
      required: true
      schema:
        type: string
        example: 60dbe307fe55d99fc083db61
    version:
      name: version
      in: query
      description: Version of the workflow definition.
      required: false
      schema:
        type: integer
        minimum: 1
        example: 1
    limit:
      name: limit
      in: query
      description: Number of items to include in the response.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    definitionId:
      name: definitionId
      in: path
      description: Workflow definition id.
      required: true
      schema:
        type: string
        example: 5870442f-3ddd-4657-b74c-6e17308f5230
    accountId:
      name: accountId
      in: path
      description: Account id
      required: true
      schema:
        type: string
        example: test_account_id
    offset:
      name: offset
      in: query
      description: Page offset. Setting limit to 10 and offset to 0 returns the first 10 items. Increment offset to retrieve more items.
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer