cr-connect-workflow/crc/api.yml

openapi: "3.0.2"
info:
  version: 1.0.0
  title: Workflow Microservice
  license:
    name: MIT
servers:
  - url: http://localhost:5000/v1.0
security:
  - jwt: ['secret']
paths:
  /sso_backdoor:
    get:
      operationId: crc.api.user.backdoor
      summary: A backdoor that allows someone to log in as a specific user, if they
        are in a staging environment.
      security: []  # Disable security for this endpoint only.
      parameters:
        - name: uid
          in: query
          required: true
          schema:
            type: string
        - name: email_address
          in: query
          required: false
          schema:
            type: string
        - name: display_name
          in: query
          required: false
          schema:
            type: string
        - name: affiliation
          in: query
          required: false
          schema:
            type: string
        - name: eppn
          in: query
          required: false
          schema:
            type: string
        - name: first_name
          in: query
          required: false
          schema:
            type: string
        - name: last_name
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          required: false
          schema:
            type: string
        - name: redirect_url
          in: query
          required: false
          schema:
            type: string
      tags:
        - Users
      responses:
        '304':
          description: Redirection to the hosted frontend with an auth_token header.
  /user:
    get:
      operationId: crc.api.user.get_current_user
      summary: Returns the current user.
      tags:
        - Users
      responses:
        '200':
          description: The currently authenticated user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
  # /v1.0/study
  /study:
    get:
      operationId: crc.api.study.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"
    post:
      operationId: crc.api.study.add_study
      summary: Creates a new study with the given parameters.
      tags:
        - Studies
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Study'
      responses:
        '200':
          description: Study created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Study"
  /study/{study_id}:
    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
    get:
      operationId: crc.api.study.get_study
      summary: Provides a single study
      tags:
        - Studies
      responses:
        '200':
          description: An Study Object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Study"
    delete:
      operationId: crc.api.study.delete_study
      summary: Removes the given study completely.
      tags:
        - Studies
      responses:
        '204':
          description: The study has been removed.
    put:
      operationId: crc.api.study.update_study
      summary: Updates an existing study with the given parameters.
      tags:
        - Studies
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Study'
      responses:
        '200':
          description: Study updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Study"
  /study-update/{study_id}:
    post:
      operationId: crc.api.study.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"
  /study/{study_id}/workflows:
    get:
      operationId: crc.api.study.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"
    post:
      operationId: crc.api.study.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"
  /workflow-specification:
    get:
      operationId: crc.api.workflow.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"
    post:
      operationId: crc.api.workflow.add_workflow_specification
      summary: Creates a new workflow specification with the given parameters.
      tags:
        - Workflow Specifications
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowSpec'
      responses:
        '200':
          description: Workflow specification created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowSpec"
  /workflow-specification/{spec_id}:
    parameters:
      - name: spec_id
        in: path
        required: false
        description: The unique id of an existing workflow specification to modify.
        schema:
          type: string
    get:
      operationId: crc.api.workflow.get_workflow_specification
      summary: Returns a single workflow specification
      tags:
        - Workflow Specifications
      responses:
        '200':
          description: Workflow specification.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowSpec"
    put:
      operationId: crc.api.workflow.update_workflow_specification
      summary: Modifies an existing workflow specification with the given parameters.
      tags:
        - Workflow Specifications
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowSpec'
      responses:
        '200':
          description: Workflow specification created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowSpec"
    delete:
      operationId: crc.api.workflow.delete_workflow_specification
      summary: Removes an existing workflow specification
      tags:
        - Workflow Specifications
      responses:
        '204':
          description: The workflow specification has been removed.
  /workflow-specification-category:
    get:
      operationId: crc.api.workflow.list_workflow_spec_categories
      summary: Provides a list of categories that can be added to a workflow spec.
      tags:
        - Workflow Specifications
      responses:
        '200':
          description: An array of workflow specification categories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkflowSpecCategory"
    post:
      operationId: crc.api.workflow.add_workflow_spec_category
      summary: Creates a new workflow spec category with the given parameters.
      tags:
        - Workflow Specifications
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowSpecCategory'
      responses:
        '200':
          description: Workflow spec category created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowSpecCategory"
  /workflow-specification-category/{cat_id}:
    parameters:
      - name: cat_id
        in: path
        required: false
        description: The unique id of an existing workflow spec category to modify.
        schema:
          type: string
    get:
      operationId: crc.api.workflow.get_workflow_spec_category
      summary: Returns a single workflow spec category
      tags:
        - Workflow Specifications
      responses:
        '200':
          description: Workflow spec category.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowSpecCategory"
    put:
      operationId: crc.api.workflow.update_workflow_spec_category
      summary: Modifies an existing workflow spec category with the given parameters.
      tags:
        - Workflow Specifications
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowSpecCategory'
      responses:
        '200':
          description: Workflow spec category created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowSpecCategory"
    delete:
      operationId: crc.api.workflow.delete_workflow_spec_category
      summary: Removes an existing workflow spec category
      tags:
        - Workflow Specifications
      responses:
        '204':
          description: The workflow spec category has been removed.
  /file:
    parameters:
      - name: workflow_spec_id
        in: query
        required: false
        description: The unique id of a workflow specification
        schema:
          type: string
      - name: study_id
        in: query
        required: false
        description: The unique id of a study
        schema:
          type: integer
      - name: workflow_id
        in: query
        required: false
        description: The unique id of a workflow instance
        schema:
          type: integer
      - name: task_id
        in: query
        required: false
        description: The unique id of a workflow task
        schema:
          type: string
      - name: form_field_key
        in: query
        required: false
        description: The unique key of a workflow task form field.  Make sure this matches a document in the irb_documents.xslx reference sheet.
        schema:
          type: string
    get:
      operationId: crc.api.file.get_files
      summary: Provides a list of files that match the given parameters (such as a spec id) IMPORTANT, only includes metadata, not the file content.
      tags:
        - Files
      responses:
        '200':
          description: An array of file descriptions (not the file content)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/File"

    post:
      operationId: crc.api.file.add_file
      summary: Add a new file
      tags:
        - Files
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Metadata about the uploaded file, but not the file content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
  /file/{file_id}:
    parameters:
      - name: file_id
        in: path
        required: true
        description: The id of the File requested
        schema:
          type: integer
    get:
      operationId: crc.api.file.get_file_info
      summary: Returns metadata about a file.
      tags:
        - Files
      responses:
        '200':
          description: Returns the file information requested.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
    put:
      operationId: crc.api.file.update_file_info
      summary: Updates existing file info with the given parameters.
      tags:
        - Files
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/File'
      responses:
        '200':
          description: File info updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
    delete:
      operationId: crc.api.file.delete_file
      summary: Removes an existing file
      tags:
        - Files
      responses:
        '204':
          description: The file has been removed.
  /file/{file_id}/data:
    parameters:
      - name: file_id
        in: path
        required: true
        description: The id of the File requested
        schema:
          type: integer
    get:
      operationId: crc.api.file.get_file_data
      summary: Returns only the file contents
      tags:
        - Files
      responses:
        '200':
          description: Returns the actual file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: '<?xml version="1.0" encoding="UTF-8"?><bpmn:definitions></bpmn:definitions>'
    put:
      operationId: crc.api.file.update_file_data
      summary: Update only the file contents for a given file
      tags:
        - Files
      requestBody:
        content:
          multipart/form-data:
            schema:
              x-body-name: file
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
                - file
      responses:
        '200':
          description: Returns the updated file model with the new version information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/File"
  # /v1.0/workflow/0
  /reference_file:
    get:
      operationId: crc.api.file.get_reference_files
      summary: Provides a list of existing reference files that are available in the system.
      tags:
        - Files
      responses:
        '200':
          description: An array of file descriptions (not the file content)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/File"
  /reference_file/{name}:
    parameters:
      - name: name
        in: path
        required: true
        description: The special name of the reference file.
        schema:
          type: string
    get:
      operationId: crc.api.file.get_reference_file
      summary: Reference files are called by name rather than by id.
      tags:
        - Files
      responses:
        '200':
          description: Returns the actual file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: '<?xml version="1.0" encoding="UTF-8"?><bpmn:definitions></bpmn:definitions>'
    put:
      operationId: crc.api.file.set_reference_file
      summary: Update the contents of a named reference file.
      tags:
        - Files
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Returns the actual file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: '<?xml version="1.0" encoding="UTF-8"?><bpmn:definitions></bpmn:definitions>'
  # /v1.0/workflow/0
  /workflow/{workflow_id}:
    parameters:
        - name: workflow_id
          in: path
          required: true
          description: The id of the workflow
          schema:
            type: integer
            format: int32
    get:
      operationId: crc.api.workflow.get_workflow
      summary: Detailed information for a specific workflow instance
      parameters:
        - name: soft_reset
          in: query
          required: false
          description: Set this to true to use the latest workflow specification to load minor modifications to the spec.
          schema:
            type: boolean
        - name: hard_reset
          in: query
          required: false
          description: Set this to true to reset the workflow
          schema:
            type: boolean
      tags:
        - Workflows and Tasks
      responses:
        '200':
          description: Returns details about the workflows state and current task
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
    delete:
      operationId: crc.api.workflow.delete
      summary: Removes an existing workflow
      tags:
        - Workflows and Tasks
      responses:
        '204':
          description: The workflow was removed
  /workflow/{workflow_id}/stats:
    parameters:
        - name: workflow_id
          in: path
          required: true
          description: The id of the workflow
          schema:
            type: integer
            format: int32
    get:
      operationId: crc.api.stats.get_workflow_stats
      summary: Stats about a given workflow
      tags:
        - Workflows and Tasks
      responses:
        '200':
          description: Returns counts of complete, incomplete, and total number of tasks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
  # /v1.0/workflow/0/task/0
  /workflow/{workflow_id}/task/{task_id}:
    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
          format: uuid
    get:
      operationId: crc.api.workflow.get_task
      summary: Get details of specific task in specific workflow instance
      tags:
        - Workflows and Tasks
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
  /workflow/{workflow_id}/task/{task_id}/data:
    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
          format: uuid
    put:
      operationId: crc.api.workflow.update_task
      summary: Exclusively for User Tasks, submits form data as a flat set of key/values.
      tags:
        - Workflows and Tasks
      requestBody:
        description: Key / Value pairs in JSON format.
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                favorite_color: blue
                capital_assyria: Assur
      responses:
        '201':
          description: Returns the updated workflow with the task completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
  /render_markdown:
    parameters:
      - name: data
        in: query
        required: true
        description: The json data to use in populating the template
        schema:
          type: string
      - name: template
        in: query
        required: true
        description: The markdown template to process.
        schema:
          type: string
    get:
      operationId: crc.api.tools.render_markdown
      security: []  # Disable security for this endpoint only.
      summary: Processes the markdown template using the data provided.
      tags:
        - Configurator Tools
      responses:
        '201':
          description: Returns the updated workflow with the task completed.
          content:
            text/plain:
              schema:
                type: string
  /render_docx:
    parameters:
      - name: data
        in: query
        required: true
        description: The json data to use in populating the template
        schema:
          type: string
    put:
      operationId: crc.api.tools.render_docx
      security: []  # Disable security for this endpoint only.
      summary: Renders a docx template with embedded jinja2 markup.
      tags:
        - Configurator Tools
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Returns the generated document.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                example: '<?xml version="1.0" encoding="UTF-8"?><bpmn:definitions></bpmn:definitions>'
  /list_scripts:
    get:
      operationId: crc.api.tools.list_scripts
      security: []  # Disable security for this endpoint only.
      summary: Returns an list of scripts, along with their descriptions
      tags:
        - Configurator Tools
      responses:
        '201':
          description: The list of scripts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Script"
components:
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      x-bearerInfoFunc: crc.api.user.verify_token
  schemas:
    User:
      properties:
        uid:
          type: string
        email_address:
          type: string
        display_name:
          type: string
        affiliation:
          type: string
        eppn:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        title:
          type: string
    DataModel:
      properties:
        id:
          type: string
    Study:
      properties:
        id:
          type: integer
          example: 1234
        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"
        protocol_builder_status:
          type: string
          enum: [DRAFT, IN_PROCESS, IN_REVIEW, REVIEW_COMPLETE, INACTIVE]
          example: done
        user_uid:
          type: string
          example: dhf8r
        primary_investigator_id:
          type: string
          example: dhf8r
        sponsor:
          type: string
          example: "Sartography Pharmaceuticals"
        ind_number:
          type: string
          example: "27b-6-42"
    WorkflowSpec:
      properties:
        id:
          type: string
        name:
          type: string
        display_name:
          type: string
        description:
          type: string
        primary_process_id:
          type: string
          nullable: true
        workflow_spec_category_id:
          type: integer
          nullable: true
        workflow_spec_category:
          $ref: "#/components/schemas/WorkflowSpecCategory"
        is_status:
          type: boolean
          nullable: true
    WorkflowSpecCategory:
      properties:
        id:
          type: integer
        name:
          type: string
        display_name:
          type: string
    File:
      properties:
        id:
          type: number
        name:
          type: string
          example: "random_fact.bpmn"
        version:
          type: integer
        last_updated:
          type: string
          format: date_time
          example: "2019-12-25T09:12:33.001Z"
        type:
          type: string
        primary:
          type: boolean
        content_type:
          type: string
          example: "application/xml"
        workflow_spec_id:
          type: string
          example: "random_fact"
          x-nullable: true
        file:
          type: file
          format: binary
    Workflow:
      properties:
        id:
          readOnly: true
          type: integer
          format: int64
        status:
          type: enum
          enum: ['new','user_input_required','waiting','complete']
        user_tasks:
          type: array
          items:
            $ref: "#/components/schemas/Task"
        last_task:
          $ref: "#/components/schemas/Task"
        next_task:
          $ref: "#/components/schemas/Task"
        workflow_spec_id:
          type: string
        spec_version:
          type: string
        is_latest_spec:
          type: boolean
        num_tasks_total:
          type: integer
        num_tasks_complete:
          type: integer
        num_tasks_incomplete:
          type: integer

      example:
        id: 291234
        status: 'user_input_required'
        workflow_spec_id: 'random_fact'
        spec_version: 'v1.1 [22,23]'
        is_latest_spec: True
        next_task:
          id: study_identification
          name: Study Identification
          title: IRB Review
          documentation: "# Heading 1\n\nMarkdown documentation text goes here"
          type: form
          state: ready
    Task:
      properties:
        id:
          readOnly: true
          type: string
        name:
          type: string
        title:
          type: string
        type:
          type: string
        state:
          type: string
        form:
          $ref: "#/components/schemas/Form"
        documentation:
          type: string
      example:
        id: study_identification
        name: Study Identification
        title: IRB Review
        documentation: "# Heading 1\n\nMarkdown documentation text goes here"
        type: form
        state: ready
        form:
          "key": "irb_review_form"
          "fields":
            - "id": "irb_review_type"
              "type": "enum"
              "label": "Select IRB Review Type"
              "options":
                - id: "emergency_use"
                  name: "Emergency Use"
                - id: "humanitarian_device"
                  name: "Humanitarian Device"
                - id: "non_human"
                  name: "Non-Human"
                - id: "non_uva_agent"
                  name: "Non-UVA Agent"
                - id: "exempt"
                  name: "Exempt"
                - id: "non_engaged"
                  name: "Non-Engaged"
                - id: "expedited"
                  name: "Expedited"
                - id: "full_board"
                  name: "Full Board"
              "default_value": "Full Board"
              "validation":
                - name: "required"
                  config: "true"
              "properties":
                - id: "description"
                  value: "Description text goes here"
                - id: "help"
                  value: "# Heading 1\n\nMarkdown help text goes here"
                - id: "required_expression"
                  value: "model.my_boolean_field_id && model.my_enum_field_value !== 'something'"
                - id: "hide_expression"
                  value: "model.my_enum_field_value === 'something'"
    Form:
      properties:
        key:
          type: string
        fields:
          type: array
          items:
            $ref: "#/components/schemas/Field"
      example:
        "key": "irb_review_form"
        "fields":
          - "id": "irb_review_type"
            "type": "enum"
            "label": "Select IRB Review Type"
            "options":
              - id: "emergency_use"
                name: "Emergency Use"
              - id: "humanitarian_device"
                name: "Humanitarian Device"
              - id: "non_human"
                name: "Non-Human"
              - id: "non_uva_agent"
                name: "Non-UVA Agent"
              - id: "exempt"
                name: "Exempt"
              - id: "non_engaged"
                name: "Non-Engaged"
              - id: "expedited"
                name: "Expedited"
              - id: "full_board"
                name: "Full Board"
            "default_value": "Full Board"
            "validation":
              - name: "required"
                config: "true"
            "properties":
              - id: "description"
                value: "Description text goes here"
              - id: "help"
                value: "# Heading 1\n\nMarkdown help text goes here"
              - id: "required_expression"
                value: "model.my_boolean_field_id && model.my_enum_field_value !== 'something'"
              - id: "hide_expression"
                value: "model.my_enum_field_value === 'something'"
    Field:
      properties:
        id:
          type: string
          readOnly: true
        type:
          type: enum
          enum: ['string', 'long', 'boolean', 'date', 'enum']
          readOnly: true
        label:
          type: string
          readOnly: true
        options:
          type: array
          items:
            $ref: "#/components/schemas/EnumFieldOption"
          readOnly: true
        default_value:
          type: string
          readOnly: true
        validation:
          type: array
          items:
            $ref: "#/components/schemas/FieldValidation"
          readOnly: true
        "properties":
          type: array
          items:
            $ref: "#/components/schemas/FieldProperty"
          readOnly: true
    EnumFieldOption:
      properties:
        id:
          type: string
        name:
          type: string
    FieldValidation:
      properties:
        name:
          type: string
        config:
          type: string
    FieldProperty:
      properties:
        id:
          type: string
        value:
          type: string
      example:
        id: "required_expression"
        value: "model.should_require"
    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."
    Script:
      properties:
        name:
          type: string
          format: string
          example: "random_fact"
        description:
          type: string
          example: "Returns a random fact about a topic.  Provide an argument of either 'cat', 'norris', or 'buzzword'"