Overview
The management of documents to be sent to the IRB and other stakeholders is one of the key requirements for CRC2. To facilitate this requirement, several customizations were made to allow the BPMN standard to easily handle document management, i.e.m the defining, configuration, adding and removing of documents in the application. The sections below describe these customizations generically. Further specific applications of these customizations can be found in the many workflows which involve document management.
Document Data Sources
IRB API Endpoint
The IRB API endpoint CrConnectRequiredDocs returns a list of all questions which can result in a required document appearing on the PB Cover Sheet. If a document is required its Name and ID is listed. The IDs returned by this endpoint are used to designate in CRC2 the subset of IRB documents which could appear on the PB Cover Sheet are required and which are not for a specific study. There is no CRC2 script to call this endpoint, instead it is used by the study_info("documents") as described later.
(irb_)documents.xlsx
A Reference File named irb_documents.xlsx was created to allow Support users to maintain a list of all current and past IRB Pro categories, as well as non-IRB Pro categories. The primary column used by the application in this spreadsheet is the first column labeled as code. The value in the code column result from a manual concatenation of the subsequent three columns: category1, category2 and category3. The additional columns in the spreadsheet were added for specific reasons as described in the sections which follow. All added columns and the data stored in them are available in Task Data when study_info(documents") is executed.
who_uploads?
Allows the Configurator to designate which CRC2 user will be uploading each document category. The list of options includes:
- N/A - specifies that category of documents is not uploaded in CRC2. Primarily used for IRB Pro categories which are out of scope for CRC2.
- Committee Member - specifies that one Committee Member, either individually identified or from a list of individuals who may upload documents, usually associated with an approval process. Who is allowed is controlled by BPMN lanes.
- CTO - someone from the Clinical Trails Office will upload. This is similar to the Committee Member upload.
- Study Team - anyone Associate who was grated access to the application
- System - the application will upload the document after it generates it in the workflow.
zip_if_uva_irb
Allows the Configurator to specify if a document category will be included in the zip file of documents sent to the UVA IRB-HSR if it is the IRB of record. The cell for each document will either contain a √ or be blank. Implementation of this capability in the Modeler is described in a later section.
locked_if_uva_irb
Allows the Configurator to specify if a document category will be locked, i.e., documents cannot be added, edited or deleted, if the UVA IRB-HSR is the IRB of record. The cell for each document will either contain a 🔒 or be blank. Implementation of this capability in the Modeler is described in a later section.
zip_if_non_uva_irb
Allows the Configurator to specify if a document category will be included in the zip file of documents sent to the UVA IRB-HSR if it is not the IRB of record. The cell for each document will either contain a √ or be blank. Implementation of this capability in the Modeler is described in a later section.
locked_if_non_uva_irb
Allows the Configurator to specify if a document category will be locked, i.e., documents cannot be added, edited or deleted, if the UVA IRB-HSR is not the IRB of record. The cell for each document will either contain a 🔒 or be blank. Implementation of this capability in the Modeler is described in a later section.
has_version_date
Allows the Configurator to specify if a version date should be one of the available metadata associated with a document. Implementation of this capability in the Modeler is described in a later section.
has_description
Allows the Configurator to specify if a short description should be one of the available metadata associated with a document. Implementation of this capability in the Modeler is described in a later section.
has_language
Allows the Configurator to specify if a language should be one of the available metadata associated with a document. Implementation of this capability in the Modeler is described in a later section.
workflow
Allows the Configurator to specify which workflow a specific document category is associated with, which is primary used as a filter in a Script Task for loop.
id
Allows the Configurator to specify which document categories correlate with the documents which may appear on the PB Cover Sheet as returned by the CrConnectRequiredDocs IRB API. The document code number is entered.
description
Allows the Configurator to specify a description to use for each document category.
CRC2 Script
The study_info("documents") script was created to provide one script to return a single source of information about documents from multiple sources. The primary data point used in this script is the document code found in the first column of the (irb_)documents.xlsx. Using this as a key value, the script returns a data dictionary which consolidates the following information presented next from an extract from the Task Data for the Drug/Device FDA Communications category:
"DrugDevDoc_FDACommunication": {
"category1": "Drug Device Document",
"category2": "FDA Communication",
"category3": "",
"who_uploads?": "Study Team",
"zip_if_uva_irb": "√",
"locked_if_uva_irb": "🔒",
"zip_if_non_uva_irb": "√",
"locked_if_non_uva_irb": "🔒",
"has_version_date": "√",
"has_description": "",
"has_language": "",
"workflow": "Drug Device Documents",
"id": "0",
"description": "FDA Communication",
"required": false,
"study_id": 17,
"code": "DrugDevDoc_FDACommunication",
"display_name": "Drug Device Document / FDA Communication",
"count": 2,
"files": [
{
"file_id": 1360,
"name": "DrugDeviceFDACommunications1.docx",
"url": "/api/file/1360/download?auth_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjYWgzdXMifQ.9xkzm3H64rkv0o1y0S---caoxw-4Nx2DM52NBbvONR4",
"workflow_id": 15082,
"data_store": {
"ShortDesc": null,
"VerDate": "2020-10-21T04:00:00.000Z",
"Lang": null
}
},
{
"file_id": 1361,
"name": "DrugDeviceFDACommunications2.docx",
"url": "/api/file/1361/download?auth_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjYWgzdXMifQ.9xkzm3H64rkv0o1y0S---caoxw-4Nx2DM52NBbvONR4",
"workflow_id": 15082,
"data_store": {
"ShortDesc": null,
"VerDate": "2021-01-05T05:00:00.000Z",
"Lang": null
}
}
],
"status": "user_input_required" }
The first rows in the dataset are the columns pulled from the (irb_)documents.xlsx spreadsheet as described above. The first column, code, is used as the key value. If any columns are added, edited or deleted in that spreadsheet, this will be reflected in all calls after the updated spreadsheet is uploaded. The remaining rows are:
"required":
If the document category is designated as one of the documents on the PB Cover Sheet (see "id": explanation above in the (irb_)documents.xlsx section), this data returned will be either True if it is a required document for the current study or False if it is not. If the document category is not designated as one of the documents on the PB Cover Sheet, the data returned will be False.
"study_id":
Data shown is the Study ID for the current study.
"code":
Value found in the first column of the (irb_)documents.xlsx spreadsheet.
"display_name":
Concatenation of the category1, category2 and category3 fields, if not empty, with " / " used as separator.
"count":
Number of files uploaded in this document category.
"files":
A list of the files uploaded to this document category and associated data as described here:
"file_id":
Each uploaded file is assigned a unique number which is used in some scripts to identify it.
"name":
The file name of the uploaded document.
"url":
URL which can be used to embed in Jinja text to download the document.
"workflow_id":
The ID of the workflow in which the document was uploaded.
"data_store":
Key value pair of all metadata associated with the uploaded file. This is done by using the file_data Property in the Modeler Form tab for a User Task or in a Script task using file_data_set(). More information on the file_data option can be found in the section which follows. More information about file_data_set() can be found on the Scripts page of this wiki.
Modeler Implementation
In the Modeler there is only one required configuration needed to upload documents which is to create a Form which has a Form Field for which the Form Field Type is either custom type->file (only one file can be uploaded) or custom type->files (multiple files can be uploaded. If no other configuration is done, the file or files will be uploaded into the Unknown document category. If the documents uploaded should be associated with a document category specified in (irb_)documents.xlsx, there are two configuration options available.
If the form will be associated with only one document category, the preferred approach is to enter the document code, i.e., the first column of the (irb_)documents.xlsx spreadsheet, in the Form Field ID of the Field where the Form Field Type is set as either custom type->file or custom type->files.
file_code
file_data