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.

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.

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

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

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.

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.

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.

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

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

REG_GREEK_SEQ

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

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

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

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.β.β

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

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)

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.

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)

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.

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

001_WB01_T

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.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

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 ":".

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 '_'

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

For example: