1 Introduction
2 Sections and properties used in the Nth step
3 Examples
4 Deprecated Feature (v11.x onwards)
5 Additional feature
- 5.1 1. Disable visit autofill (v11.0)

Introduction

The Nth step is used to enter extra specimen details after the specimen is collected.

The specimen collection page shows only a few default fields. If more default fields or custom specimen fields are needed, they can be added and filled in using the Nth step.

Extra fields can be arranged into conditional sections. For example, tissue-specific fields can appear only when the specimen type is tissue. This helps users enter only the data that is relevant to the specimen

Eg: Frozen Event details captured for Tissue samples, Spun events details captured for fluid samples.

Syntax:

The following syntax defines the structure of the specimenCollection Nth step, including section grouping, conditional criteria, and specimen-level field configuration.

syntax:

{
  "name": "specimenCollection",
  "view": null,
  "ctrl": null,
  "data": {
    "fieldGroups": [
      {
        "title": "<Section Title>",   // Title shown as the section header on the Nth step page

        "criteria": {
          "op": "AND",                // Logical operator to evaluate all rules
          "rules": [
            {
              "field": "<field_name>", // Specimen field variable name used for condition (e.g. specimen.type, specimen.lineage)
              "op": "== | != | > | <", // Condition operator
              "value": "<value>"       // Value to compare against
            }
          ]
        },

        "fields": [
          {
            "name": "<field_variable>",       // Field to be displayed on the UI. If this field is NOT defined in the dictionary.Provide full field configuration here.
            "type": "span | text | dropdown | toggle-checkbox",   // UI control type
            "caption": "<custom_label>",    // Custom label shown on the UI
            "defaultValue": "<default_value>" // Default value for the field
          },
          {
            "name": "<field_variable>",
            "baseField": "<field_variable>"  // If type and caption are not specified, they are taken from the dictionary configuration if available.          }
        ]
      }
    ]
  }
}

Sections and properties used in the Nth step

Section in Nth step:

Section	Details

Section	Details
visitFields	If the visit fields need to be displayed on the nth step, this section must be added. There will be only one section of this displaying one row for a visit being collected (Deprecated from v11.x, handled in system workflow).
fields	All fields to be displayed in a table format within the 'fields' section of JSON.
title	Title of each section/table in the nth step.
fieldGroups	If fields need to be displayed in separate sections or tables, multiple sections can be within fieldGroups. For example: 'Primary Specimen details', 'Aliquot details', etc. Each section can have a title, criteria, and a set of fields.
criteria	This defines conditions for displaying fields in each section. For example 'Centrifuge event details' section can be displayed only for 'Whole Blood' & 'Primary' specimens.

Properties used within Sections:

Specimen Collection properties:

Property	Description

Property	Description
name	Identifies the section as specimenCollection. This tells OpenSpecimen that this JSON block handles the Nth step.
view	Optional. Specifies a custom HTML or component view if you want to override the default table-based layout. Usually set to null.
ctrl	Optional. Defines a custom Angular controller if additional logic is required. Usually set to null.
data	Main configuration object containing all parameters for specimen collection → visit details, specimen fields, criteria, and display logic.

Data Section:

Property	Description

Property	Description
showVisitDetails	If true, visit-related fields (like Visit Name, Visit Status) are displayed at the top of the step. (Deprecated from v11.x, it is handled through the system workflow)
showCollectionEvent	Displays specimen collection event fields such as collection date, time, and collector. (Deprecated from v11.x, it is handled through the custom workflow)
showReceivedEvent	Displays received event fields such as received time and received quality. (Deprecated from v11.x, it is handled through the system workflow)
defCollectionDate	Sets the default collection date field (commonly "visit_date" to use the visit’s date). (Deprecated from v11.x, it is handled through the system workflow)
hideCopyFirstToAll	If false, users can copy the first specimen’s field values to all other specimens in the table for faster data entry. (Deprecated from v11.x, it is handled through the system workflow)
enableCofrc	Used for the collapse mode. (Deprecated from v11.x)
visitFields	Defines the configuration of visit-related fields (see separate table below). (Deprecated from v11.x, it is handled through the system workflow)
fieldGroups	Contains one or more specimen field tables (each representing a section like Whole Blood, Plasma, PBMC, etc.).
showCollectionTree	If false, it skips the collection page and directly navigates to the Nth step. (Deprecated from v11.x)

Visit Field Section (Deprecated from v11.x, it is handled through the system workflow):

Property	Description

Property	Description
title	Title of the visit section displayed on the UI (e.g., “Visit Details”).
criteria	Defines logical conditions for displaying this section. Leave blank ("") to always display.
fields	Defining fields for each section for data entry.

Field Group Section:

Property	Description

Property	Description
title	Title for each specimen section/table (e.g., “Whole Blood Collection Details”, “Plasma Collection Details”).
criteria	Logical condition used to decide when this section appears. Defines specimen attributes like type, lineage, or status required to show this group.
fields	List of specimen field configurations to display in the table for this group. Each object represents one column.

Criteria:

Property	Description

Property	Description
op	Logical operator — can be "AND" or "OR" to combine multiple rules.
rules	An array of conditions (rules) to match specimen attributes. Each rule has a field, operator, and value.

Rules (Inside criteria):

Property	Description

Property	Description
field	Field name to be evaluated (e.g., specimen.type, specimen.status).
op	Comparison operator —> e.g., ==, !=, >, <.
value	Expected value to match against. String values must be enclosed in single quotes (e.g., 'Whole Blood').

Field properties used in the field group:

Property	Description

Property	Description
name	Name for the field typically matches baseField.
baseField	Actual backend field name (e.g., specimen.initialQty, specimen.storageLocation).
caption	Optional. Custom label shown as column header in the UI.
type	Type of specimen field. Common types: span (read-only), text, number, pv (dropdown), date, toggle-checkbox.
icon	Optional. Display an icon for the field like a checkbox.
width	Optional. Defines the column width (e.g., "30px").
defaultValue	Default value assigned to the field (e.g., false for a checkbox field).
optional	If false, the field becomes mandatory.

Examples

The examples below show how the Nth step (specimenCollection) can be set up to show specimen default fields, custom fields, and event details for the data entry. Fields can be displayed conditionally based on specimen type, lineage, or requirement code. This ensures that users enter only relevant data after specimen collection.

Please refer to the JSON Fields Configuration wiki page for the field configuration.

Any field used in the Nth step must first be configured in the dictionary section of the CP JSON.

1. Display specimen default fields

Field Details:

Anatomic Site
Pathology Status
Laterality
SR Container

Configuration:

{
  "name" : "specimenCollection",
  "view" : null,
  "ctrl" : null,
  "data" : {
    "fieldGroups" : [ {
      "title" : "Specimen Additional Details",
      "criteria" : {
        "rules" : [ {
          "field" : "specimen.lineage",
          "op" : "==",
          "value" : "'New'"
        } ]
      },
      "fields" : [ {
        "name" : "specimen.label",
        "baseField" : "specimen.label",
        "type" : "span"
      }, 
      {
        "name": "specimen.anatomicSite",
        "baseField": "specimen.anatomicSite"
      },
      {
        "name": "specimen.laterality",
        "baseField": "specimen.laterality"
      },
      {
        "name": "specimen.pathology",
        "baseField": "specimen.pathology"
      },
      {
        "name" : "specimen.collectionContainer",
        "baseField" : "specimen.collectionContainer",
        "caption": "SR Container",
        "type": "span"
      }]
    } ]
  }
}

Screenshot:

2. Display the specimen custom field with a default value

SubForm and Radio field configuration is supported from v11.x.

Field Details:

Specimen Label
Specimen Barcode
Lineage
Type
Is Specimen Used (Radio field)
Histological Details (SubForm Field)
Fixative (Custom Field) → Default to FBS value.
Close Specimen

Criteria: This section should be shown for primary and derived specimens.

Configuration:

{
  "name" : "specimenCollection",
  "view" : null,
  "ctrl" : null,
  "data" : {
    "fieldGroups" : [ {
      "title" : "Fixative Details",
      "enableCofrc" : false,
      "criteria" : {
        "rules" : [ {
          "field" : "specimen.lineage",
          "op" : "!=",
          "value" : "'Aliquot'"
        } ]
      },
      "fields" : [ {
        "name" : "specimen.label",
        "baseField" : "specimen.label",
        "type" : "span"
      }, {
        "name" : "specimen.barcode",
        "baseField" : "specimen.barcode",
        "type" : "span"
      }, {
        "name" : "specimen.lineage",
        "baseField" : "specimen.lineage",
        "type" : "span"
      }, {
        "name" : "specimen.type",
        "baseField" : "specimen.type",
        "type" : "span"
      }, {
        "name" : "specimen.extensionDetail.attrsMap.fixative",
        "baseField" : "specimen.extensionDetail.attrsMap.fixative",
        "defaultValue": "FBS"
      },{
        "name": "specimen.extensionDetail.attrsMap.tier",
        "baseField" : "specimen.extensionDetail.attrsMap.fixative",
        "defaultValue": "1"
        },{
        "name" : "specimen.extensionDetail.attrsMap.histological_details",
        "caption": "Histological Details",
        "type" : "collection",
        "fields" : [ {
          "name" : "histological_qualityy",
          "caption" : "Histological quality",
          "type" : "pvs",
          "attr" : "histological_quality",
          "optional" : true
        } ]
      }, {
        "name" : "specimen.closeAfterChildrenCreation",
        "caption" : "Close Specimen",
        "type" : "toggle-checkbox",
        "defaultValue" : true,
        "values" : {
          "trueValue" : "true",
          "falseValue" : "false"
        }
      } ]
    } ]
  }
}

Screenshot:

3. Display fields based on the specimen requirement code

Field Details:

Specimen Label
Requirement Code
Cell Count → Custom field defaulted value to 10

Criteria:
1. The Nth step section is displayed only for specimens whose requirement code is WB or WS.

{
  "name" : "specimenCollection",
  "view" : null,
  "ctrl" : null,
  "data" : {
    "fieldGroups" : [ {
      "title" : "PB - Cryopreserved Cells",
      "criteria" : {
        "op" : "AND",
        "rules" : [ {
          "field" : "specimen.lineage",
          "op" : "==",
          "value" : "'New'"
        }, {
          "field" : "['WB', 'WS'].indexOf(specimen.reqCode)",
          "op" : "!=",
          "value" : "-1"
        } ]
      },
      "enableCofrc" : false,
      "fields" : [ {
        "name" : "specimen.label",
        "baseField" : "specimen.label",
        "type" : "span"
      }, {
        "name" : "specimen.reqCode",
        "baseField" : "specimen.reqCode",
        "caption" : "Requirement Code",
        "type" : "span"
      }, {
        "name" : "specimen.extensionDetail.attrsMap.cell_count",
        "type" : "number",
        "caption" : "Cell Count",
	    "defaultValue": 10
      } ]
    }]
}
}

Screenshot:

4. Display Processing Event for Whole Blood Specimens

The user can display specimen events at the nth step, like frozen event, fixed event, spun event, etc., at the nth step. Make sure the event field configuration is added in the dictionary section of the JSON file.

Field Details:

Specimen Label
Specimen Type
Lineage
Separation Method (Event Field)
Processing Comment (Event Field)

Criteria:

The Nth step only shown for Whole Blood specimens.

{
  "name" : "specimenCollection",
  "view" : null,
  "ctrl" : null,
  "data" : {
    "fieldGroups" : [ {
      "title" : "Processing details",
      "criteria" : {
        "op" : "AND",
        "rules" : [ {
          "field" : "specimen.type",
          "op" : "==",
          "value" : "'Whole Blood'"
        } ]
      },
      "fields" : [ {
        "name" : "specimen.label",
        "baseField" : "specimen.label",
        "type" : "span"
      }, {
        "name" : "specimen.type",
        "baseField" : "specimen.type",
        "type" : "span"
      }, {
        "name" : "specimen.lineage",
        "baseField" : "specimen.lineage",
        "type" : "span"
      }, {
        "name" : "events.processing_details.separation_method",
        "baseField" : "specimen.events.processing_details.separation_method"
      }, {
        "name" : "events.processing_details.processing_comment",
        "baseField" : "specimen.events.processing_details.processing_comment"
      } ]
    }]
}
}

Screenshot:

Full JSON File:

Deprecated Feature (v11.x onwards)

1. Configure Visit Fields on the nth Step

This configuration is deprecated in v11. From v11 onwards, both default and custom visit fields are automatically pulled from the dictionary in the visit creation task.

Before v11, the visit-level fields were not shown on the specimen collection page for planned specimens. These fields can be captured using the Nth step.

The 'visitFields' section is used to add visit fields on the nth step. You need to add the dictionary section as well before adding the fields in the Nth step.

{
    "name": "specimenCollection",
    "data": {
      "visitFields": {
        "title": "Visit Details",
        "fields": [
          [ {
              "name" : "visit.status",
              "baseField" : "visit.status"
            }, {
              "name": "visit.name",
              "baseField": "visit.name",
              "type": "span",
              "width": "150px"
            }, {
              "name": "visit.clinicalDiagnoses",
              "baseField": "visit.clinicalDiagnoses",
              "width": "200px"
            }, {
              "name": "visit.comments",
              "baseField": "visit.comments",
              "width": "200px"
            }
          ]
        ]
      },
      "fieldGroups": [ {
          "title": "Frozen Event",
          "criteria": {
            "rules": [ {
                "field": "specimen.specimenClass",
                "op": "==",
                "value": "'Tissue'"
              }
            ]
          },
          "fields": [ {
              "name": "specimen.label",
              "baseField": "specimen.label",
              "type": "span"
            }, {
              "name": "specimen.type",
              "baseField": "specimen.type",
              "type": "span"
            }, {
              "name": "events.SpecimenFrozenEvent.time",
              "baseField": "specimen.events.SpecimenFrozenEvent.time"
            }, {
              "name": "events.SpecimenFrozenEvent.user",
              "baseField": "specimen.events.SpecimenFrozenEvent.user"
            }, {
              "name": "events.SpecimenFrozenEvent.frozenMethod",
              "baseField": "specimen.events.SpecimenFrozenEvent.frozenMethod"
            }
          ]
        }
      ]
    }
  }

2. Hide Fields/Table on Specimen Collection Page (v7.1)

This configuration is deprecated in v11, but users can hide the fields through the custom workflow.

The idea is to allow CP admins to hide the columns/tables whose values are derived from the other field values displayed on the screen and submit them to the backend/API.

Hide table code snippet

{
      "title": "Aliquots: Processing Details",
      "criteria": {
        "rules": {
          ...
        }
      },
      "enableCofrc": false,
      "hideTable": true, // To hide the specimen collection page
      "fields": [
        ...
      ]
    }

Hide column code snippet

{
      "title": "Frozen Details",
      "criteria": {
        "rules": {
          ...
        }
      },
      "enableCofrc": false,
      "fields": [
      {
        "name" : "events.SpecimenFrozenEvent.frozenMethod",
        "baseField" : "specimen.events.SpecimenFrozenEvent.frozenMethod",
        "caption" : "Frozen Method",
        "defaultValue" : "Not Specified",
        "hideColumn" : true   // To hide the frozen method column at the nth step
      },
        ...
      ]
    }

3. Show/Hide Visit, Collection, and Received Event Fields (v7.1)

In v11, this is not supported because the specimen collection page is deprecated. However, the same functionality can be achieved using custom workflows.

Use-Cases

Sometimes specimens are collected in the clinic but not yet received by the biobank when the clinic staff enters the details. So the received event is not needed on the specimen collection page.
Collection times are different for each primary specimen. So instead of collecting one time for all, you will collect different times in the nth step.

The options are to be added in the “specimenCollection” section of the workflows JSON as illustrated below:

{
  "name": "specimenCollection",
   "data": {
     "showVisitDetails": false,
     "showCollectionEvent": false,
     "showReceivedEvent": true,
     "defReceiveQuality": "To be Received",  //defaults received qualtity to 'To be Received'
     "defCollectionStatus" : "Collected",    //defaults collection status to 'Collected'
     "defCollectionDate" : "current_date",   // (v8.1) defaults collection and received dates to current date. The supported values are none, current_date and visit_date.
  ...
          } 
}

The above configuration hides visit fields, collection event fields, and displays the received event fields. When the above configuration is not present, all the fields are displayed by default.

From v8.1, the collection and receive dates would be blank by default. You can set the collection and receive dates as follows:

Code	Description

Code	Description
defCollectionDate = 'visit_date'	The common collection and receive dates will be the same as whatever is populated in the visit date field.
defCollectionDate = 'current_date'	The collection and receive dates will be the current/present date/time.
defCollectionDate = 'none'	You are forced to select a date for collection and received fields.

Example JSON to configure the setup that is shown in the above screenshot:

4. Remove the default visit date(v10.0)

This configuration is deprecated in v11 but can be achieved through custom workflows.

{
  "name": "specimenCollection",
  "data": {
    "defVisitDate": "none"
  }
}

Once you added the above code "defVisitDate": "none" in the "specimenCollection section”, you can see the visit date field empty. OpenSpecimen will ask the user to enter the date to proceed further.

Additional feature

1. Disable visit autofill (v11.0)

The defaulted values on events or workflows configuration are autofilled in both cases.

{
  "name" : "specimenCollection",
  "view" : null,
  "ctrl" : null,
  "data" : {
    "autoInitVisit" : false
  }
}

#1 Autofill Enabled:

USE-CASE	Result

USE-CASE	Result
Create a new visit (no visits exist for that participant)	Visit fields (default and custom) are empty except for defaulted values.
Create a new visit under the same event (visit exists for participant for this event)	Visit fields (default and custom) values is autopopulate from old visits expect below fields. Visit Date is defaulted to the current date. Surg Path Number is empty. Status is defaulted to Complete.
Create a new visit under a different event (visit doesn’t exist for participant for this event)	Visit fields (default) values is autopopulate from old visits from different event expect below fields. Visit Date is defaulted to the current date. Surg Path Number, Cohort, Comments, and all custom fields are empty. Status is defaulted to Complete. Clinical Status is defaulted to “Not Specified.” Clinical Diagnosis should be pulled from the last visit from a different event.
Edit the existing visit	Visit fields (default and custom) values are shown AS-IS.

#2 Autofill Disabled:

USE-CASE	Result

USE-CASE	Result
Create a new visit (no visits exist for that participant)	Visit fields (default and custom) are empty except for defaulted values.
Create a new visit under the same event (visit exists for participant for this event)	Visit fields (default and custom) are empty except for defaulted values.
Create a new visit under a different event (visit doesn’t exist for participant for this event)	Visit fields (default and custom) are empty except for defaulted values.
Edit the existing visit	Visit fields (default and custom) values are shown AS-IS.

Configure Collect Specimens (Nth Step)

Introduction

Sections and properties used in the Nth step

Examples

1. Display specimen default fields

2. Display the specimen custom field with a default value

3. Display fields based on the specimen requirement code

4. Display Processing Event for Whole Blood Specimens

Deprecated Feature (v11.x onwards)

Additional feature

1. Disable visit autofill (v11.0)