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: /login: get: operationId: crc.api.user.login summary: In production, logs the user in via SSO. If not in production, logs in as a specific user for testing. security: [] # Disable security for this endpoint only. parameters: - name: uid 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.user_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: type: array items: $ref: "#/components/schemas/Study" /study/all: get: operationId: crc.api.study.all_studies summary: Provides a list of studies tags: - Studies responses: '200': description: An array of studies, with submitted files, ordered by the last modified date. content: application/json: schema: type: array items: $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 security: - auth_admin: ['secret'] 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/{study_id}/approvals: 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.approval.get_approvals_for_study summary: Returns approvals for a single study tags: - Studies - Approvals responses: '200': description: An array of approvals content: application/json: schema: type: array items: $ref: "#/components/schemas/Approval" /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 security: - auth_admin: ['secret'] 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 security: - auth_admin: ['secret'] summary: Removes an existing workflow specification tags: - Workflow Specifications responses: '204': description: The workflow specification has been removed. /workflow-specification/{spec_id}/validate: parameters: - name: spec_id in: path required: false description: The unique id of an existing workflow specification to validate. schema: type: string get: operationId: crc.api.workflow.validate_workflow_specification summary: Loads and attempts to execute a Workflow Specification, returning a list of errors encountered tags: - Workflow Specifications responses: '200': description: Workflow specification. content: application/json: schema: type: array items: $ref: "#/components/schemas/Error" /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 Specification Category 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 security: - auth_admin: ['secret'] summary: Creates a new workflow spec category with the given parameters. tags: - Workflow Specification Category 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 Specification Category responses: '200': description: Workflow spec category. content: application/json: schema: $ref: "#/components/schemas/WorkflowSpecCategory" put: operationId: crc.api.workflow.update_workflow_spec_category security: - auth_admin: ['secret'] summary: Modifies an existing workflow spec category with the given parameters. tags: - Workflow Specification Category 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 security: - auth_admin: ['secret'] summary: Removes an existing workflow spec category tags: - Workflow Specification Category 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: workflow_id in: query required: false description: The unique id of a workflow instance schema: type: integer - 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. In the event the file can not be deleted, it is marked as "archived" in the database and is no longer returned unless specifically requested by id. 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 - name: version in: query required: false description: The version of the file, or none for latest version 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: '' 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" /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: '' put: operationId: crc.api.file.set_reference_file security: - auth_admin: ['secret'] 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: '' /task_events: parameters: - name: action in: query required: false description: The type of action the event documents, options include "ASSIGNMENT" for tasks that are waiting on you, "COMPLETE" for things have completed. schema: type: string get: operationId: crc.api.workflow.get_task_events summary: Returns a list of task events related to the current user. Can be filtered by type. tags: - Workflows and Tasks responses: '200': description: Returns details about tasks that are waiting on the current user. content: application/json: schema: $ref: "#/components/schemas/TaskEvent" # /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: Returns a workflow, can also be used to do a soft or hard reset on the workflow. 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_workflow security: - auth_admin: ['secret'] summary: Removes an existing workflow tags: - Workflows and Tasks responses: '204': description: The workflow was removed /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 - name: terminate_loop in: query required: false description: Terminate the loop on a looping task schema: type: boolean 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 this task as the current task. content: application/json: schema: $ref: "#/components/schemas/Workflow" /workflow/{workflow_id}/task/{task_id}/set_token: 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.set_current_task summary: Attempts to make the given task the Current Active Task tags: - Workflows and Tasks responses: '201': description: Returns the updated workflow with this task as the current task. content: application/json: schema: $ref: "#/components/schemas/Workflow" /workflow/{workflow_id}/lookup/{field_id}: parameters: - name: workflow_id in: path required: true description: The id of the workflow schema: type: integer format: int32 - name: field_id in: path required: true description: The id of the field (as set in the bpmn editor) on which to do a lookup. schema: type: string - name: query in: query required: false description: The string to search for in the Value column of the lookup table. schema: type: string - name: value in: query required: false description: An alternative to query, this accepts the specific value or id selected in a dropdown list or auto-complete, and will return the one matching record. Useful for getting additional details about an item selected in a dropdown. schema: type: string - name: limit in: query required: false description: The total number of records to return, defaults to 10. schema: type: integer get: operationId: crc.api.workflow.lookup summary: Provides type-ahead search against a lookup table associted with a form field. tags: - Workflows and Tasks responses: '201': description: Returns the a list of values and labels for a lookup form. content: application/json: schema: $ref: "#/components/schemas/LookupItem" /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 /send_email: parameters: - name: address in: query required: true description: The address to send a test email to. schema: type: string get: operationId: crc.api.tools.send_email summary: Sends an email so we can see if things work or not. tags: - Configurator Tools responses: '201': description: Returns any error messages that might come back from sending the email. content: text/plain: schema: type: string /render_docx: 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 data: type: string format: json responses: '200': description: Returns the generated document. content: application/octet-stream: schema: type: string format: binary example: '' /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" /approval-counts: parameters: - name: as_user in: query required: false description: If provided, returns the approval counts for that user. schema: type: string get: operationId: crc.api.approval.get_approval_counts summary: Provides counts for approvals by status for the given user, or all users if no user is provided tags: - Approvals responses: '200': description: An dictionary of Approval Statuses and the counts for each content: application/json: schema: type: array items: $ref: "#/components/schemas/ApprovalCounts" /all_approvals: parameters: - name: status in: query required: false description: If set to true, returns all the approvals with any status. Defaults to false, leaving out canceled approvals. schema: type: boolean get: operationId: crc.api.approval.get_all_approvals summary: Provides a list of all workflows approvals tags: - Approvals responses: '200': description: An array of approvals content: application/json: schema: type: array items: $ref: "#/components/schemas/Approval" /approval: parameters: - name: status in: query required: false description: If provided, returns just approvals for the given status. schema: type: string - name: as_user in: query required: false description: If provided, returns the approval results as they would appear for that user. schema: type: string get: operationId: crc.api.approval.get_approvals summary: Provides a list of workflows approvals tags: - Approvals responses: '200': description: An array of approvals content: application/json: schema: type: array items: $ref: "#/components/schemas/Approval" /approval/{approval_id}: parameters: - name: approval_id in: path required: true description: The id of the approval in question. schema: type: integer format: int32 put: operationId: crc.api.approval.update_approval summary: Updates an approval with the given parameters tags: - Approvals requestBody: content: application/json: schema: $ref: '#/components/schemas/Approval' responses: '200': description: Study updated successfully. content: application/json: schema: $ref: "#/components/schemas/Approval" /approval/csv: get: operationId: crc.api.approval.get_csv summary: Provides a list of all users for all approved studies tags: - Approvals responses: '200': description: An array of approvals content: application/json: schema: type: object /health_attesting: get: operationId: crc.api.approval.get_health_attesting_csv summary: Returns a CSV file with health attesting records tags: - Approvals responses: '200': description: A CSV file content: application/json: schema: type: array items: $ref: "#/components/schemas/Approval" components: securitySchemes: jwt: type: http scheme: bearer bearerFormat: JWT x-bearerInfoFunc: crc.api.user.verify_token auth_admin: type: http scheme: bearer bearerFormat: JWT x-bearerInfoFunc: crc.api.user.verify_token_admin 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" primary_investigator_id: type: string example: dhf8r user_uid: type: string example: dhf8r protocol_builder_status: type: string enum: [INCOMPLETE, ACTIVE, HOLD, OPEN, ABANDONED] example: done sponsor: type: string example: "Sartography Pharmaceuticals" ind_number: type: string example: "27b-6-42" hsr_number: type: string x-nullable: true example: "27b-6-1212" categories: type: array items: $ref: "#/components/schemas/WorkflowSpecCategory" WorkflowSpec: properties: id: type: string name: type: string display_name: type: string description: type: string primary_process_id: type: string nullable: true 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 display_order: type: integer workflows: type: array items: $ref: "#/components/schemas/Workflow" 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'] navigation: type: array items: $ref: "#/components/schemas/NavigationItem" 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 data: type: object multi_instance_type: type: enum enum: ['none', 'looping', 'parallel', 'sequential'] multi_instance_count: type: number multi_instance_index: type: number process_name: type: string properties: type: object 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'" TaskEvent: properties: workflow: $ref: "#/components/schemas/Workflow" study: $ref: "#/components/schemas/Study" workflow_sec: $ref: "#/components/schemas/WorkflowSpec" spec_version: type: string action: type: string task_id: type: string task_type: type: string task_lane: type: string form_data: type: object mi_type: type: string mi_count: type: integer mi_index: type: integer process_name: type: string date: type: string 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'" LookupItem: properties: value: type: string format: string example: "1000" label: type: string example: "Chuck Norris" data: type: any NavigationItem: properties: id: type: number format: integer example: 5 task_id: type: string format: uuid example: "1234123uuid1234" name: type: string example: "Task_Has_bananas" description: type: string example: "Has Bananas?" backtracks: type: boolean example: false level: type: integer example: 1 indent: type: integer example: 2 child_count: type: integer example: 4 state: type: enum enum: ['FUTURE', 'WAITING', 'READY', 'CANCELLED', 'COMPLETED','LIKELY','MAYBE'] readOnly: true is_decision: type: boolean example: False readOnly: true task: $ref: "#/components/schemas/Task" Approval: properties: id: type: number format: integer example: 5 ApprovalCounts: properties: PENDING: type: number format: integer example: 5 APPROVED: type: number format: integer example: 5 DECLINED: type: number format: integer example: 5 CANCELED: type: number format: integer example: 5 AWAITING: type: number format: integer example: 5