Customize Screens & Workflows (JSON)

Created by Poornima Govindrao
Last updated: Apr 13, 2022 by Divya Prabhu

Introduction

In OpenSpecimen, there are standard fields for participant, visit, and specimen pages. However, these fields must not be relevant for your study, or you would want to create new fields based on the CP requirements. Using this feature, super administrators can configure the user interface.

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

https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/825590142

Which pages can be configured?

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 that is displayed when you click on any object.

  • Participant

  • Specimen

  • Specimen cart

  • Reserved specimen

  • Order specimens

What can be configured?

  1. Fields to be displayed, i.e., remove unwanted fields or add additional fields.

  2. Making fields mandatory/optional.

  3. Default values for fields.

  4. Populate values in a field based on a value in another field.

  5. Subsetting dropdown values based on the value of another field.

  6. Adding skip logic (i.e., hide/unhide fields based on the value of another field).

  7. Display calculated fields in overview pages or tables.

  8. Reorder fields.

  9. Group fields in the same line under headers.

  10. Validation rules (Refer to Data Validations(Edit Checks)).

Workflow Configuration

This configuration can be done at two levels:

  1. System-wide - applies to all protocols

  2. Collection Protocol level - overrides the system setting for that protocol

Collection Protocol Level

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

Once JSON is created for the data dictionary, you can set it for all CPs at the system level. Refer to the steps:

  1. Navigate to 'Settings'.

  2. Under 'Biospecimen', set the 'System Workflows' property with the new JSON.

  3. Refresh the browser to take effect of the settings.

Remove Workflow 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

CP Level (v9.0)

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

  1. If you make any changes to the fields in the form, it is reflected on data entry screens.

  2. If you want to add skip logic, download the form xml → add the skip logic → import the xml. Please refer to the skip logic for more details.

  3. Once the field is deleted, the previous data entered for the field is also deleted.

  4. This will only work if you have not manually configured the custom fields within the “dictionary” section.

System Level

System-level JSON is enhanced to show the custom field in any CP to avoid the CP-specific dictionary configuration for custom fields. The UI automatically appends the CP-specific custom fields when a system-level dictionary is used for displaying the add/edit/overview pages. This is subject to the condition that the system-level dictionary doesn't have any custom fields in it.

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

Pre-requisite: CP should not have any CP level workflow attached so that it will use the system level workflow as default.

This feature is supported at the below levels:

  1. Collection Protocol Custom Fields

  2. Registration Custom fields

  3. Visit Custom fields

  4. Specimen Custom fields

Default JSON Files

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

Before v6.2:

  1. Participant centric CP workflow

  2. Specimen centric CP workflow

From v6.2:

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

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

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