Unqork Workflow API

openapi: 3.2.0
info:
  version: 1.0.0
  x-logo:
    url: https://developers.unqork.io/unqork-logo.png
    backgroundColor: '#FFFFFF'
  title: Unqork Customer Workflow API
  description: Unqork's customer REST API, based on open standards, allows you to set and retrieve module submission data, as well as control other aspects of your Unqork environment.
servers:
- url: https://{host}/api/1.0
  variables:
    host:
      default: env.unqork.io
      description: Environment host
security:
- OAuth2: []
tags:
- name: Workflow
paths:
  /workflows/{workflowPath}/timerstart:
    get:
      x-unqork-service: true
      tags:
      - Workflow
      summary: List of timer start nodes and statuses
      operationId: listTimerStartNodes
      description: 'Get a list of all timer start nodes and their activity status in a workflow

        ### Authorization Required:

        - Application View'
      parameters:
      - $ref: '#/components/parameters/WorkflowPath'
      responses:
        '200':
          description: List of timer start nodes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievedTimerStartResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowPath}/timedEvents/{submissionId}:
    get:
      x-unqork-service: true
      tags:
      - Workflow
      summary: List of Timed Events for Submission Id
      operationId: listTimedEventsBySubmissionId
      description: 'Get a list of all timed events that have been queued for a submission Id

        ### Authorization Required:

        - See Submission Access (Submission Access)'
      parameters:
      - $ref: '#/components/parameters/WorkflowPath'
      - name: submissionId
        in: path
        description: ID of workflow submission to retrieve
        required: true
        schema:
          type: string
      - name: status
        in: query
        description: Status of timed event action
        required: false
        schema:
          type: string
          enum:
          - ACTIVE
          - CANCELLED
          - EXECUTED
          - EXECUTION_FAILED
          - SLA_TRACKING_ERROR
      - name: actionType
        in: query
        description: Type of action
        required: false
        schema:
          type: string
          enum:
          - message
          - changePath
      - name: timedEventNode
        in: query
        description: Path of timed event node the action is part of
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of timed event actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievedTimedEventsBySubmissionIdResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowPath}/timerstart/{timerStartNodePath}/start:
    post:
      x-unqork-service: true
      tags:
      - Workflow
      summary: Start a Timer Start Node
      operationId: startTimerStartNode
      description: 'Trigger a timer start node to start which will create and execute workflow submissions at the configured frequency

        ### Authorization Required:

        - Application Update'
      parameters:
      - $ref: '#/components/parameters/WorkflowPath'
      - $ref: '#/components/parameters/TimerStartNodePath'
      responses:
        '200':
          description: TimerStart node sucessfully started
        '404':
          description: Timer start node not found'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowPath}/timerstart/{timerStartNodePath}/stop:
    post:
      x-unqork-service: true
      tags:
      - Workflow
      summary: Stop a Timer Start Node
      operationId: stopTimerStartNode
      description: 'Trigger a timer start node to stop which will cancel the scheduled creation and execution of workflow submissions

        ### Authorization Required:

        - Application Update'
      parameters:
      - $ref: '#/components/parameters/WorkflowPath'
      - $ref: '#/components/parameters/TimerStartNodePath'
      responses:
        '200':
          description: Deleted {deleteCount} start timer node queued jobs
        '404':
          description: Timer start node not found
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowPath}/timerstart/{timerStartNodePath}/run-once:
    post:
      x-unqork-service: true
      tags:
      - Workflow
      summary: Run a Timer Start Node Once (Test Run)
      operationId: runTimerStartNodeOnce
      description: 'Trigger a timer start node to run once (test run) which will create and execute a workflow submission a single time

        ### Authorization Required:

        - Application Update'
      parameters:
      - $ref: '#/components/parameters/WorkflowPath'
      - $ref: '#/components/parameters/TimerStartNodePath'
      responses:
        '200':
          description: TimerStart node sucessfully started for single run
        '404':
          description: Timer start node not found
        '400':
          description: TimerStart run once is already running
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflow-execute/{workflowPath}:
    post:
      x-unqork-service: true
      tags:
      - Workflow
      summary: Create Workflow Submission
      operationId: createWorkflowSubmission
      description: 'Creates a new workflow submission. Submission ID is auto-generated and returned. Workflow submission data must be provided as a JSON object. The default start node will be used.

        ### Authorization Required:

        - Application View or Express Read'
      parameters:
      - $ref: '#/components/parameters/WorkflowPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowStartRequest'
      responses:
        '200':
          description: Submissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowCreateSubmissionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflow-execute/{workflowPath}/{stepPath}:
    post:
      x-unqork-service: true
      tags:
      - Workflow
      summary: Create Workflow Submission from Step
      operationId: createWorkflowSubmissionFromStep
      description: 'Creates a new workflow submission. Submission ID is auto-generated and returned. Workflow submission data must be provided as a JSON object.

        ### Authorization Required:

        - Application View or Express Read'
      parameters:
      - $ref: '#/components/parameters/WorkflowPath'
      - $ref: '#/components/parameters/StepPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowStartRequest'
      responses:
        '200':
          description: Submissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowCreateSubmissionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflow-execute/{workflowPath}/resume/{resumePathName}/submission/{submissionId}:
    post:
      x-unqork-service: true
      tags:
      - Workflow
      summary: Resume workflow
      operationId: resumeWorkflow
      description: 'Resume a workflow that has encountered a Service Task.

        ### Authorization Required:

        - See Submission Access (Submission Access)'
      parameters:
      - name: workflowPath
        in: path
        description: Path of the workflow that is being loaded
        required: true
        schema:
          type: string
      - name: resumePathName
        in: path
        description: Service Task path
        required: true
        schema:
          type: string
      - name: submissionId
        in: path
        description: ID of submission to use.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeWorkflowRequest'
      responses:
        '200':
          description: Workflow advanced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeWorkflowResponse'
        default:
          description: Failed to advance workflow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedResumeWorkflowResponse'
  /workflow/{workflowPath}/handoff:
    put:
      x-unqork-service: true
      tags:
      - Workflow
      summary: Handoff submission
      operationId: handoffSubmission
      description: 'Hands off existing submission to specified workflow. This endpoint is available to "Administrator" users only.

        ### Authorization Required:

        - Express Super User or Designer Administrator'
      parameters:
      - name: workflowPath
        in: path
        description: Path of the workflow to handoff submission
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandoffSubmissionToWorkflowRequest'
      responses:
        '200':
          description: Successfully handed off submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandoffSubmissionToWorkflowResponse'
        default:
          description: Failed to hand off submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedHandoffSubmissionToWorkflowResponse'
  /workflows/{workflowId}/restore:
    post:
      tags:
      - Workflow
      summary: Restore a Deleted Workflow
      operationId: restoreDeletedWorkflow
      description: 'Restores a soft-deleted workflow

        ### Authorization Required:

        - Application Create'
      parameters:
      - name: workflowId
        in: path
        description: ID of workflow to restore
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully Restored
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: Error
      required:
      - code
      - message
      properties:
        code:
          description: HTTP status code
          type: integer
          format: int32
          enum:
          - 400
          - 401
          - 403
          - 404
          - 412
          - 500
        message:
          description: Error message
          type: string
    FailedHandoffSubmissionToWorkflowResponse:
      type: object
      description: Handoff Submission Workflow Validation and/or execution error
      properties:
        submissionId:
          type: string
          description: ID of submission
        statusCode:
          type: integer
          format: int32
          enum:
          - 400
          - 401
          - 403
          - 404
          - 412
          - 500
        message:
          description: Error message
          type: string
        formattedError:
          type: object
          properties:
            validationErrors:
              $ref: '#/components/schemas/ValidationErrors'
            invalidNavigationPanels:
              $ref: '#/components/schemas/InvalidNavigationPanels'
            executionError:
              $ref: '#/components/schemas/ExecutionError'
    RetrievedTimedEventsBySubmissionIdResponse:
      type: array
      description: List of timed event actions and their statuses in a particular workflow submission
      items:
        type: object
        properties:
          startTime:
            type: string
            format: date-time
            description: Date-Time the timed event action was queued
          endTime:
            type: string
            format: date-time
            description: Date-Time the timed event action was completed
          executionTime:
            type: string
            format: date-time
            description: Date-Time the timed event action is set to be exectued
          label:
            type: string
            description: The label of the timed event action, if provided
          status:
            type: string
            description: The current status of the timed event action (ACTIVE, CANCELLED, EXECUTED, EXECUTION_FAILED, SLA_TRACKING_ERROR)
          actionType:
            type: string
            description: The type of the action (message, changePath)
          duration:
            type: object
            description: The configured duration on the timed event action
            properties:
              days:
                type: string
              hours:
                type: string
              minutes:
                type: string
          timedEventNode:
            type: string
            description: Path of the timed event node the action is part of
          parentNode:
            type: string
            description: The Task or Subprocess node that triggered the action to be queued
          totalDurationSeconds:
            type: integer
            format: int32
            description: The calculated duration to wait before executing the action, in seconds
    FailedResumeWorkflowResponse:
      type: object
      description: Resume Workflow Validation and/or execution error
      properties:
        submissionId:
          type: string
          description: ID of submission
        state:
          type: string
          description: Current state of the submission
        statusCode:
          description: Error codes or custom http status codes if returned for api modules
          type: integer
          format: int32
          enum:
          - 400
          - 401
          - 403
          - 404
          - 412
          - 500
        message:
          description: Error message
          type: string
        formattedError:
          type: object
          properties:
            validationErrors:
              $ref: '#/components/schemas/ValidationErrors'
            invalidNavigationPanels:
              $ref: '#/components/schemas/InvalidNavigationPanels'
            executionError:
              $ref: '#/components/schemas/ExecutionError'
    ValidationErrors:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          path:
            type: string
          label:
            type: string
          parent:
            type: string
          message:
            type: string
    ResumeWorkflowResponse:
      type: object
      properties:
        submissionId:
          type: string
          description: ID of submission
        state:
          type: string
          description: Current state of the submission
        statusCode:
          type: integer
          format: int32
          enum:
          - 200
        submission:
          type: object
          description: Submission data
    SavedSubmissionResponse:
      type: object
      required:
      - id
      - moduleId
      - created
      - modified
      properties:
        id:
          type: string
        userId:
          type: string
          description: Submission owner
        moduleId:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        deleted:
          type: string
          format: date-time
        data:
          type: object
          description: Raw output data
          properties:
            rawData:
              type: object
        metadata:
          type: object
        validationErrors:
          $ref: '#/components/schemas/ValidationErrors'
    ExecutionError:
      type: object
      properties:
        type:
          type: string
        url:
          type: string
        component:
          type: string
        message:
          type: string
        code:
          type: integer
    HandoffSubmissionToWorkflowResponse:
      type: object
      properties:
        submissionId:
          type: string
          description: ID of submission
        workflowId:
          type: string
          description: ID of workflow after handoff
        state:
          type: string
          description: Current state of the submission
        statusCode:
          type: integer
          format: int32
          enum:
          - 200
        submission:
          type: object
          description: Submission data
    WorkflowCreateSubmissionResponse:
      type: object
      properties:
        submissionId:
          type: string
          description: ID of submission
        submission:
          $ref: '#/components/schemas/SavedSubmissionResponse'
        statusCode:
          type: integer
          description: Error or success response code
    InvalidNavigationPanels:
      type: array
      items:
        type: object
        properties:
          key:
            type: string
          label:
            type: string
    HandoffSubmissionToWorkflowRequest:
      type: object
      required:
      - submissionId
      properties:
        submissionId:
          type: string
          description: ID of submission to use.
        startNode:
          type: string
          description: Path of the start node in handoff workflow. Default start node will be used when startNode is not provided.
    WorkflowStartRequest:
      type: object
      properties:
        userId:
          type: string
          description: Submission owner
        data:
          description: Raw data to include in submission.
          type: object
    ResumeWorkflowRequest:
      type: object
      properties:
        data:
          description: Raw data to include in submission.
          type: object
    RetrievedTimerStartResponse:
      type: object
      description: List of timer start nodes and their statuses in a particular workflow
      properties:
        path:
          type: string
          description: workflow path
        nodes:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: timer start node name
              path:
                type: string
                description: timer start node path
              started:
                type: boolean
                description: whether a timer start node is active or not
        statusCode:
          type: integer
          format: int32
          enum:
          - 200
  parameters:
    TimerStartNodePath:
      name: timerStartNodePath
      in: path
      description: Unique path of a timer start node in a workflow
      required: true
      schema:
        type: string
    WorkflowPath:
      name: workflowPath
      in: path
      description: Unique workflow path
      required: true
      schema:
        type: string
    StepPath:
      name: stepPath
      in: path
      description: Unique path of workflow step, usually "start"
      required: true
      schema:
        type: string
  securitySchemes:
    OAuth2:
      description: "The Unqork API implements the [OAuth 2.0 Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4) and the [OAuth 2.0 Password Grant](https://tools.ietf.org/html/rfc6749#section-1.3.3). Access via OAuth2 Client Credentials Grant can be utilized by creating Client Credentials through the API Access Management Administration page. Access via OAuth2 Password Grant can be enabled for all users in Environment Administration. Once OAuth2 Password Grant is enabled, all Unqork users can use their Unqork username/password to retrieve an access token.\n\nIn order to utilize any of the API resources, you must first retrieve an access token by POSTing your credentials to the access token URL, e.g. using `curl`:\n```\n  $ curl -u '{clientId}:{clientSecret}' -X POST --basic https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=client_credentials\"\n```\nOr:\n```\n  $ curl -X POST https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=password&username={username}&password={password}\"\n```\nThis returns an \"access_token\", which you would then retain and use in any subsequent resource requests. **Access tokens expire after one hour, at which point you must retrieve a new one.** The access token should be included in a request header:\n```\n  $ curl -H \"Authorization: Bearer {access_token}\" https://xyzfinancial.unqork.io/api/1.0/{endpoint}\n```\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A
        password:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A