How to lock/unlock participant fields?

Starting v3.4, OpenSpecimen supports locking of participant fields. This locks the fields across all collection protocols. 

The locked fields cannot be edited either from UI or through API. This allows biobankers to put in check constraints to ensure users do not inadvertently modify participant information fetched from external sources like REDCap, OpenClinica, OnCore or any other clinical research system.

It is possible to configure fields to be locked depending on source from which the participant information is fetched. The locking information can be configured only at the system level using configuration settings UI & API as described below:

Settings UI

Given below are steps to configure fields to be locked:

1. Navigate to Settings → Biospecimen → System Workflows
2. Click URL displayed for setting to download workflows JSON
3. Open workflows JSON file in any editor of your choice
4. Prepare locking fields configuration JSON as illustrated below. Add this JSON to the array in workflows JSON file. Ensure there is only one array element named "locked-fields". The example configuration instructs OpenSpecimen to disallow edits to identified fields of participants sourced from EPIC. EPIC is an example of data source. It could be REDCap, OpenClinica, OnCore etc. The default data source name for participants created directly in OS is OpenSpecimen
5. The system workflow JSON file should look like the attached file system-workflows.json
6. Upload updated workflows JSON by clicking on System Workflows setting
7. Test that the locking of fields is done properly based on the "data source name"
   
   

    {
        "name": "locked-fields",
        "data": {
            "participant": {
              "EPIC": [
                  "cpr.participant.firstName",
                  "cpr.participant.lastName",
                  "cpr.participant.middleName",
                  "cpr.participant.birthDate",
                  "cpr.participant.gender",
                  "cpr.participant.pmis",
                  "cpr.participant.ethnicities",
                  "cpr.participant.races",
                  "cpr.participant.empi",
                  "cpr.participant.vitalStatus",
                  "cpr.participant.deathDate",
                  "cpr.participant.uid"
              ]
            }
        }
    }

Settings API

1. Download existing system workflow settings using below API:
   
   GET $APP_URL/rest/ng/config-settings/files?module=biospecimen&property=sys_workflows

This will return JSON array with each element representing configuration for a workflow / feature.
   

2. Prepare the locking fields configuration as illustrated in above section
   
   
3. Upload edited system workflows file using HTTP POST multipart form data request as illustrated below
   
   POST $APP_URL/rest/ng/config-settings/files
Content-Type: multipart/form-data

Body:
Multipart request containing file contents attached to variable "file"

The API will return file ID like below for use in subsequent API
   

   4e0db682-ec8d-4ca6-be30-9239e78127e8_system-workflows-9.json

   


4. Using the response of API in step #3, associate the uploaded file as system workflows setting using below API
   
   PUT $APP_URL/rest/ng/config-settings
Content-Type: application/json
Body:
{
   "module": "biospecimen",
   "property": "sys_workflows",
   "value": "4e0db682-ec8d-4ca6-be30-9239e78127e8_system-workflows-9.json"
}



You can refer to the sample json for locking fields