1 Introduction
2 JSON Configuration Levels
- 2.1 Collection Protocol Specific
- 2.2 System Level
3 JSON File Structure
4 Types of Configurations
5 Remove JSON Configuration
- 5.1 CP Level
- 5.2 System Level
6 Custom Fields Configuration
- 6.1 Custom Fields Display
7 Default JSON Files

Introduction

In OpenSpecimen, there are standard fields for participant, visit, and specimen pages. However, not all fields would be relevant to your studies, or you might require new fields based on the CP requirements. Using this feature, users can configure the user interface.

Only Super Admins can edit the System JSON, while users with ‘Collection Protocol’ update privilege can configure the CP JSON, e.g., Administrator roles.

Configurable Pages

Data Entry (This includes the overview, add, and edit pages.)
- Participant
- Visit
- All specimen pages like add new fields during collection, aliquot, derive, etc.
List View (The list view page is the table displayed when you click on any object.)
- CP
- Participant
- Specimen
- Specimen cart
- Reserved specimen
- Order specimens

This is possible using JSON configuration at a CP level or system level.

JSON Configuration Levels

System-wide: applies to all protocols
Collection Protocol Group (CPG) level: applies to all protocols in the group and overrides system setting for them.
Collection Protocol level: overrides the system and CPG settings for that protocol

Collection Protocol Specific

To import/export workflows:

Go to the collection protocols overview page.
Click on the 'More' button.
Select Export Workflows or Import Workflows.

System Level

JSON can be set for all CPs at the system level. When OpenSpecimen is installed, a default system-level JSON is already set in the Settings. This contains the list view and aliquot/derivative creation screen configurations. Refer to the steps to edit system JSON:

Navigate to 'Settings'.
Under 'Biospecimen', set the 'System Workflows' property with the new JSON.
Refresh the browser to take effect of the settings.

JSON File Structure

The JSON files have multiple sections, some of which are only used in the System-level JSON. Here are the details of these sections:

Section Name	Exclusive to System JSON?	Description
CP List View	Yes	Configures the collection protocol list view and filters.
Participant List View	No	Configures the participant list view and filters of the CP.
Specimen List View	No	Configures the specimen list view and filters of the CP.
Common Specimen List View	Yes	Configures the specimen list view across the system, e.g., reserved specimen list view, cart specimen list view, etc.
Order Specimen List View	Yes	Configures the specimen list view and filter of order created during the distribution. For more details, please refer to the System lists → Order specimen list view page section of the wiki page.
Order Specimens Add and Edit	Yes	Configures the add and edit page of order during distribution. For more details, please refer to the System lists → Order specimen add and edit page section of the wiki page.
Container Specimen List View	Yes	Configures the specimen list view and filter in the container pages.
Reserved Specimen List View	Yes	Configures the specimen list view and filter of the reserved specimen tab in the distribution Protocol. If this section is not used, the fields configured in the Common Specimen List View are used. For more details, please refer to the System Lists → Reserved Specimen List Page section of the wiki page.
Specimen Cart Page	Yes	Configures under the Specimens-list-view section of the cart. For more details, please refer to the System lists → Specimen Cart Page section of the wiki page.
Common	No	This section configures: Unplanned Aliquot and Derivative creation page The Specimen Description format (for Specimen Table) Which Workflows are used (from v11)
Bulk Update Dictionary	No	Configures the dropdown list of bulk update of participants and specimens from UI.
Dictionary	No	This defines all the fields that will be used for biospecimen data entry in the CP. The system JSON doesn’t contain a dictionary section and uses default configuration. You can copy and paste the dictionary section from the Participant-centric CP workflow to configure the system JSON dictionary. This is useful only if the same set of data fields apply to all current and future CPs. E.g., if you want to remove a default field like SSN for all CPs, you can use the dictionary section at system-level JSON to achieve this. Refer to the Default JSON section files from the wiki page for the JSON.
Edit Checks (Data Validation)	No	These allow users to add validations to fields (at either system, or the CP levels). These ensure the rules aren’t violated during data entry. Refer to Defining Data Validation for further details.
Visit Table	No	This configures the Visits table on the Participant Overview Page. Refer to this wiki page.
Specimen Tree	No	This field configures the Specimen Table and Tree view. Refer to the following page. Note: Specimen Tree is not present from v11.
Auto-Allocation	No	This is for container auto-allocations (beyond CP and Specimen Type-based allocations). E.g., Container Allocation based on SRs. Refer to the following wiki page.
Locked Fields	Yes	Allows users to lock participant fields. Refer to the wiki page.
Specimen Collection (Nth Step)	No	Allows users to add additional details while collecting specimens. Please refer to the following page.
Form Data Entry Rules	No	Shows/Hides Forms based on conditions. Refer to the wiki page.

Types of Configurations

Below are the list of configurations supported in v11 onwards.
Depreciated configuration in v11 here.

Various types of configurations can be performed using JSON. We have listed them according to which pages they affect:

Participants: List of all Participant Level Configuration

Visits: List of all Visit Level Configuration

Specimens: List of all Specimen Level Configuration

General (actions applicable across levels):

Remove JSON Configuration

Custom Fields Configuration

Custom Fields Display

If you define custom fields in System or CP-level JSON, any changes to the form need to be updated in their respective JSON files too.

The feature where custom fields automatically appear without JSON configuration was implemented in v9.0.

OpenSpecimen

Customize Screens (JSON)