SYS_UID(n)

Assign a system-wide unique identifier

(n): Optionally specify the 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, an 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)

The 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 the 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 a 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 the unique identifier

SP_PATH_STATUS

Specimen pathology status abbreviation

e.g. If label format is '%PPI%.%SP_TYPE%_%SP_PATH_STATUS%_%SYS_UID%', label generated will be 'PW-001.WB_T_2', where 'PW-001' 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, output_one)

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

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

output_one: Optionally specify whether to output the count 1 or not. When not included, the counting starts from the second specimen as 2. The first specimen does not get any UID.

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 the same patient. If a different type of specimen is collected, then the sequence restarts.PW-0001_WB', 'PW-0001_WB2'

e.g. %PPI%_%SP_TYPE%%PPI_SPEC_TYPE_UID(0, output_one)% generates labels as PW-0001_WB1, PW-0001_WB2 etc

CP_CODE

Collection protocol shortcode 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

The 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, output_one)

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

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

output_one: Optionally specify whether to output the count 1 or not. When not included, the counting starts from the second specimen as 2. The first specimen does not get any UID.

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 the 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 v3.1! For including a unique sequence number within the PPI

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

%PPI_UID% generates a unique ID within the PPID irrespective of whatever type of sample it is.

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.

If there are more derivatives created, the label generated would be 'E1-P_2', 'E1-Sr_3' and so on.

^{SPEC_CP_UID(n)}

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

(n): Optionally specify the 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 v4.1.4! For including a unique sequence number within the CP and PPI

(n): Optionally specify the 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 specimen requirement code set and '1' is the unique sequence number within the CP and PPI.

^{PSPEC_COUNTER(n)}

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

(n): New in v8.1! Optionally, specify the number of digits of the parent specimen label that needs to remain fixed. 

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" …

%PSPEC_COUNTER(2)% will generate the labels as "PA401", "PA402", "PA403", ...,  "PA409", "PA4010", "PA4011" and like that.

^{PRIMARY_SPEC_COUNTER(n)}

New in v8.1! Generates child specimen labels by incrementing the number that appears at the end of the primary specimen label. 

In case of PSPEC_COUNTER, the immediate parent label counter/number is used to generate the child specimen label. Whereas in case of this token, the topmost specimen label counter/number is used.

(n): Optionally, specify the number of digits of the primary specimen label that needs to remain fixed.

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

If primary specimen label is "PA400" then the generated labels for aliquots will be "PA401", "PA402", "PA403" ...

%PRIMARY_SPEC_COUNTER(2)% will generate the labels as "PA401", "PA402", "PA403", ...,  "PA409", "PA4010", "PA4011" and like that.

CUSTOM_FIELD(level, fieldName)

New in v5.0! Include the value of any custom field identified by "fieldName" at the specified level. The field name is the same as the attribute name that appears in the 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

VISIT_UID(n)

New in v5.0! For generating and including a unique sequence number within the visit.

(n): Optionally specify the 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

^{REG_GREEK_SEQ}

New in v5.2. Generates unique Greek letter sequences for specimens of the same participant.

e.g. if label format is %PPI%.%REG_GREEK_SEQ%, the generated specimen labels will be

TS-007.α
TS-007.β
TS-007.γ
TS-007.δ

VISIT_GREEK_SEQ

New in v5.2. Generates unique Greek letter sequences for specimens of the same visit.

e.g. if label format is %VISIT_NAME%.%VISIT_GREEK_SEQ%, the generated specimen labels will be

TS-0005.01.α
TS-0005.01.β
TS-0005.01.γ
TS-0005.01.δ

^{PSPEC_GREEK_SEQ}

New in v5.2. Generates unique Greek letter sequences for child specimens underneath the same parent.

e.g. if label format is %PSPEC_LABEL%.%PSPEC_GREEK_SEQ%, the generated specimens labels will be

TS-0005.01.α.α
TS-0005.01.α.β
TS-0005.01.β.α
TS-0005.01.β.β

PR_SPEC_LABEL

New in v5.2. This token is suitable for use in the child specimen label formats. The token interpolates the child labels with the primary specimen label.

e.g. Assume the primary specimen (lineage = New) label is TS-0005.01.  When the aliquot label format is %PR_SPEC_LABEL%.%CP_PPI_UID(2)%, the aliquot labels are generated as below. The aliquots could be at any level (direct children, grandchildren, great-grandchildren) underneath the parent specimen:

TS-0005.01.01
TS-0005.01.02
TS-0005.01.03
TS-0005.01.04

SP_TYPE_ABBR_UID

New in v6.0. Generates unique ID/sequences for specimen type abbreviations within a given visit or participant registration or parent specimen or primary specimen. If 2 or more specimen types have the same abbreviation then they will share the same counter/sequence.

e.g. %SP_TYPE_ABBR_UID([0-9]+, default|output_one, registration|visit)%

%SP_TYPE_ABBR_UID(0, default, registration)%: Generates unique sequences for specimen type abbreviations at the participant registration level.

%SP_TYPE_ABBR_UID(0, default, visit)%: Unique sequences for specimen type abbreviations at the visit level.

%SP_TYPE_ABBR_UID(2, output_one, registration)%: Generates sequences that are 2 digits in width at the registration level. The sequence numbering starts from 1.

%SP_TYPE_ABBR_UID(2, output_one, parent_specimen)%: Generates sequences of 2 digits in width at the parent specimen level. The sequence numbering starts from 1.

%SP_TYPE_ABBR_UID(2, output_one, primary_specimen)%: Generates sequences of 2 digits in width for children within primary specimen. The sequence numbering starts from 1.

^EVAL(expr)

New in v6.2. Includes the result of expression evaluation in the generated visit names. The expression can be a field name or complex expression.

e.g. %EVAL(#specimen.pathologicalStatus.conceptCode)%: Outputs the concept code of the specimen pathological status in the generated labels.

%EVAL(#formatDate(#specimen.createdOn, "yyyy"))%: Outputs the year of specimen creation in the generated labels.

VISIT_SP_PATH_UID(n, output_one)

New in v6.3. Unique sequence number related to the specific visit and pathology_status of the specimen. Similar to 'VISIT_SP_TYPE_UID'.

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

output_one: Optionally specify whether to output the count 1 or not. When not included, the counting starts from the second specimen as 2. The first specimen does not get any UID.

e.g if label format is '%PPI%_%SP_TYPE%_%VISIT_SP_PATH_UID%' label generated will be 'PW-0001_WB', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation for whole blood. Suppose the pathology_status is 'Malignant'.

The sequence will continue as '0001_WB2' for another whole blood (Malignant) collected within the same visit where '2' is the unique sequence number generated from the 2nd specimen (Malignant).

For a new specimen path_status (say, Non-Malignant) the unique sequence number generated would start from 1.

TODAY_DATE(Format)

New in v7.0! The Format can be optionally specified by the end-user. If the format is not specified, OpenSpecimen will take the default date format for the set locale. (e.g; For US: MM-dd-yyyy)

e.g. If the label format is '%SP_TYPE%_%SPEC_CP_UID(3)%_%TODAY_DATE(dd-MM-yyyy HH:mm:ss)%' label generated will be 'WB_001_03-12-2019 10:42:33', where 'WB' is specimen type abbreviation for whole blood, '001' is unique ID for the specimen under the CP, and '03-12-2019 10:42:33' is the DateTime generated by the passed format.

%TODAY_DATE("yyyy")% will generate current year in 'yyyy' format. (eg: 2020)

The input format will generate DateTime up to milliseconds precision.

PV_PROP(field_name, prop_name, is_custom_field)

New in v9.1.RC2. Outputs the field PV's property value.

field_name: Name of the field that is backed by permissible value. This could be the name of the custom field or standard field. Examples include - pathologicalStatus, tissueSite 

prop_name: Name of the PV property whose value is required.

Example - abbreviation

is_custom_field: Optional. true if field_name refers to the custom field. Otherwise, standard field.

1. PV_PROP(specimenType, abbreviation) will output the specimen type abbreviation. For example - for plasma specimens, this will generate Pl. For serum specimens, the output will be Se.

2. PV_PROP(deviation, code, true): Here deviation is the custom field name because the last argument is true. This will output the value of property "code" of the PV represented by the custom field "deviation".

%EVAL(#specimen.pathologicalStatus.conceptCode)%

Outputs the concept code of the specimen pathological status in the generated labels.

001_WB01_T

%EVAL(#formatDate(#specimen.createdOn, "yyyy"))%

Outputs the year of specimen creation in the generated labels.

001_WB01_2020

%EVAL(#formatDate(#specimen.collectionEvent.time, "dd-MM-yy"))%

Outputs the collection date in the generated labels.

Note:  If while collecting the specimens the time is set as 00:00 then the label will have previous date. For example, if the collection date and time is 23-12-22 00:00 then the generated label will be Ur-22-12-22-01

Ur-23-12-22-01

%EVAL(#specimen.specimenRequirement.name)%

Outputs the year of specimen requirement name in the generated labels.

001_WB01_Tigertop

%EVAL(#specimen.tissueSite.value)%

Outputs the anatomic site value

001_WB01_Lung, NOS

%EVAL(#formatDate(#specimen.visit.visitDate, "dd-MM-yy"))%

Outputs the visit date in the generated labels.

30-04-2021_001_WB01

%EVAL(#specimen.visit.surgicalPathologyNumber)%

Outputs the surgical path number mentioned at visit level

%EVAL(#specimen.registration.externalSubjectId)%

Outputs the external subject ID entered for participant registration 

%EVAL(#specimen.registration.site.code)%

Outputs the registration site code entered for participant registration

%EVAL(#specimen.collectionEvent.container.props[abbreviation])%

Outputs the collection container abbreviation

%EVAL(#specimen.parentSpecimen.specimenRequirement.code)%

Outputs parent's specimen requirement code set in the protocol

%EVAL(#specimen.primarySpecimen.specimenRequirement.code)%

Outputs primary specimen requirement code set in the protocol 

%EVAL(#formatDate(#specimen.registration.registrationDate, "yyyy"))%.

Outputs the year of the registration date of the participant

%EVAL(#specimen.visit.name.substring(n))%-%VISIT_UID(2)%

Remove the first (n) character from the visit name

%EVAL(#specimen.parentSpecimen.label.substring(0,#specimen.parentSpecimen.label.length-2))%

Getting the substring from its parent specimen label.

0 → Getting string from start – First character of the parent specimen label

#specimen.parentSpecimen.label.length-2 → Calculating the length of the parent specimen minus 2

Eg: If your parent specimen label is 20 characters, so using above, it will only get the first 18 characters

%EVAL(#specimen.parentSpecimen.label.substring(0,#specimen.parentSpecimen.label.length-2))%

%EVAL(#specimen.specimenRequirement.name.split(":")[0])%

To get the first part of the specimen requirement name after using split function.

For example:

If you have a specimen requirement name = "1CST6: Serum ST 6ML (RED TOP)" and you want to pull string value before ":" in your specimen label, then you can use the below expression:

%PPI%_%EVAL(#specimen.specimenRequirement.name.split(":")[0])%

It will generate "0000003_1CST6" specimen where 0000003 will be PPID and 1CST6 will be the first part of specimen requirement name before ":".

%EVAL(#specimen.parentSpecimen.label.substring(0, #specimen.parentSpecimen.label.indexOf('_', #specimen.parentSpecimen.label.indexOf('_') + 1)))%

IndexOf function here is used to find the second instance of '_' , and later we used that index to get the substring. 

For Example:

If your parent specimen label is "#2_PR0023_Whole Blood_-1" and you want to extract some part of that label into your aliquot/derivative label, you can use the given expression.

%EVAL(#specimen.parentSpecimen.label.substring(0, #specimen.parentSpecimen.label.indexOf('_', #specimen.parentSpecimen.label.indexOf('_') + 1)))%

The above expression extracts, the #2_PR0023 part, from the parent specimen label. Using the above expression, you are extracting the parent label string from 0 index to second occurrence index of '_'

%EVAL(#specimen.parentSpecimen.label.substring(#specimen.parentSpecimen.label.length-3))%

Getting the last indexsubstring from its parent specimen label.

#specimen.parentSpecimen.label.length-3 → Calculating the length of the parent specimen minus 2

Example:

Parent Specimen Label: WB24-010, the eval will calculate the length of the label and give the last 3 digits of the label, i.e., 010

%EVAL(#specimen.barcode)%

To insert Barcode in specimen label

For example:

Open

%EVAL(#specimen.parentSpecimen.barcode)%-%SYS_UID(5)%

To insert Parent Barcode on child specimen label

For example:

Open

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 for a specimen with PPI 1892, a type is a Whole Blood, collected in the year 1999 with a unique number 1.

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%}

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'