Table of Contents

Participants
Specimens
Specimen cart
Reserved Specimens
Collection Protocol List
Order Specimen List
Container Specimen List

Note
List view pages do not support the Custom Form fields. Eg: Forms attached at Registration Form Level, Specimen Form level etc.

What can be configured?

Columns
Sorting order
Filters (on the right-hand side)
Conditional data display: Fixed criteria can be set to display only specific participants and specimens. For example, display only aliquots.

How to configure the system-level list view?

A default view is shipped with the installation package and applies to all protocols. Super admins can change the default system-level list view configuration by uploading a new configuration file through 'Settings->Biospecimen→SystemWorkflows>Biospecimen→System Workflows'.

...

How to configure the CP level list view?

To configure the list view for a specific CP, go to the CP overview → More → Import Workflows.

...

For participants and specimens, this configuration can be done at two levels:

System-wide - applies to all protocols
Protocol-level - overrides the system setting for that protocol

There is a separate section for each list view in the JSON, as shown below.

...

You can sort the list view based on specimen idID, location, etc.

Expand

title	Sort list view by specimen id in ascending order...

Code Block

language	json

{
       "name": "specimen-list-view",
       "data": {
           "columns": [
               {
                   "expr": "Specimen.label",
                   "caption": "Label",
                   "metainfo": {
                       "showLink": "true"
                   }
               },
               {
                   "expr": "Specimen.createdOn",
                   "caption": "Created On"
               },
               {
                   "expr": "Specimen.type",
                   "caption": "Type"
               },
               {
                   "expr": "Specimen.tissueSite",
                   "caption": "Anatomic Site"
               },
               {
                   "expr": "Specimen.pathologicalStatus",
                   "caption": "Pathology Status"
               },
               {
                   "expr": "Specimen.availableQty",
                   "caption": "Quantity",
                   "metainfo": {
                       "showUnit": "true",
                       "measure": "quantity"
                   }
               },
               {
                   "expr": "concat(Specimen.specimenPosition.containerName, concat_ws(\"\", concat(\" (\", Specimen.specimenPosition.formattedPos, \")\")))",
                   "caption": "Location"
               }
           ],
           "criteria": "Specimen.collectionStatus = \"Collected\" and Specimen.activityStatus = \"Active\"",
           "orderBy": [
               {
                   "expr": "Specimen.id",
                   "direction": "asce"
               }
           ],
           "filters": [
               {
                   "expr": "Specimen.label",
                   "caption": "Label",
                   "searchType": "contains"
               },
               {
                   "expr": "Specimen.lineage",
                   "caption": "Lineage"
               },
               {
                   "expr": "Specimen.createdOn",
                   "caption": "Created On"
               },
               {
                   "expr": "Specimen.type",
                   "caption": "Type"
               },
               {
                   "expr": "Specimen.tissueSite",
                   "caption": "Anatomic Site"
               },
               {
                   "expr": "Specimen.pathologicalStatus",
                   "caption": "Pathology Status"
               },
               {
                   "expr": "Specimen.availableQty",
                   "caption": "Quantity"
               }
           ]
       }
   },

Expand

title	Sort list view by location in ascending order...

Code Block

language	json

{
       "name": "specimen-list-view",
       "data": {
           "columns": [
               {
                   "expr": "Specimen.label",
                   "caption": "Label",
                   "metainfo": {
                       "showLink": "true"
                   }
               },
               {
                   "expr": "Specimen.createdOn",
                   "caption": "Created On"
               },
               {
                   "expr": "Specimen.type",
                   "caption": "Type"
               },
               {
                   "expr": "Specimen.tissueSite",
                   "caption": "Anatomic Site"
               },
               {
                   "expr": "Specimen.pathologicalStatus",
                   "caption": "Pathology Status"
               },
               {
                   "expr": "Specimen.availableQty",
                   "caption": "Quantity",
                   "metainfo": {
                       "showUnit": "true",
                       "measure": "quantity"
                   }
               },
               {
                   "expr": "concat(Specimen.specimenPosition.containerName, concat_ws(\"\", concat(\" (\", Specimen.specimenPosition.formattedPos, \")\")))",
                   "caption": "Location"
               }
           ],
           "criteria": "Specimen.collectionStatus = \"Collected\" and Specimen.activityStatus = \"Active\"",
           "orderBy": [
               {
                   "expr": "concat(Specimen.specimenPosition.containerName, concat_ws(\"\", concat(\" (\", Specimen.specimenPosition.formattedPos, \")\")))",
                   "direction": "asce"
               }
           ],
           "filters": [
               {
                   "expr": "Specimen.label",
                   "caption": "Label",
                   "searchType": "contains"
               },
               {
                   "expr": "Specimen.lineage",
                   "caption": "Lineage"
               },
               {
                   "expr": "Specimen.createdOn",
                   "caption": "Created On"
               },
               {
                   "expr": "Specimen.type",
                   "caption": "Type"
               },
               {
                   "expr": "Specimen.tissueSite",
                   "caption": "Anatomic Site"
               },
               {
                   "expr": "Specimen.pathologicalStatus",
                   "caption": "Pathology Status"
               },
               {
                   "expr": "Specimen.availableQty",
                   "caption": "Quantity"
               }
           ]
       }
   },

System-Level Lists

These lists can be configured at the system level only via Settings → System Workflows:

...

Reserved specimen list page

Configured under the 'reserved-specimens-list-view' section of the JSON
If there is no section for reserved specimens added, then the 'common-specimens-list-view' (if specified) else 'specimen-list-view' is used.

Expand

title	Click here to view the example JSON

Code Block

language	json

{
      "name": "reserved-specimens-list-view",
      "view": null,
      "ctrl": null,
      "data": {
        "columns": [
          {
            "expr": "Participant.empi",
            "caption": "MRN"
          },
          {
            "expr": "concat_ws(\" \", Participant.firstName, Participant.lastName)",
            "caption": "Name"
          },
          {
            "expr": "Specimen.label",
            "caption": "Label",
            "metainfo": {
            "showLink": "true"
            }
          },
          {
            "expr": "Specimen.type",
            "caption": "Type"
          },
          {
            "expr": "Specimen.tissueSite",
            "caption": "Anatomic Site"
          },
          {
            "expr": "Specimen.pathologicalStatus",
            "caption": "Category"
          },
		  {
            "expr": "Specimen.creationEvent.createdBy",
            "caption": "Created By"
          },
          {
            "expr": "concat(Specimen.specimenPosition.containerName, concat_ws(\"\", concat(\" (\", Specimen.specimenPosition.formattedPos, \")\")))",
            "caption": "Box Location"
          }
        ],
        "criteria": "Specimen.availableQty > 0 and Specimen.collectionStatus = \"Collected\"",
        "orderBy": [
          {
            "expr": "Specimen.createdOn",
            "direction": "desc"
          }
        ],
        "filters": [
          {
            "expr": "Specimen.label",
            "caption": "Label",
            "searchType": "contains"
          },
          {
            "expr": "Specimen.lineage",
            "caption": "Lineage"
          },

          {
            "expr": "Specimen.type",
            "caption": "Type"
          },
          {
            "expr": "Specimen.tissueSite",
            "caption": "Anatomic Site"
          },
          {
            "expr": "Specimen.pathologicalStatus",
            "caption": "Pathology Status"
          }
        ]
      }
    }

Specimen cart page

Configured under the 'cart-specimens-list-view' section of the JSON
The configuration for cart specimens list view is picked from system workflow in the following order of preference: cart-specimens-list-view -> common-specimens-list-view -> specimen-list-view.
The configuration detail is the same as that for specimen-list-view specifying the columns to display in the table, filters, ordering, additional restrictions, etc.

Expand

title	Click here to view the JSON example JSON

Code Block

 {
        "name": "cart-specimens-list-view",
        "data": {
            "columns": [
                {
                    "expr": "Specimen.label",
                    "caption": "Label",
                    "metainfo": {
                        "showLink": "true"
                    }
                },
                {
                        "expr": "Specimen.id",
                        "caption": "Specimen ID"
                },
                {
                    "expr": "Specimen.createdOn",
                    "caption": "Created On"
                },
				{
                   "expr": "Specimen.creationEvent.createdBy",
                   "caption": "Created By"
                },
                {
                    "expr": "Specimen.type",
                    "caption": "Type"
                },
                {
                    "expr": "Specimen.availableQty",
                    "caption": "Quantity",
                    "metainfo": {
                        "showUnit": "true",
                        "measure": "quantity"
                    }
                },
                {
                    "expr": "concat(Specimen.specimenPosition.containerName, concat_ws(\"\", concat(\" (\", Specimen.specimenPosition.formattedPos, \")\")))",
                    "caption": "Location"
                }
            ],
            "criteria": "Specimen.collectionStatus = \"Collected\" and Specimen.activityStatus != \"Disabled\"",
            "orderBy": [
                {
                    "expr": "Specimen.createdOn",
                    "direction": "desc"
                }
            ],
            "filters": [
                {
                    "expr": "Specimen.label",
                    "caption": "Label",
                    "searchType": "contains"
                },
                {
                    "expr": "Specimen.lineage",
                    "caption": "Lineage"
                },
                {
                    "expr": "Specimen.createdOn",
                    "caption": "Created On"
                },
                {
                    "expr": "Specimen.type",
                    "caption": "Type"
                },
                {
                    "expr": "Specimen.tissueSite",
                    "caption": "Anatomic Site"
                },
                {
                    "expr": "Specimen.pathologicalStatus",
                    "caption": "Pathology Status"
                },
                {
                    "expr": "Specimen.availableQty",
                    "caption": "Quantity"
                }
            ]
        }
    }

Order specimen list view page

Configured under the "order-specimens-list-view" section of the JSON
If the user is not configured any "order-specimens-list-view" in the system workflow, then OpenSpecimen uses the default configuration.
Added an option to hide the empty columns by specifying the property "hideEmptyColumns": true,

Expand

title	Click here to view the exmple JSON

Code Block

{
        "name": "order-specimens-list-view",
        "data": {
            "columns": [
                {
                    "expr": "Specimen.specimenOrders.label",
                    "caption": "Distribution Label"
                },
                {
                    "expr": "Specimen.label",
                    "caption": "Label",
                    "metainfo": {
                        "showLink": "true"
                    }
                },
                {
                    "expr": "Specimen.type",
                    "caption": "Type"
                },
                {
                  "expr": "Specimen.pathologicalStatus",
                  "caption": "Pathology Status"
                },
		 		{
                  "expr": "Specimen.creationEvent.createdBy",
                  "caption": "Created By"
                },
                {
                    "expr": "CollectionProtocol.shortTitle",
                    "caption": "Collection Protocol"
                }
            ],
            "hideEmptyColumns": true,
            "criteria": "",
            "orderBy": [
                {
                    "expr": "Specimen.specimenOrders.itemId",
                    "direction": "asc"
                }
            ],
            "filters": [
                {
                    "expr": "Specimen.label",
                    "caption": "Label",
                    "searchType": "contains"
                },
                {
                    "expr": "Specimen.type",
                    "caption": "Type"
                },
                {
                    "expr": "CollectionProtocol.shortTitle",
                    "caption": "Collection Protocol"
                }
            ]
        }
    }

Order specimens add and edit page

Configured under "order-addedit-specimens" of the JSON
If the user has not configured any "order-addedit-specimens" in the system workflow, then OpenSpecimen uses the default configuration.

Expand

title	Click here to view the example JSON

Code Block

language	json

	{
        "name": "order-addedit-specimens",
        "data": {
            "columns": [
                {
                    "name": "specimen.label",
                    "caption": "Label",
                    "type": "text",
                    "width": "140px"
                },
                {
                    "name": "specimen",
                    "caption": "Description",
                    "type": "specimen-description",
                    "width": "140px"
                },
                {
                    "name": "specimen.cpShortTitle",
                    "caption": "Collection Protocol",
                    "type": "text",
                    "width": "140px"
                },
                {
                    "name": "specimen.ppid",
                    "caption": "Participant ID",
                    "type": "text",
                    "width": "120px"
                },
                {
                    "name": "specimen.collectionEvent.procedure",
                    "caption": "Collection Procedure",
                    "type": "text",
                    "width": "140px"
                },
                {
                    "name": "specimen.storageLocation",
                    "caption": "Location",
                    "type": "storage-position",
                    "width": "140px"
                },
                {
                    "name": "specimen.availableQty",
                    "caption": "Available",
                    "type": "specimen-quantity",
                    "specimen": "specimen",
                    "width": "100px"
                },
				{
                    "name": "specimen.createdBy",
                    "caption": "Created By",
                    "type": "user",
                    "width": "100px"
                }
            ]
        }
    }

Collection protocol list page (Implemented from v6.3 onwards)

Configured under "cp-list-view" of the JSON
If the user is not configured any "cp-list-view" in the system workflow, then OpenSpecimen uses the default configuration.

Expand

title	Click here to view the example JSON

Code Block

language	json

	{
      "name": "cp-list-view",
      "data": {
          "columns": [
              {
                  "expr": "CollectionProtocol.shortTitle",
                  "caption": "Title",
                  "metainfo": {
                      "showLink": "true"
                  }
              },
              {
                  "expr": "CollectionProtocol.principalInvestigator.investigatorName",
                  "caption": "Principal Investigator"
              },
              {
                  "expr": "CollectionProtocol.startDate",
                  "caption": "Start Date"
              },
              {
                  "expr": "CollectionProtocol.endDate",
                  "caption": "End Date"
              },
              {
                "expr": "CollectionProtocol.customFields.cPCustomField.type",
                "caption": "CP Type"
              }

          ],
          "criteria": "CollectionProtocol.id exists",
          "orderBy": [
              {
                  "expr": "CollectionProtocol.shortTitle",
                  "direction": "asc"
              }
          ],
          "filters": [
              {
                  "expr": "CollectionProtocol.shortTitle",
                  "caption": "Title",
                  "searchType": "contains"
              },
              {
                  "expr": "CollectionProtocol.Title",
                  "caption": "Long Title",
                  "searchType": "contains"
              },
              {
                  "expr": "CollectionProtocol.principalInvestigator.investigatorName",
                  "caption": "Principal Investigator"
              },
              {
                  "expr": "CollectionProtocol.cpSites.siteName",
                  "caption": "Repository"
              }
          ]
      }
  	},

Container Specimen List

Configured under the "container-specimens-list-view" section of the JSON
If the user has not configured any "container-specimens-list-view" in the system workflow, then OpenSpecimen uses the default configuration.

Expand

title	Click here to view the example JSON

Code Block

language	json

{
    "name": "container-specimens-list-view",
    "data": {
       "columns": [
         {
             "expr": "Participant.ppid",
             "caption": "PPID",
             "metainfo": {
                 "showLink": "true"
             }
         },{
             "expr": "Specimen.label",
             "caption": "Label",
             "metainfo": {
                 "showLink": "true"
             }
         },{
             "expr": "Specimen.barcode",
             "caption": "Barcode"
         },{
             "expr": "Specimen.lineage",
             "caption": "Lineage"
         },
         {
             "expr": "Specimen.type",
             "caption": "Type"
         },
         {
             "expr": "Specimen.tissueSite",
             "caption": "Anatomic Site"
         },{
             "expr": "CollectionProtocol.shortTitle",
             "caption": "Collection Protocol",
             "metainfo": {
                 "showLink": "true"
             }
         },
         {
             "expr": "Specimen.availableQty",
             "caption": "Quantity",
             "metainfo": {
                 "showUnit": "true",
                 "measure": "quantity"
             }
         },
         {
             "expr": "concat(Specimen.specimenPosition.containerName, concat_ws(\"\", concat(\" (\", Specimen.specimenPosition.formattedPos, \")\")))",
             "caption": "Location"
         },{
             "expr": "Specimen.createdOn",
             "caption": "Created On"
         }
     ],
     "criteria": "Specimen.collectionStatus = \"Collected\" and Specimen.activityStatus = \"Active\"",
     "orderBy": [
         {
             "expr": "Specimen.createdOn",
             "direction": "desc"
         }
     ],
     "filters": [
       {
           "expr": "Participant.ppid",
           "caption": "PPID",
           "searchType": "contains"
       },{
             "expr": "Specimen.label",
             "caption": "Label",
             "searchType": "contains"
         },{
             "expr": "Specimen.barcode",
             "caption": "Barcode"
         },
         {
             "expr": "Specimen.lineage",
             "caption": "Lineage"
         },
         {
             "expr": "Specimen.type",
             "caption": "Type"
         },
         {
             "expr": "Specimen.tissueSite",
             "caption": "Anatomic Site"
         },{
             "expr": "CollectionProtocol.shortTitle",
             "caption": "Collection Protocol"
         },
         {
             "expr": "Specimen.availableQty",
             "caption": "Quantity"
         },{
             "expr": "concat(Specimen.specimenPosition.containerName, concat_ws(\"\", concat(\" (\", Specimen.specimenPosition.formattedPos, \")\")))",
             "caption": "Location"
         },{
             "expr": "Specimen.createdOn",
             "caption": "Created On"
         }
     ]
    }
    }

...

Expand

List Page

Field Name

Expression

1.

Participant List

MRN Site

Code Block

language	json

{
"expr": "Participant.medicalRecord.mrnSiteName",
"caption": "Site"
}

2.

Participant List

MRN

Code Block

language	json

{
"expr": "Participant.medicalRecord.medicalRecordNumber",
"caption": "MRN"
}

3.

Participant List

External Subject ID

(Supported version V5.1 and onwards)

Code Block

language	json

{
"expr": "Participant.externalSubjectId",
"caption": "External Subject ID"
}

4.

Participant List

Date formatting("participant-list-view")

(Supported version V5.2 and onwards)

Refer to wiki for 'Date Formats'

Code Block

language	json

{
  "expr": "Participant.dateOfBirth",
  "caption": "Date Of Birth",
  "expr": "date_format(Participant.dateOfBirth, \"%month2%-%month_day%-%year4%\")"
}

5.

Participant List

Consent Document Title

Code Block

language	json

{
      "expr" : "Participant.econsents.docTitle",
      "caption" : "eConsent Doc Title"
}

6.

Participant List

Consent Version

Code Block

language	json

{
      "expr" : "Participant.econsents.docVersion",
      "caption" : "Version"
}

7.

Participant List

Consent Statement

Code Block

language	json

{
      "expr" : "Participant.econsents.stmtResponses.statement",
      "caption" : "Consent Statement"
}

8.

Participant List

Consent Response

Code Block

language	json

{
      "expr" : "Participant.econsents.stmtResponses.response",
      "caption" : "Response"
}

9.

Participant List

Consent Custom Field

Code Block

language	json

{
      "expr" : "Participant.econsent.customFields.additionalRegistration.preferredLanguage",
      "caption" : "Preferred Language"
}

10.

Participant List

Consent Date

Code Block

language	json

{
  "expr": "Participant.consentSignDate",
  "caption": "Date of Consent",
  "datatype": "date"
}

11.

Participant List

Custom Form Fields (Participant level)

Syntax: Participant.extensionscustomFields.<formName>.<attributeName>

<formName>: Replace it with the 'Form Name' of the custom form

<attributeName>: Replace it with the 'Attribute Name' of the custom form field

Note: Ensure that the custom fields are defined in the dictionary section before configuring them in list view columns or filter section.

Code Block

language	json

{
  "expr": "Participant.customFields.smokingHistoryForm.dateOfSigning",
  "caption": "Signing Date of Smoking History Form",
  "datatype": "date"
}

Specimen List

Date formatting ("specimen-list-view"12.

Participant List

Add Custom field of any type dropdown, text, text field

"Participant.customFields" → Default syntax to call participant custom field
"patient_details_form"→ Custom form name
"patient_initials"→ Field udn present in a custom form XML

Example:

Patient initials

{
"expr": "Participant.customFields.patient_details_form.patient_initials",
"caption": "Patient Initials"
}

13.

Specimen List

Date formatting ("specimen-list-view")

(Supported version V5.2 and onwards)

Refer to wiki for 'Date Formats'

Code Block

language	json

{
  "expr": "Specimen.createdOn",
  "caption": "Created On",
  "expr": "date_format(Specimen.createdOn, \"%month3%-%month_day%-%year4%\")"
}

14.

Specimen List

Add Custom field of any type dropdown, text, number, fancy control, etc

"Specimen.customFields" → Default syntax to call specimen custom field
"wCMCSpecimenFields"→ Custom form name
"diseaseStatus"→ Field udn present in a custom form XML

Eg:1

Disease Status

Code Block

language	json

{
"expr":"Specimen.customFields.wCMCSpecimenFields.diseaseStatus",
  "caption" : "Disease Status"
}

Eg:2

Technician(User Fancy Control)

Code Block

language	json

{
 "expr" : "Specimen.customFields.wCMCSpecimenFields.technician",
 "caption" : "Technician"
},

15.

Specimen List

Collection Date and Time

Code Block

language	json

{
 "expr" : "Specimen.spmnCollRecvDetails.collTime",
  
   "caption" : "Collection Date"
}

16.

Specimen ListSpecimen Laterality

Collection Container

Code Block

language	json

{

     "expr" : "Specimen.spmnCollRecvDetails.tissueSidecollContainer",
      "caption" : "LateralityCollection Container"
}

17.

Specimen List

Visit NameCollection Procedure

Code Block

language	json

 {
      ""expr" : "SpecimenCollectionGroupSpecimen.spmnCollRecvDetails.namecollProcedure",
      "caption" : "VisitCollection NameProcedure"

}

18.

Specimen List

Visit Custom Field

Add visit custom fields to the specimen list view page:

“SpecimenCollectionGroup.customFields”: Default syntax to call visit custom field
“visit_data_extension“: Custom form name
“sequence_number“: Field udn present in a custom form XML

Received Date and Time

Code Block

language	json

{
"expr": "SpecimenCollectionGroupSpecimen.customFields.visit_data_extension.sequence_numberspmnCollRecvDetails.recvTime",
  "caption" : "SequenceReceived Numberon"
}

19.

CP Specimen List View

Custom Field:

In 'expr', 'cPCustomFields' is a Form Name, 'type' is an attribute name.

Specimen Laterality

Code Block

language	json

{
      "expr" : "CollectionProtocol.customFields.cPCustomField.typeSpecimen.tissueSide",
      "caption" : "Laterality"
}

20.

Specimen List

Visit Name

Code Block

language	json

 {
      "expr" : "SpecimenCollectionGroup.name",
      "caption" : "Visit Name"
 }

21.

Specimen List

Clinical Diagnoses

Code Block

language	json

 {
      "expr" : "SpecimenCollectionGroup.clinicalDiagnoses.value",
      "caption" : "CPClinical TypeDiagnoses"
 }

22.

Specimen List

Visit Custom Field

Add visit custom fields to the specimen list view page:

“SpecimenCollectionGroup.customFields”: Default syntax to call visit custom field
“visit_data_extension“: Custom form name
“sequence_number“: Field udn present in a custom form XML

Code Block

language	json

{
"expr":"SpecimenCollectionGroup.customFields.visit_data_extension.sequence_number",
  "caption" : "Sequence Number"
}

23.

Specimen List

Participant Registration Site

Code Block

language	json

{
      "expr" : "Participant.site",
      "caption" : "Registration Site"
    }

24.

Specimen List

Participant Registration Date

Code Block

language	json

{
      "expr" : "Participant.regDate",
      "caption" : "Registration Date"
    },

25.

CP List View

Add: Collection Protocol Code in list view page(Supported from v9.0)

Code Block

language	json

 {
   "expr": "CollectionProtocol.code",
   "caption": "CP Code"
  },

26.

CP List View

Custom Field:

In 'expr', 'cPCustomFields' is a Form Name, 'type' is an attribute name.

Code Block

language	json

{
  "expr": "CollectionProtocol.customFields.cPCustomField.type",
  "caption": "CP Type"
}

27.

Participant List

Registration Site

Code Block

language	json

{
      "expr" : "Participant.site",
      "caption" : "Registration Site"
    }

28

Specimen List

Collection Protocol Event Label

Code Block

language	json

{
      "expr" : "SpecimenCollectionGroup.collectionProtocolEvent.collectionPointLabel",
      "caption" : "Event Label"
    }

29

Participant List

Participant Creation Date and Time

Code Block

language	json

{
      "expr" : "Participant.creationTime",
      "caption" : "Creation Date"
    },

Versions Compared

Old Version 67

New Version 84

Key

What can be configured?

How to configure the system-level list view?

How to configure the CP level list view?

System-Level Lists

Page Comparison

Versions Compared

Old Version 67

New Version 84

Key

What can be configured?

How to configure the system-level list view?

How to configure the CP level list view?

System-Level Lists