cr-connect-workflow/crc/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: crc.api.all_studies
      summary: Provides a list of studies related to the current user.
      tags:
        - Studies
      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}:
    get:
      operationId: crc.api.get_study
      summary: Provides a single study
      tags:
        - Studies
      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 Study Object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Study"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /study-update/{study_id}:
    post:
      operationId: crc.api.post_update_study_from_protocol_builder
      summary: If the study is up-to-date with Protocol Builder, returns a 304 Not Modified. If out of date, return a 202 Accepted and study state changes to updating.
      tags:
        - Study Status
      parameters:
        - name: study_id
          in: path
          required: true
          description: The id of the study that should be checked for updates.
          schema:
            type: integer
            format: int32
      responses:
        '304':
          description: Study is currently up to date and does not need to be reloaded from Protocol Builder
        '202':
          description: Request accepted, will preform an update. Study state set to "updating"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /study/{study_id}/workflows:
    get:
      operationId: crc.api.get_study_workflows
      summary: Provides a list of workflows to be completed for the given study.
      tags:
        - Studies
      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 workflows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Workflow"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      operationId: crc.api.add_workflow_to_study
      summary: Starts a new workflow for the given study using the provided spec.  This is atypical, and should be left to the protocol builder.
      tags:
        - Studies
      parameters:
        - name: study_id
          in: path
          required: true
          description: The id of the study for which a workflow should start
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowSpec'
      responses:
        '200':
          description: An array of workflows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Workflow"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  # /v1.0/workflow/0
  /workflow-specification:
    get:
      operationId: crc.api.all_specifications
      summary: Provides a list of workflows specifications that can be added to a study manually. Please note that Protocol Builder will handle this most of the time.
      tags:
        - Workflow Specifications
      responses:
        '200':
          description: An array of workflow specifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkflowSpec"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    # /v1.0/workflow/0
  /workflow/{workflow_id}:
    get:
      operationId: crc.api.get_workflow
      summary: Detailed information 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/task/0
  /workflow/{workflow_id}/task/{task_id}:
    get:
      operationId: crc.api.get_task
      summary: Get details 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: string
      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"

    put:
      operationId: crc.api.update_task
      summary: Update, attempt to complete a workflow task
      tags:
        - Workflows and Tasks
      parameters:
        - in: body
          name: task
          schema:
            $ref: '#/components/schemas/Task'
        - 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: string
      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"
    WorkflowSpec:
      properties:
        id:
          type: string
        display_name:
          type: string
        description:
          type: string
        bpmn_url:
          type: string
        svg_url:
          type: string
    Workflow:
      properties:
        id:
          readOnly: true
          type: integer
          format: int64
        status:
          type: enum
          enum: ['user_input_required','waiting','complete']
        study_id:
          readOnly: true
          type: integer
        workflow_spec:
          $ref: "#/components/schemas/WorkflowSpec"
        current_task_ids:
          type: array
          items:
            type: String
        messages:
          type: array
          items:
            type: String
      example:
        id: 291234
        status: 'user_input_required'
        current_task_ids: ['study_identification','Detailed Reports']
        workflow_spec:
          id: 'prot_def'
          display_name: 'Protocol Definition'
          description: 'Collect some additional information about your protocol to complete forms and processes.'
          bpmn_url: 'https://crconnect.viriginia.edu/prot_def.bpmn'
          svg_url: 'https://crconnect.viriginia.edu/prot_def.svg'
        messages: [
          "Protocol Builder reports that the protocol process is complete for this study.",
          "IDS Submission Template was generated successfully."
        ]
    Task:
      properties:
        id:
          readOnly: true
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
        form:
          $ref: "#/components/schemas/Form"
      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"
            }
          }
        }
    Form:
      properties:
        fields:
          type: array
          items:
            $ref: "#/components/schemas/Field"
    Field:
      properties:
        id:
          type: string
          readOnly: true
        label:
          type: string
          readOnly: true
        type:
          type: enum
          enum: ['text','number', 'enum']
          readOnly: true
        options:
          type: array
          items:
            type: string
          readOnly: true
        value:
          type: string
    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."