Opal Workflow Contexts API

openapi: 3.2.0
info:
  version: 3.0.0
  title: Opal API (⚠️ WIP) Workflow Contexts API
  license:
    name: Opal API License
    url: https://www.workwithopal.com/api-license
  description: The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
servers:
- url: https://login.ouropal.com
tags:
- name: Workflow Contexts
paths:
  /v3/workflow_contexts:
    post:
      tags:
      - Workflow Contexts
      operationId: CreateContextV3
      summary: Create a Context
      description: 'Creating a context ties a Workflow to a particular resource that the

        workflow should operate on. Currently, only `moment` or `block` resources

        are supported.


        If the context would refer to a moment-block pairing, both `moment` and

        `block` relationships should be provided when creating a context.'
      security:
      - oauth2:
        - offline_access
      - api_key: []
      parameters:
      - name: include
        in: query
        required: false
        description: A comma separated value of related objects to include.
        schema:
          type: array
          items:
            type: string
            enum:
            - workflow
            - workflow.stages
            - workflow.stages.assignments
        style: form
        explode: false
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - type
                  - attributes
                  - relationships
                  properties:
                    type:
                      type: string
                      enum:
                      - workflow_context
                    attributes:
                      type: object
                      properties: {}
                    relationships:
                      type: object
                      required:
                      - moment
                      - workflow
                      properties:
                        moment:
                          type: object
                          required:
                          - data
                          additionalProperties: false
                          properties:
                            data:
                              type: object
                              required:
                              - id
                              - type
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                type:
                                  type: string
                                  enum:
                                  - moment
                        workflow:
                          type: object
                          required:
                          - data
                          additionalProperties: false
                          properties:
                            data:
                              type: object
                              required:
                              - id
                              - type
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                type:
                                  type: string
                                  enum:
                                  - workflow
            example:
              data:
                id: 4ac02fc7-705c-467e-933e-8bf16fc3ebf1
                type: workflow_context
                attributes: {}
                relationships:
                  workflow:
                    data:
                      id: d7a0168b-edc6-4737-85b6-8b551d1faf99
                      type: workflow
                  block:
                    data:
                      id: f649cebe-3dce-441a-8335-86707303c388
                      type: block
                  moment:
                    data:
                      id: c53fa6f9-b8c5-4238-909c-eb0eb75bdb19
                      type: moment
      responses:
        '201':
          description: Context created
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    title: workflow_context
                    type: object
                    additionalProperties: false
                    required:
                    - id
                    - type
                    - attributes
                    - relationships
                    properties:
                      id:
                        type: string
                        format: uuid
                      type:
                        type: string
                        enum:
                        - workflow_context
                      attributes:
                        type: object
                        additionalProperties: false
                        required:
                        - created_at
                        - updated_at
                        properties:
                          created_at:
                            type: string
                            format: date-time
                            description: An ISO8601 date-time.
                            readOnly: true
                          updated_at:
                            type: string
                            format: date-time
                            description: An ISO8601 date-time.
                            readOnly: true
                      relationships:
                        type: object
                        additionalProperties: false
                        required:
                        - block
                        - created_by_user
                        - moment
                        - workflow
                        properties:
                          block:
                            type: object
                            required:
                            - data
                            additionalProperties: false
                            properties:
                              data:
                                type:
                                - object
                                - 'null'
                                required:
                                - id
                                - type
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  type:
                                    type: string
                                    enum:
                                    - block
                          created_by_user:
                            title: User
                            type: object
                            required:
                            - data
                            additionalProperties: false
                            properties:
                              data:
                                type: object
                                required:
                                - id
                                - type
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  type:
                                    type: string
                                    enum:
                                    - user
                          moment:
                            type: object
                            required:
                            - data
                            additionalProperties: false
                            properties:
                              data:
                                type:
                                - object
                                - 'null'
                                required:
                                - id
                                - type
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  type:
                                    type: string
                                    enum:
                                    - moment
                          workflow:
                            type: object
                            required:
                            - data
                            additionalProperties: false
                            properties:
                              data:
                                type: object
                                required:
                                - id
                                - type
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  type:
                                    type: string
                                    enum:
                                    - workflow
                  included:
                    type: array
                    items:
                      oneOf:
                      - title: workflow
                        type: object
                        required:
                        - id
                        - attributes
                        - relationships
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            format: uuid
                          type:
                            type: string
                            enum:
                            - workflow
                          meta:
                            type: object
                            description: 'Optionally calculated workflow status metadata. **Not part of responses by

                              default.**


                              This is currently only available when requesting workflow resources from

                              the `/workflows/v2/workflows` and `/workflows/v2/workflows/{id}` `GET`

                              endpoints. You request that this metadata be included in responses with the

                              `expose` query parameter like:

                              `/workflows/v2/workflows?expose[workflow][meta]`.


                              The "latest active stage" is either the stage that is currently active or

                              it is the last stage of a completed workflow.

                              '
                            required:
                            - latest_active_stage
                            - completed_stages
                            - stage_type_count
                            additionalProperties: false
                            properties:
                              latest_active_stage:
                                oneOf:
                                - title: Stage Status Metadata
                                  allOf:
                                  - required:
                                    - stage_type
                                    - resource_identifier
                                    properties:
                                      stage_type:
                                        type: string
                                        enum:
                                        - approval
                                        - task
                                        - circuit_breaker
                                      title:
                                        type:
                                        - string
                                        - 'null'
                                        description: The title of the stage.
                                      due_date:
                                        type:
                                        - string
                                        - 'null'
                                        format: date-time
                                        description: The due date of the stage if set.
                                      resource_identifier:
                                        type: object
                                        required:
                                        - data
                                        additionalProperties: false
                                        properties:
                                          data:
                                            type: object
                                            required:
                                            - id
                                            - type
                                            additionalProperties: false
                                            properties:
                                              id:
                                                type: string
                                                format: uuid
                                              type:
                                                type: string
                                                enum:
                                                - workflow_stage
                                  - type: object
                                    description: The status metadata of a workflow_stage.
                                    required:
                                    - assignment_counts
                                    properties:
                                      assignment_counts:
                                        type: object
                                        description: 'Assignment counts broken down in three ways.


                                          First, the number of complete/incomplete assignments for all users

                                          (both approvals and tasks).


                                          Second, the number of complete/incomplete assignments for the current

                                          user (both approvals and tasks).


                                          Third, the number of declined approvals.


                                          In the first two cases, both approvals and tasks can be complete or

                                          incomplete where both approved and declined responses on an approval

                                          assignment count as completion.

                                          '
                                        required:
                                        - all
                                        - current_user
                                        - declined
                                        additionalProperties: false
                                        properties:
                                          all:
                                            type: object
                                            required:
                                            - incomplete
                                            - complete
                                            additionalProperties: false
                                            properties:
                                              incomplete:
                                                type: integer
                                                minimum: 0
                                              complete:
                                                type: integer
                                                minimum: 0
                                          current_user:
                                            type: object
                                            required:
                                            - incomplete
                                            - complete
                                            additionalProperties: false
                                            properties:
                                              incomplete:
                                                type: integer
                                                minimum: 0
                                              complete:
                                                type: integer
                                                minimum: 0
                                          declined:
                                            type: integer
                                            minimum: 0
                                - title: 'null'
                                  type:
                                  - object
                                  - 'null'
                                  enum:
                                  - null
                              completed_stages:
                                type: integer
                                minimum: 0
                              stage_type_count:
                                type: object
                                required:
                                - approval
                                - task
                                - circuit_breaker
                                additionalProperties: false
                                properties:
                                  approval:
                                    type: integer
                                    minimum: 0
                                  task:
                                    type: integer
                                    minimum: 0
                                  circuit_breaker:
                                    type: integer
                                    minimum: 0
                          attributes:
                            type: object
                            required:
                            - created_at
                            - status
                            - is_approved
                            - updated_at
                            additionalProperties: false
                            properties:
                              created_at:
                                type: string
                                format: date-time
                                description: An ISO8601 date-time indicating when the workflow was created.
                                readOnly: true
                              status:
                                type: string
                                description: A string indicating the current status of the workflow.
                                enum:
                                - active
                                - complete
                                - inactive
                                - paused
                                readOnly: true
                              is_approved:
                                type: boolean
                                description: 'Indicative of whether the latest approval workflow_stage has been completed.

                                  Workflows with only task workflow_stages will never result in

                                  `is_approved=true`.

                                  '
                                readOnly: true
                              updated_at:
                                type: string
                                format: date-time
                                description: 'An ISO8601 date-time indicating when the workflow was last updated.

                                  '
                                readOnly: true
                          relationships:
                            type: object
                            additionalProperties: false
                            required:
                            - context
                            - created_by_user
                            - stages
                            properties:
                              context:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type:
                                    - object
                                    - 'null'
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                      type:
                                        type: string
                                        enum:
                                        - workflow_context
                              created_by_user:
                                title: User
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: object
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                      type:
                                        type: string
                                        enum:
                                        - user
                              stages:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: array
                                    items:
                                      type: object
                                      required:
                                      - id
                                      - type
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        type:
                                          type: string
                                          enum:
                                          - workflow_stage
              example:
                data:
                  id: 4ac02fc7-705c-467e-933e-8bf16fc3ebf1
                  type: workflow_context
                  attributes:
                    created_at: '2021-01-04T22:23:51Z'
                    updated_at: '2021-01-04T22:23:51Z'
                  relationships:
                    block:
                      data:
                        id: f649cebe-3dce-441a-8335-86707303c388
                        type: block
                    created_by_user:
                      data:
                        id: ada0d59f-9f8c-4df3-ae9c-d6997ab48645
                        type: user
                    moment:
                      data:
                        id: c53fa6f9-b8c5-4238-909c-eb0eb75bdb19
                        type: moment
                    workflow:
                      data:
                        id: d7a0168b-edc6-4737-85b6-8b551d1faf99
                        type: workflow
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The http status code of the error response.
                        title:
                          type: string
                          description: A short, human-readable summary of the error.
                        detail:
                          type: string
                          description: A human-readable explanation of the error.
                        code:
                          type: string
                          description: 'An system-readable error code to provide additional specificity for

                            the error.

                            '
                      required:
                      - status
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The http status code of the error response.
                        title:
                          type: string
                          description: A short, human-readable summary of the error.
                        detail:
                          type: string
                          description: A human-readable explanation of the error.
                        code:
                          type: string
                          description: 'An system-readable error code to provide additional specificity for

                            the error.

                            '
                      required:
                      - status
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The http status code of the error response.
                        title:
                          type: string
                          description: A short, human-readable summary of the error.
                        detail:
                          type: string
                          description: A human-readable explanation of the error.
                        code:
                          type: string
                          description: 'An system-readable error code to provide additional specificity for

                            the error.

                            '
                      required:
                      - status
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The http status code of the error response.
                        title:
                          type: string
                          description: A short, human-readable summary of the error.
                        detail:
                          type: string
                          description: A human-readable explanation of the error.
                        code:
                          type: string
                          description: 'An system-readable error code to provide additional specificity for

                            the error.

                            '
                      required:
                      - status
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'This API uses OAuth 2.0 with the authorization code grant flow. You can

        find more detailed authentication instructions in the [Authentication

        Strategies](/api/documentation#section/Authentication-Strategies/OAuth-2.0)

        section.

        '
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/auth
          tokenUrl: /oauth2/token
          scopes:
            offline_access: Include this scope if you wish to receive a refresh token
    anonymous_oauth:
      type: oauth2
      description: 'The OAuth 2.0 client credentials flow is used for secure server-server

        requests when Opal does not need to associate a request with a particular

        Opal user. These anonymous requests are instead authorized based on the

        OAuth scope.

        '
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            write:onboarding: Include this scope if you wish to make API requests to onboard new Opals.
    api_key:
      type: apiKey
      description: '(Deprecated) This API also supports authentication via an API or session

        token set in the request headers.

        '
      in: header
      name: Session-Token
    presentation_share_cookie:
      type: apiKey
      description: 'A cookie set and read by the Monolith service that authorizes a non-opal

        user to view a presentation and the resources within it. Other services

        can rely on this cookie by asking Monolith to authenticate it.

        '
      in: cookie
      name: share_token
x-tagGroups:
- name: Stable
  tags:
  - Board Collaborators
  - Board Objects
  - Boards
  - Content Schedules
  - Moment Schedules
  - Moments
  - Onboarding
- name: ⚠️  Unstable
  tags:
  - Block Connectors
  - Board Columns
  - Board Duplication
  - Board Standard Columns
  - Channels
  - Custom Field Options
  - Custom Field Types
  - Custom Fields
  - Moment Assignees
  - Moment Custom Fields
  - Planning Status
  - Rich Text Documents
  - User Groups
  - Users
  - Workspaces
- name: ℹ️ Proposed
  tags:
  - Bulk Operations
  - Gem Chats
  - Gem Files
  - Moment Duplication
  - Presentation Themes
  - Workflows
  - Workflow Contexts
  - Workflow Stages
  - Workflow Assignments
  - Workflow Responses
- name: ⚛️ Experimental
  tags:
  - Blocks
  - Block Custom Field Values
  - Block Duplication
  - Board User Settings
  - Categories
  - Category Types
  - Charts
  - Content
  - Custom Field Colors
  - Filter Sets
  - Key Dates
  - View Columns
  - View Standard Columns
  - Views
  - View Colors
  - Stories
- name: Additional Resources
  tags:
  - secondary_resources