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.
The fields which support auto-generation are:
- Participant protocol ID (PPID)
- Visit name
- Specimen label
Sorry!
We understand this is a bit complex to understand. We are planning to implement a user interface to design labels in one of the coming releases.
What is a token?
The format is configured using "tokens". A token is a unit of information. This page has the list of tokens and examples of the format supported for each field. It takes programming efforts to add a new token.
How to define a format?
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 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
| Token name | Description | Example |
|---|---|---|
CP_CODE | CP code as specified in the collection protocol page. | e.g. If PPID format is '%CP_CODE%.%CP_UID(2)%', PPID generated will be 'PW-02', where 'PW' is the CP code set while creating CP and '02' is the 2 digits unique identifier generated within the CP. |
CP_UID(n) | 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 | e.g. If PPID format is '%CP_CODE%.%CP_UID(2)%', PPID generated will be 'SPW-0004', where 'SPW' is the CP code set while creating CP and '0004' is the 4 digits unique identifier generated within the CP. |
| SYS_UID(n) | 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. | e.g. If PPID format is '%SYS_UID%, PPID generated will be '36', the unique sequential number across all collection protocols |
CP_SITE_CODE | 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. | e.g. If PPID format is %CP_SITE_CODE%_%CP_UID(4)%, PPID generated will be 'KP-01_0012', where 'KP-01' is the CP site code and '0012' is the unique sequential identifier within the CP. |
SITE_CODE | 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. | e.g. If PPID format is '%SITE_CODE%_%CP_UID(4)%', PPID generated will be 'KP_0013', where 'KP' is the site code and '0013' is the 4 digits unique identifier within the CP. |
EXT_SUBJECT_ID | 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 | e.g. If PPID format is %CP_CODE%-%EXT_SUBJECT_ID%, the generated PPID will be 'PW-OC-0001' where 'PW' is the CP code and 'OC-0001' is external subject ID |
REG_SITE_CODE | CP site code of participant's registration site, if specified. Works v4.3 onward | e.g. If PPID format is %CP_CODE%-%EXT_SUBJECT_ID%-%REG_SITE_CODE%, then the generated PPID will look like 'PW-OC-0001-KP' where 'PW' is CP code, 'OC-0001' is external subject ID and 'KP' is CP site code for registration site. |
CUSTOM_FIELD(level, fieldName) | 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.
|
Examples
| Example | Description |
|---|---|
%CP_CODE%_%CP_UID(3)% | Each protocol can have a unique CP code which can be used as part of the PPID. This example format will generate PPID like 'GC_001' if CP code is set as 'GC'. |
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
| Token name | Description | Example |
|---|---|---|
EVENT_LABEL | Event label as specified in collection protocol | e.g. If visit name format is '%PPI%_%EVENT_LABEL%.%EVENT_UID(2)%', visit name generated will be '00011_Visit-01.01', where '00011' is the PPI, 'Visit-01' is the event label and '01' is the unique identifier. |
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. | e.g. If visit name format is '%PPI%_%EVENT_LABEL%.%EVENT_UID(2)%', visit name generated will be 'PW-0001_Visit-01.02', where 'PW-0001' is the PPI, 'Visit-01' is the event label and '02' is the unique identifier. |
PPI | Participant protocol ID | e.g. If visit name format is '%PPI%_%EVENT_LABEL%.%EVENT_UID(2)%', visit name generated will be 'PW-0001_Visit-01.03', where 'PW-0001' is the PPI, 'Visit-01' is the event label and '03' is the unique identifier. |
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. | e.g. If visit name format is 'PW_%EVENT_LABEL%_%SYS_UID(2)%', the visit name generated will be 'PW_Visit-01_49', where 'Visit-01' is the event label and '49' is the unique identifier generated bu the system |
YR_OF_VISIT | Year of visit (four digits) | e.g. If visit name format is '%PPI%-%YR_OF_VISIT%-%EVENT_LABEL%.%EVENT_UID(2)%', the visit name generated will be 'KP-010012-2017-Visit-01.01', where 'KP-010012' is the PPI, '2017' year of visit, 'Visit-01' is the event label and '01' is the unique event identifier. |
YR_OF_VISIT2 | Year of visit (two digits) | e.g. If visit name format is '%PPI%-%YR_OF_VISIT2%-%EVENT_LABEL%.%EVENT_UID(2)%', the visit name generated will be 'KP-010012-17-Visit-01.04' where 'KP-010012' is the PPI, '17' is the two digits year of collection, 'Visit-01' is the event label and '04' is the unique sequence identifier. |
CLINICAL_STATUS | Clinical status | e.g. If visit name format is '%PPI%-%YR_OF_VISIT2%-%EVENT_LABEL%.%EVENT_UID(2)%%CLINICAL_STATUS%', the visit name generated will be 'KP-010013-17-Visit-01.01Follow-up', where 'KP-010013' is the PPI, 17' is the two digits year of collection, 'Visit-01' is the event label, '01' is the unique sequence identifier and 'Follow-up' is the clinical status of the visit |
CLINICAL_STATUS_ABBR | Abbreviation for the clinical status. | e.g. If visit name format is '%PPI%-%YR_OF_VISIT2%-%EVENT_LABEL%.%EVENT_UID(2)%_%CLINICAL_STATUS_ABBR %', the visit name generated will be 'KP-010013-17-Visit-01.01_F', where 'KP-010013' is the PPI, 17' is the two digits year of collection, 'Visit-01' is the event label, '01' is the unique sequence identifier and 'F' is the abbreviation set for 'Follow-up' clinical status |
SITE_CODE | System configured code for the visit site | e.g. if visit name format is %PPI%-%SITE_CODE%-%EVENT_UID(2)%, the generated visit name will be KP-010013-KH-01 where 'KP-010013' is the PPID, KH is site code configured for the site 'Kailas Hospital' and '01' is the unique event identifier. |
CUSTOM_FIELD(level, fieldName) | 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.
|
Examples
| Example | Description |
|---|---|
%PPI%_%EVENT_LABEL%_%SYS_UID% | Default format |
%PPI%.%CLINICAL_STATUS%.%EVENT_UID(1)% | This will generate visit name with participant protocol ID, clinical status and sequential number. For example, 'GC_0001.Operative.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 | Example |
|---|---|---|
SYS_UID(n) | 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. | e.g. If label format is 'WB%SYS_UID%', label generated will be 'WB193', where 193 is a system-wide unique identifier generated. |
PPI | Participant protocol identifier | e.g. If label format is '%PPI%.%SP_TYPE%.%PPI_SPEC_TYPE_UID% label generated will be 'PW-0001.WB.2', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood and '2' is the unique sequence number related to PPI and specimen type. |
SP_TYPE | Specimen type abbreviation. For example, abbreviation for 'Whole Blood' is WB. How to set abbreviations? | e.g If label format is '%PPI%.%SP_TYPE%.%PPI_SPEC_TYPE_UID% label generated will be 'PW-0001.WB.4, where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood and '4' is the unique sequence number related to PPI and specimen type. |
YR_OF_COLL | Year of collection (four digits). | e.g. if label format is %PPI%.%SP_TYPE%.YR_OF_COLL%_%PPI_YOC_UID% 'PW-0001.WB.2017_1', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood, '2017' is the year of collection and '1' is unique sequence number for the participant within the year of collection. |
PPI_YOC_UID(n) | 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. | e.g. If label format is '%PPI%.%SP_TYPE%.%PPI_YOC_UID%' label generated will be 'PW-0001.WB.2017_1', where 'PW-001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood '2017_1' is the unique sequence number for the participant within the year 2017. |
PSPEC_LABEL | Parent specimen's label | e.g. If label format is '%PSPEC_LABEL%.%PSPEC_UID%', label generated will be 'PW-0001.WB.2017_1.2', where '2' is the unique sequence number within the parent specimen 'PW-0001.WB.2017_1' |
PSPEC_UID(n) | Unique sequence number within a parent specimen. | e.g. If label format is '%PSPEC_LABEL%.%PSPEC_UID(2)%', label generated will be 'PW-0001.WB.2017_1.02', where '2' is the unique sequence number within the parent specimen 'PW-0001.WB.2017_1' |
EVENT_LABEL | Visit event label | e.g. If label format is '%PPI%_%EVENT_LABEL%.%EVENT_DATE%_%SYS_UID%', the label generated will be 'PW-001_Visit-01.20161106_309', where 'PW-001' is the PPI, 'Visit-01' is the event label, '20161106' is the visit date and '309' is the system generated unique identifier |
EVENT_DATE | Visit date. Generates date in the format YYYYMMDD | e.g. If label format is '%PPI%_%EVENT_LABEL%.%EVENT_DATE%_%SYS_UID%', the label generated will be 'PW-001_Visit-01.20161106_309', where 'PW-001' is the PPI, 'Visit-01' is the event label, '20161106' is the visit date and '309' is the system generated unique identifier |
SP_PATH_STATUS | Specimen pathology status abbreviation | e.g. If label format is '%PPI%.%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'PW-0001.WB_T_2', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood T' is the pathology status abbreviation set for 'Malignant' pathology status and '2' is the unique sequence number. |
VISIT_NAME | Visit name | e.g. If label format is '%VISIT_NAME%_%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'PW-0001_Baseline_29308.WB_2', where 'PW-0001_Baseline_29308' is the visit name, 'WB' is the specimen type abbreviation set for whole blood and '2' is the unique sequence number related to specific PPI and type of specimen. |
PPI_SPEC_TYPE_UID(n) | 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. | e.g. If label format is '%PPI%_%SP_TYPE%%PPI_SPEC_TYPE_UID%', this will generate label like '0001_WB, where '0001' is PPI, WB is specimen type abbreviation for 'Whole Blood'. The sequence will continue as '0001_WB2' for another whole blood collected under same patient. If a different type of specimen is collected, then the sequence restarts.PW-0001_WB', 'PW-0001_WB2' |
CP_CODE | Collection protocol short code value | e.g. If label format is '%CP_CODE%_%PPI%_%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'PW_PW-0001_WB_2', where 'PW' is the CP code set while creating a CP, 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation for whole blood and '2' is the unique sequence number related to specific PPI and type of specimen. |
EVENT_CODE | Event code of the event | e.g. If label format is '%EVENT_CODE%_%PPI%_%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'Surgery_SPW1_7_WB_4', where 'Surgery' is the event code set while creating events, SPW1_7' is the PPI, 'WB' is the specimen type abbreviation for whole blood and '4' is the unique sequence number related to specific PPI and type of specimen. |
SR_CODE | Specimen requirement code | e.g. If label format is '%SR_CODE%_%PPI%_%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'E1-WB_SPW1_7_WB_4', where 'E1-WB' is the specimen requirement code set specimen requirement level, 'SPW1_7' is the PPI, 'WB' is the specimen type abbreviation for whole blood and '4' is the unique sequence number related to specific PPI and type of specimen. |
VISIT_SP_TYPE_UID(n) | 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. | e.g if label format is '%PPI%_%SP_TYPE%_%VISIT_SP_TYPE_UID%' label generated will be 'PW-0001_WB', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation for whole blood. The sequence will continue as '0001_WB2' for another whole blood collected within the same visit where '2' is the unique sequence number generated from 2nd specimen. |
YR_OF_COLL2 | Year of the collection (two digits) | e.g. if label format is %PPI%.%SP_TYPE%.YR_OF_COLL2%_%PPI_YOC_UID% 'PW-0001.WB.17_1', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood, '17' is the year of collection and '1' is unique sequence number for the participant within the year of collection. |
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. | e.g. if label format is''%SR_CODE%_%PPI_UID%, label generated will be 'E1-WB_1', where 'E1-WB' is the specimen requirement code set and '1' is the unique sequence number within the PPI |
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. | e.g. if label format is '%SR_CODE%_%SPEC_CP_UID(3)%', label generated will be 'E1-WB_001', where 'E1-WB' is the specimen requirement code set and '001' is the 3 digits unique sequence number within the CP |
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. | e.g. if label format is '%SR_CODE%_%CP_PPI_UID%', label generated will be 'E1-WB_1', where 'E1-WB' is the E1-WB and '1' is the unique sequence number within the CP and PPI. |
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" … |
CUSTOM_FIELD(level, fieldName) | 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.
|
VISIT_UID(n) | New in OS v5.0! For generating and including an unique sequence number within the visit. (n): Optionally specify number of digits. For example, if n = 2 is used, then the numbers generated will be 01, 02, 03 etc. | e.g. if label format is %VISIT_NAME%.%VISIT_UID(2)%, the generated specimens labels will be TS-0005.01 TS-0005.02 TS-0005.03 TS-0005.04 |
Examples
| Example | Comment |
|---|---|
| This will generate a label of the sort: GC_1892_WB_1999_1. This is for a specimen with PPI 1892, type is Whole Blood, collected in the year 1999 with a unique number 1. |
| This will generate a label of the sort: |
%PSPEC_LABEL%.%PSPEC_UID% | This is generally used for aliquots. This will generate a label of the sort: CP_1890_Se_1.1, for the 1st child specimen of the parent with label 'CP_1890_Se_1' |