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: "\nUnqork'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. You can use any web development language to access the API, as communication is over secured HTTP.\n## URI Structure and Methods\nAll API communication will occur over SSL (HTTPS). All API responses are in JSON format.\nAll Unqork requests begin with the prefix:\n\n```\n  https://{yourSubdomain}.unqork.io/api/1.0\n```\n\nFor example, if your subdomain is **xyzfinancial**, you would use the prefix `https://xyzfinancial.unqork.io/api/1.0`.\n\nThe next segment of the URI path will vary based on the endpoint of the request.\n\nA given endpoint (resource) has a series of actions (methods) associated with it. The Unqork API supports these standard HTTP methods:\n\n- **GET** - retrieves data\n\n- **PUT** - updates existing data\n\n- **POST** - creates new data\n\n- **DELETE** - deletes existing data\n\nFor example, you can use the POST action on the module submission resource to create a new module submission.\n## Paging\nPaged endpoints use the [Link header](https://www.w3.org/wiki/LinkHeader). If the link header \"next\" is present, then there are more items to retrieve, and the \"next\" should be followed.\n## Cloud Storage Delivery\nUnqork exposes generated PDFs, uploaded attachments, and other file-like pieces of submission data via Cloud Storage Delivery URLs. These are signed, expiring links that allow the user to securely retrieve files stored in Unqork. Links can appear inside raw submission data, or they can be returned from PDF transform submission endpoints.\n\nThese links cannot be shared with other parties; only the user who generates the unique link (by either submitting the file or accessing the submission where the file has been saved) will be able to use that specifically generated link. This means that the user must be authenticated (either in the browser, or by passing a valid OAuth Bearer token) in order to retrieve the file.\n\nCloud Storage Delivery URLs will look like this:\n\n`https://xyzfinancial.unqork.io/fbu/files/{filePath}?signature={signature}`\n\nThe file can be retrieved by accessing the link in the browser, or like this:\n\n```\n  $ curl -H \"Authorization: Bearer {access_token}\" https://xyzfinancial.unqork.io/fbu/files/{filePath}?signature={signature}\n```\n## Nomenclature\nPreviously, \"Modules\" were called \"Forms\". This nomenclature change affects all endpoints documented here in paths, request parameters, and response bodies (e.g. `forms -> modules`, `formId -> moduleId`; however, the behaviors of the endpoints are the same. The previous endpoints will continue to be supported, but they will be deprecated in the future.\n## API Access Notes\n#### Express Module and Workflow Access <a name=\"express-module-workflow-access\"></a>\nExpress Module and Workflow Access is determined by a User's Role and the Module's permissions. An Express User's Role is specified at the environment level, but can be overwritten at the Application level using Application Roles. If Module Permissions are used, the permission settings will specify what access (Read, Write, Obfuscate, or None) a User will have to the Module. Anonymous Users may also be able to access a Module if the permission settings allow it.\n#### Submission Access <a name=\"submission-access\"></a>\nSubmission Access is determined by a User's Role, Groups, and if they are the owner of the Submission. A Submission owner is the user that created or updated the Submission. If a user is a Submission owner, Designer Administrator, or an Express Super User, the user has access to the Submission. If the User does not have access to the Module or Workflow that the Submission is associated with, then the User will not have access to the Submission. See Express Module and Workflow Access ([Express Module and Workflow Access](#express-module-workflow-access)). A User's Role Groups can also provide a User Access to a Submission. A User needs to have Intersecting Groups with the Submission Owner. Intersecting Groups means a User has a Role with a Group (Groups assigned directly to the User do not count) that is in the Submission owner's groups (the Submission owners Role Groups or the Submission owners User Groups). If a User has Intersecting Groups:\n- And the Group type is ignore role, a User that has Intersecting Groups can access the Submission.\n- And the Group type is Role descendents, a User that has Intersecting Groups and the Submission owner's Role is a descendant of the User's Role then the User can access the Submission.\n- And the Group type is own Role and descendents, a User that has Intersecting Groups and the Submission owner's Role is a descendent of the User's Role or the User's Role is the same as the Submission owner's Role then the User can access the Submission.\n"
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\n### Authorization Required:\n  - Application View\n"
      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\n### Authorization Required:\n  - See Submission Access ([Submission Access](#submission-access))\n"
      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\n### Authorization Required:\n  - Application Update\n"
      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\n### Authorization Required:\n  - Application Update\n"
      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\n### Authorization Required:\n  - Application Update\n"
      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.\n### Authorization Required:\n  - Application View or Express Read\n"
      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.\n### Authorization Required:\n  - Application View or Express Read\n"
      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.\n### Authorization Required:\n  - See Submission Access ([Submission Access](#submission-access))\n"
      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.\n### Authorization Required:\n  - Express Super User or Designer Administrator\n"
      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\n### Authorization Required:\n  - Application Create\n"
      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:
    ExecutionError:
      type: object
      properties:
        type:
          type: string
        url:
          type: string
        component:
          type: string
        message:
          type: string
        code:
          type: integer
    InvalidNavigationPanels:
      type: array
      items:
        type: object
        properties:
          key:
            type: string
          label:
            type: string
    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
    ValidationErrors:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          path:
            type: string
          label:
            type: string
          parent:
            type: string
          message:
            type: string
    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
    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'
    WorkflowStartRequest:
      type: object
      properties:
        userId:
          type: string
          description: Submission owner
        data:
          description: Raw data to include in submission.
          type: object
    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'
    ResumeWorkflowRequest:
      type: object
      properties:
        data:
          description: Raw data to include in submission.
          type: object
    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
    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
    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.
    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
  parameters:
    StepPath:
      name: stepPath
      in: path
      description: Unique path of workflow step, usually "start"
      required: true
      schema:
        type: string
    WorkflowPath:
      name: workflowPath
      in: path
      description: Unique workflow path
      required: true
      schema:
        type: string
    TimerStartNodePath:
      name: timerStartNodePath
      in: path
      description: Unique path of a timer start node in a workflow
      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