/
Customize Screens (JSON)
Got feedback or spotted a mistake?

Leave a comment at the end of this page or email contact@krishagni.com

Customize Screens (JSON)

Owned by Poornima Govindrao
Last updated: May 09, 2025 by Srikanth Adiga

Introduction

JSON configuration can configure the following screens:

  • Data Entry (Overview, add, and edit pages)

    • Participant

    • Visit

    • Specimen

  • List Views

    • Collection Protocol

    • Participant

    • Specimen

    • Cart

    • Reserved specimens

    • Order specimens

Video

Configuration Levels

  1. System-wide: applies to all protocols

  2. Collection Protocol Group (CPG) level: applies to all protocols in the group and overrides system setting for them.

  3. Collection Protocol level: overrides the system and CPG settings for that protocol

Collection Protocol Specific

To import/export workflows:

  1. Go to the collection protocols overview page.

  2. Click on the 'More' button.

  3. Select Export Workflows or Import Workflows.

System Level

A default JSON can be set at the system level.

  1. As Super Admin, navigate to 'Settings'.

  2. Under 'Biospecimen', search for 'System Workflows'

  3. Download the file, edit and upload.

 

JSON File Structure

The JSON files have multiple sections, some 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:

  1. Unplanned Aliquot and Derivative creation page

  2. The Specimen Description format (for Specimen Table)

  3. 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.

Remove JSON Configuration

CP Level

  1. Go to CP Overview → More → Import workflows

  2. Choose the file EmptyWorkflow.json and import it. Once you import this, the CP-level workflow will be erased.

System Level

If you want to replace the file uploaded at the system level with the default file attached: Navigate to Settings → Biospecimen→ System Workflows

Custom Fields Configuration

This feature is supported at the following levels. (Refer to Attribute Types Examples):

  1. Collection Protocol Custom Fields

  2. Registration Custom fields

  3. Visit Custom fields

  4. Specimen Custom fields

Custom Fields Display

Form attachment

System JSON

CP level JSON

Description

Form attachment

System JSON

CP level JSON

Description

Form is associated to all CPs

Yes

No

System-level JSON is enhanced to show the custom field in any CP to avoid the CP-specific JSON dictionary configuration for custom fields. This is subject to the condition that the system-level dictionary doesn't have any custom fields in it.

CP should not have any CP-level workflow attached so that it will use the System-level workflow as default.

Form is attached to specific CP

Yes

No

CP-specific custom fields are displayed on respective add/edit/overview pages. This is to avoid any additional configuration for custom fields within the dictionary of CP JSON. 

This allows you to define a system-wide dictionary and yet define CP-specific custom fields without requiring to create/maintain a CP dictionary.

This will only work if you have not manually configured the custom fields within the “dictionary” section of the System-level JSON.

Form is attached to specific CP

Yes

Yes

CP-specific custom fields are displayed on respective add/edit/overview pages. This is to avoid any additional configuration for custom fields within the dictionary. 

This will only work if you have not manually configured the custom fields within the “dictionary” section of the CP-level JSON.

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.

Default JSON Files

Default JSON files for the configuration that contains: the dictionary (all fields for the participant, visit, and specimen), default participant-list, and specimen-list columns and filters are added below

Files:

  1. Participant centric CP workflow

  2. Specimen centric CP workflow

You can download the default JSON from the user interface. The URLs to download the default JSON's are:

  1. Participant centric workflow:<your openspecimen domain>/rest/ng/docs?filename=participant-centric-workflow.json

Example: test.openspecimen.org/rest/ng/docs?filename=participant-centric-workflow.json

  1. Specimen centric workflow: <your openspecimen domain>/rest/ng/docs?filename=specimen-centric-workflow.json

Example: test.openspecimen.org/rest/ng/docs?filename=specimen-centric-workflow.json

Got feedback or spotted a mistake?

Leave a comment at the end of this page or email contact@krishagni.com