cr-connect-workflow/app/api.yml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Workflow Microservice
  license:
    name: MIT
servers:
  - url: http://localhost:5000/v1.0
paths:
  # /v1.0/study
  /study:
    get:
      operationId: app.api.study.list_all
      summary: Provides a list of studies related to the current user.
      tags:
        - Studies and Requirements
      responses:
        '200':
          description: An array of studies, ordered by the last modified date.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Study"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /study/{study_id}/requirement:
    get:
      operationId: app.api.requirements.list_all
      summary: Provides a list of requirements for the study.
      tags:
        - Studies and Requirements
      parameters:
        - name: study_id
          in: path
          required: true
          description: The id of the study for which workflows should be returned.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: An array of requirements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Requirement"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /study/{study_id}/requirement/{requirement_id}:
    post:
      operationId: app.api.study.create_workflow
      summary: Generate a new instance of a workflow, based on a requirement.
      tags:
        - Studies and Requirements
      parameters:
        - name: study_id
          in: path
          required: true
          description: The id of the study for which workflows should be returned.
          schema:
            type: integer
            format: int32
        - name: requirement_id
          in: path
          required: true
          description: The id of the requirement for which to generate or start a new workflow.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Returns a new workflow instance on which to work.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        '412':
          description: You already have a workflow underway to complete this requirement.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # /v1.0/workflow/0
  /workflow/{workflow_id}:
    get:
      operationId: app.api.workflows.getWorkflow
      summary: Status info for a specific workflow instance
      tags:
        - Workflows and Tasks
      parameters:
        - name: workflow_id
          in: path
          required: true
          description: The id of the workflow
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Returns details about the workflows state and current task
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # /v1.0/workflow/0/tasks/0
  /workflow/{workflow_id}/tasks/{task_id}:
    get:
      operationId: app.api.workflows_tasks.get
      summary: Get status of specific task in specific workflow instance
      tags:
        - Workflows and Tasks
      parameters:
        - name: workflow_id
          in: path
          required: true
          description: The id of the workflow
          schema:
            type: integer
            format: int32
        - name: task_id
          in: path
          required: true
          description: The id of the task
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      operationId: app.api.workflows_tasks.post
      summary: Update, attempt to complete a workflow task
      tags:
        - Workflows and Tasks
      parameters:
        - name: workflow_id
          in: path
          required: true
          description: The id of the workflow
          schema:
            type: integer
            format: int32
        - name: task_id
          in: path
          required: true
          description: The id of the task
          schema:
            type: integer
            format: int32
      requestBody:
        description: Task status to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Task"
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"


components:
  schemas:
    Study:
      required:
      - id
      - title
      - last_updated
      - pb_status
      - pi
      - sponsor
      - ind_number
      properties:
        id:
          type: string
          format: string
          example: AB1234
        title:
          type: string
          example: The impact of fried pickles on beer consumption in bipedal software developers.
        last_updated:
          type: string
          format: date_time
          example: "2019-12-25T09:12:33.001Z"
        pb_status:
          type: string
          enum: [started, done]
          example: done
        pi:
          type: string
          example: dhf8r
        sponsor:
          type: string
          example: "Sartography Pharmaceuticals"
        ind_number:
          type: string
          example: "27b-6-42"
    Requirement:
      required:
        - id
        - name
        - type
        - status
        - description
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [workflow, non-functional]
        status:
          type: string
          enum: [new, in-process, complete]
        description:
          type: string
        workflow:
          type: integer
      example:
        id: ids_submission
        name: Investigational Drug Services
        type: workflow
        status: in-process
        description: This workflow will help determine what application needs be provided to IDS, create the template, and submit it for approval.
        workflow_id: 21
    Workflow:
      required:
        - id
        - messages
        - current_status
        - current_task_id
      properties:
        id:
          readOnly: true
          type: integer
          format: int64
        name:
          type: string
        current_status:
          type: enum
          enum: ['user_input_required','waiting','complete']
          $ref: "#/components/schemas/Task"
        current_task_id:
          readOnly: true,
          type: string
      example:
        id: 291234
        requirement_id: ids_submission
        workflow_status: 'user_input_required'
        current_task_id: study_identification
        messages: [
          "Protocol Builder reports that the protocol process is complete for this study.",
          "IDS Submission Template was generated successfully."
        ]
    Task:
      required:
        - id
        - name
        - type
      properties:
        id:
          readOnly: true
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
        form:
          $ref: "#/components/schemas/Task"
      example:
        {
          id: study_identification,
          name: "Study Identification",
          type: form,
          form: {
            field: {
              id: adult_oncology,
              type: enum,
              label: "Is this study treating adult oncology patients?",
              options: ["yes", "no"],
              value: "yes"
            }
          }
        }
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: string
          format: string
          example: "access_denied"
        message:
          type: string
          example: "You do not have permission to view the requested study."