...
In OpenSpecimen, there are standard fields for participant, visit, and specimen pages. However, these not all fields must not would be relevant for to your studystudies, or you would want to create might require new fields based on the CP requirements. Using this feature, super administrators users can configure the user interface.
This is possible using JSON configuration at a CP level or system level.
| Widget Connector |
|---|
| overlay | youtube |
|---|
| _template | com/atlassian/confluence/extra/widgetconnector/templates/youtube.vm |
|---|
| width | 400px |
|---|
| url | https://www.youtube.com/watch?v=UYUr2ur4bS4&list=PLLFI_6gCd35OlVCHTk1BWu0WdCyqySMx8&index=13 |
|---|
| height | 300px |
|---|
|
Which pages can be configured?
...
Data Entry
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.)
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
What can be configured?
| Expand |
|---|
Fields to be displayed, i.e., remove unwanted fields or add additional fields. Making fields mandatory/optional. Default values for fields. Populate values in a field based on a value in another field. Subsetting dropdown values based on the value of another field. Adding skip logic (i.e., hide/unhide fields based on the value of another field). Display calculated fields in overview pages or tables. Reorder fields. Group fields in the same line under headers. Validation rules (Refer to Data Validations(Edit Checks)).
|
Workflow Configuration
This configuration can be done at three levels:
...
This is possible using JSON configuration at a CP level or system level.
| Widget Connector |
|---|
| overlay | youtube |
|---|
| _template | com/atlassian/confluence/extra/widgetconnector/templates/youtube.vm |
|---|
| width | 400px |
|---|
| url | https://www.youtube.com/watch?v=UYUr2ur4bS4&list=PLLFI_6gCd35OlVCHTk1BWu0WdCyqySMx8&index=13 |
|---|
| height | 300px |
|---|
|
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 /or CP group setting CPG settings for that protocol
Collection Protocol
...
Specific
| Expand |
|---|
To import/export workflows: Go to the collection protocols overview page. Click on the 'More' button. Select Export Workflows or Import Workflows.
 |
Collection Group Protocol Level
| Expand |
|---|
To import/export workflows: Go to the collection protocol group overview page.Click on the 'Workflows'. Select ‘Export' or 'Import’.  Image Removed |
System Level
| Expand |
|---|
JSON can be set for all CPs at the system level. When OpenSpecimen is installed, there is already 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:
| Expand |
|---|
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.Dictionary | 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 Participant-centric workflow to configure the system JSON dictionary This is useful only if same set of data fields apply to all current and future CPs. For e.g., if you want to remove 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. 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 |
-> page.Common | Configure the unplanned aliquot and derivative creation Bulk Update Dictionary | Configures the dropdown list of bulk update of participants and specimens from UI. | 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 -> 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
| Expand |
|---|
CP LevelGo to CP Overview → More → Import workflows Choose the file EmptyWorkflow.json and import it. Once you import this, the CP-level workflow will be erased.
 System LevelIf you want to replace the file uploaded at the system level with the default file attached: Navigate to Settings → Biospecimen→ System Workflows System-wide - applies to all protocolsCollection Protocol Group level - applies to all protocols in the group.  |
Custom Fields Configuration
| Expand |
|---|
This feature is supported at the below levelsfollowing levels. (Refer to Attribute Types Examples): Collection Protocol Custom Fields Registration Custom fields Visit Custom fields Specimen Custom fields
|
...
| Expand |
|---|
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 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 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. |
|
| Info |
|---|
If you define custom fields in system System or CP-level JSON, any changes to the form needs changes in respective JSONs 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. |
...
| Expand |
|---|
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: Participant centric CP workflow Specimen centric CP workflow
You can download the default JSON from the user interface. The URLs to download the default JSON's are: 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 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 |
...
| title | Click here to see all example JSON codes... |
|---|
...