Introduction

OpenSpecimen can be configured to auto-generate certain fields likes labels and names. You can define the format either at the system level or at the collection protocol level depending on the type of field.

...

A format can be defined using one or more tokens and fixed text. Care should be taken that the format will result in a unique string for the label. Currently, no validation is performed when the label format is set. If the label format does not result in the unique label, then OpenSpecimen will start giving errors during data entry. The simplest way to ensure that the label format is unique is to add a UID token. 

Finally, always test the new label formats on QA server before setting in production server. 

PPID format

In order to auto generation 'Participant Protocol ID(PPID)', below tokens can be used. You can configure the PPID format at the collection protocol level i.e. each protocol can have its own format.

Tokens

...

CP code as specified in the collection protocol page.

...

Generates a unique identifier within this CP. The argument n is optional and specifies the number of digits in the identifier.

For example:

%CP_UID% generates IDs like 1, 10, 1010 etc

%CP_UID(5)% generates IDs like 00001, 00002, 00003, 00004, ... 00010, 00011 etc

...

Assigns unique sequential number across all collection protocols.

For example: Generates IDs like 1,2,3,.........101,102, etc. These number will be unique across all the collection protocols.

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

CP specific site code of participant's first MRN. The order of MRNs is based on the order in which they were assigned to the participant.

The CP site code is defined in the collection protocol.

...

System-wide site code of participant's first MRN. The order of MRNs is based on the order in which they were assigned to the participant.

This is specified in the site page.

...

External subject ID specified during participant registration. External subject ID are typically unique study based or system wide IDs assigned by external systems like OpenClinica, REDCap to identify the subjects or patients.

Works v4.3 onward

...

CP site code of participant's registration site, if specified.

Works v4.3 onward

...

Include value of any custom field identified by "fieldName" at the specified level. The field name is same as the attribute name that appears in custom form designer. The allowed values of level are "cpr" and "cp"

Works v5.0 onward

...

e.g.

1. CUSTOM_FIELD(cp, piCode) will include the value of CP custom field "piCode" 
2. CUSTOM_FIELD(cpr, patientId) will include the value of registration custom field "patientId"

Examples

...

%CP_CODE%_%CP_UID(3)%

...

Visit name format

Visit names needs to be unique across protocols. By default system auto generates visit names if no format is set or user does not specify visit name manually. User can alternatively set format at protocol level to generate visit names automatically in required format using below tokens.

Tokens

...

EVENT_LABEL

...

EVENT_UID(n)

...

Assigns unique identifier which is unique to event for each PPID. The argument n is optional and specifies number of digits in the generated identifier. When not specified, no padding is done on left side of generated identifier.

For example:

%EVENT_UID% generates IDs like 1, 2, 3, 4, ...10,11 etc.

%EVENT_UID(2)% generates IDs like 01, 02, 03, 04, ... 10, 11 etc.

...

PPI

...

SYS_UID(n)

...

Unique identifier generated by the system

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

YR_OF_VISIT

...

YR_OF_VISIT2

...

CLINICAL_STATUS

...

CLINICAL_STATUS_ABBR

...

Abbreviation for the clinical status.

How to set abbreviations?

...

Include value of any custom field identified by "fieldName" at the specified level. The field name is same as the attribute name that appears in custom form designer. The allowed values of level for visit names are "visit", "cpr" and "cp"

Works v5.0 onward

...

e.g.

1. CUSTOM_FIELD(cp, piCode) will include the value of CP custom field "piCode" 
2. CUSTOM_FIELD(cpr, patientId) will include the value of registration custom field "patientId"
3. CUSTOM_FIELD(visit, visitNum) will include the value of visit custom field "visitNum"

Examples

...

%PPI%_%EVENT_LABEL%_%SYS_UID%

...

Default format

...

%PPI%.%CLINICAL_STATUS%.%EVENT_UID(1)%

...

Specimen label format

There are three formats on the main CP page:

• Specimen 
• Derivative
• Aliquot

There are similar fields at every specimen requirement level. The user can define different label format for each specimen requirement or keep it same as defined at main CP level.

Tokens

...

Token Name

...

Description

...

Assign a system-wide unique identifier

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

Unique sequence number for the participant within the year of collection. This is generally used in combination of 'YR_OF_COLL' token.

Note: If this token is used individually, the label generated might not be unique across different years of collection.

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

Unique sequence number related to specific PPI and type of specimen. This is generally used in combination of '%SP_TYPE%' token.

Note: The sequence number starts from second specimen as 2, first specimen does not get any UID

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

Unique sequence number related to specific visit and type of specimen. Similar to 'PPI_SPEC_TYPE_UID' above but the sequence here is within visit.

Note: The sequence number starts from second specimen as 2, first specimen does not get any UID

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

YR_OF_COLL2

...

PPI_UID(n)

...

New in OS v3.1! For including a unique sequence number within the PPI

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

SPEC_CP_UID(n)

...

New in OS v3.3.1! For including a unique sequence number within the CP

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

CP_PPI_UID(n)

...

New in OS v4.1.4! For including a unique sequence number within the CP and PPI

(n): Optionally specify number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

...

PSPEC_COUNTER

...

New in OS v4.3! To create child specimens by incrementing count by 1 in the number appears at last in parent specimen label.

...

e.g If aliquot label format is %PSPEC_COUNTER%.

If parent specimen label is "PA400" then generated labels for aliquots will be "PA401", "PA402", "PA403" …

...

New in OS v5.0! Include value of any custom field identified by "fieldName" at the specified level. The field name is same as the attribute name that appears in custom form designer. The allowed values of level for visit names are "specimen", "visit", "cpr" and "cp"

Works v5.0 onward

...

e.g.

1. CUSTOM_FIELD(cp, piCode) will include the value of CP custom field "piCode" 
2. CUSTOM_FIELD(cpr, patientId) will include the value of registration custom field "patientId"
3. CUSTOM_FIELD(visit, visitNum) will include the value of visit custom field "visitNum"
4. CUSTOM_FIELD(specimen, part) will include the value of specimen custom field "part"
5. CUSTOM_FIELD(parentSpecimen, part) will include the value of parent specimen custom field part

...

(n): Optionally specify number of digits. For example, if n = 2 is used, then the numbers generated will be 01, 02, 03 etc.

...

Examples

...

GC_%PPI%_%SP_TYPE%_%YR_OF_COLL%_%PPI_YOC_UID%

...

This will generate a label of the sort: GC_1892_WB_1999_1. This is

...

CP_%PPI%_%SP_TYPE%_%PSPEC_UID%

...

This will generate a label of the sort: CP_1890_S_1 – for a specimen with PPI 1890, type Saliva & 1st child specimen for the particular parent.

...

%PSPEC_LABEL%.%PSPEC_UID%

...

More Details