Template File Contents
This article describes the metadata, tokens, and special characters that you can include in your custom template files for use with the Template File Generator.
Available from: BaseSpace Clarity LIMS v5.1.x
Metadata
The following table lists and describes the metadata elements that you can include in your template files.
Unless otherwise specified, metadata elements are optional. In some cases, a metadata element must be used in conjunction with another element. For example, ILLEGAL.CHARACTERS must be used with ILLEGAL.CHARACTER.REPLACEMENTS.
Unless otherwise specified, metadata elements can appear multiple times in the template. However, if they are paired with values, only the first occurrence is used. The other lines are silently ignored.
Unless otherwise specified, if a metadata element requires a single value, any additional values are ignored when the file is generated. For example, suppose you include the OUTPUT.TARGET.DIR <path> metadata in your template file and provide more than one value for <path>. The script will process only the first (valid) path value and will ignore all other values.
Unless "metadata syntax must match exactly" is specified, metadata elements are detected and used even if there is text appended before or after them. For example the following expressions are equivalent:
For more information on metadata and how to use metadata elements in your template files, see Metadata in Creating Template Files article.
Metadata Element | Description | Examples |
CONTROL.SAMPLE.DEFAULT.PROJECT.NAME, <project name> | Defines a project name for control samples. The value specified is used to determine the SAMPLE.PROJECT.NAME and SAMPLE.PROJECT.NAME.ALL token values.
| |
EXCLUDE.CONTROL.TYPES, <control-type name>, <control-type name>, ... | Excludes control inputs that have a control-type uri matching an entry from the exclusion list.
| |
EXCLUDE.CONTROL.TYPES.ALL | Excludes all control types. Takes precedence over EXCLUDE.CONTROL.TYPES
| |
EXCLUDE.INPUT.ANALYTES | Excludes inputs of type Analyte (derived sample) from the generated file. If used without the INCLUDE.INPUT.RESULTFILES element, the generated files will be empty. File generation finishes with a warning message and a warning is logged in the log file. | |
EXCLUDE.OUTPUT.ANALYTES | Excludes outputs of type Analyte (derived sample) from the generated file. The generated file(s) will be empty if:
In both scenarios, file generation finishes with a warning message and a warning is logged in the log file. | |
GROUP.FILES.BY.<grouping>, <zip file name> The following groupings are supported:
| Creates a file for each instance of the specified grouping, i.e., one file per input or per output container. The script gathers all files together into one zip file so only one file placeholder is needed. The metadata may be followed by the name of the zip file that will contain the grouped files. Otherwise, the value set by the -destLIMSID script parameter is used for the file name. The following scenarios will abort file generation:
| |
HIDE, <token>, <token>, ... IF <case> The following case is supported:
| Removes lines from the HEADER_BLOCK section and columns from the HEADER and DATA sections when a <token> matches the <case>.
| |
ILLEGAL.CHARACTERS, <character>, <character>, ... ILLEGAL.CHARACTER.REPLACEMENTS, <replacement>, <replacement>, ... <character> supports Special Character Mapping | Specifies characters that must not appear in the generated file, and replaces them.
| |
INCLUDE.INPUT.RESULTFILES | Includes inputs of type ResultFile in the generated file. (By default these are excluded.) ℹ️ In LIMS v5 and later, ResultFile inputs are only supported in the API. | |
INCLUDE.OUTPUT.RESULTFILES | Includes outputs of type ResultFile in the generated file. (By default these are excluded.) | |
LIST.SEPARATOR, <separator> <separator> supports Special Character Mapping | Specifies character(s) used to separate elements for tokens that return lists (e.g., SAMPLE.PROJECT.NAME.ALL).
| |
OUTPUT.FILE.NAME, <file name> | Specifies the name for the generated file(s).
| You can include 'grouping' tokens in the file name, which allows you to create unique file names when generating multiple files. For details and a list of supported tokens, see Using Token Values in File Names. |
OUTPUT.FILE.NAME.ILLEGAL.CHARACTER.REPLACEMENT, <replacement> | Specifies the character(s) to use when replacing illegal characters in file names.
| |
OUTPUT.SEPARATOR, <separator> <separator> supports Special Character Mapping | Specifies the character(s) used to separate columns in the output.
| |
OUTPUT.TARGET.DIR, <path> | Specifies the name for the generated file(s).
| See also Using Token Values in File Names. |
PROCESS.POOLED.ARTIFACTS | Includes pools in the generated file as if they were regular input artifacts.
| |
SCRIPT.VERSION, <major>.<minor>.<patch> | Provides the version of the compatible DriverFileGenerator.jar file.
⚠️ Ensure your NGS version is up to date. | |
SORT.BY.${token}, ${token}, ... | Sorts the <DATA> rows based on the ${token} specified.
| See Sorting Logic. |
SORT.VERTICAL | Sorts the <DATA> rows based on container column placement.
| See Sorting Logic. |
Tokens
A token is a placeholder variable that is replaced with unique data at run time. You can include tokens in automation command lines, in scripts, and in template files.
For example, suppose you include the INPUT.CONTAINER.NAME token in a template file generated by a step. At run time, this token is replaced with the name of the container that was input to the step.
All tokens included in a template file must appear in the following form: ${TOKEN}, for example - ${INPUT.CONTAINER.NAME}.
Input and Output Tokens
For steps with ResultFile inputs or outputs, refer to the following entries in the Metadata table:
INCLUDE.INPUT.RESULTFILES
INCLUDE.OUTPUT.RESULTFILES
Token | Description |
INPUT.LIMSID OUTPUT.LIMSID | The LIMS ID of a given input / output |
INPUT.NAME OUTPUT.NAME | The name of a given input / output |
INPUT.CONTAINER.COLUMN OUTPUT.CONTAINER.COLUMN | The column part of the placement of a given input / output in its container |
INPUT.CONTAINER.LIMSID OUTPUT.CONTAINER.LIMSID | The LIMS ID of the container of a given input / output Also supported in:
|
INPUT.CONTAINER.NAME OUTPUT.CONTAINER.NAME | The name of the container of a given input / output Also supported in:
|
INPUT.CONTAINER.PLACEMENT OUTPUT.CONTAINER.PLACEMENT | The placement of a given input / output in its container. Format defined in the <PLACEMENT> segment |
INPUT.CONTAINER.ROW OUTPUT.CONTAINER.ROW | The row part of the placement of a given input / output in its container |
INPUT.CONTAINER.TYPE OUTPUT.CONTAINER.TYPE | The type of container holding a given input / output Also supported in:
|
INPUT.CONTAINER.UDF.<udf name> OUTPUT.CONTAINER.UDF.<udf name> | Get the value of a UDF on the container of a given input / output |
INPUT.REAGENT.CATEGORY OUTPUT.REAGENT.CATEGORY | List of categories of reagent on a given input / output |
INPUT.REAGENT.NAME OUTPUT.REAGENT.NAME | List of reagents on an input / output |
INPUT.REAGENT.SEQUENCE OUTPUT.REAGENT.SEQUENCE | List the sequence of each category of reagent on a given input / output |
INPUT.UDF.<udf name> OUTPUT.UDF.<udf name> | Get the value of a UDF on a given input / output |
INPUT.POOL.NAME | If the current input is a pool, provides its name. Empty if the input is not a pool |
INPUT.POOL.PLACEMENT | If the current input is a pool, provides its placement (not affected by the <PLACEMENT> section) Empty if the input is not a pool. |
INPUT.POOL.UDF.<udf name> | If the current input is a pool, provides one of its UDFs. Empty if the input is not a pool. |
Process Tokens
Token | Description |
PROCESS.LIMSID | The LIMS ID of the current process Also supported in:
|
PROCESS.NAME | The name of the current process |
PROCESS.UDF.<udf name> | Get the value of a process UDF (on the current step) Also supported in:
|
PROCESS.TECHNICIAN See Upgrade Note in Creating Template Files article. | The first and last name of the technician running the current process. Also supported in:
|
Submitted Sample Tokens
Token | Description |
SAMPLE.LIMSID | List of all submitted sample LIMS IDs of a given artifact |
SAMPLE.NAME | List of all submitted sample names of a given artifact |
SAMPLE.UDF.<udf name> | Get the value of a UDF for the project containing the submitted samples of a given artifact |
SAMPLE.UDT.<udt name>.<udf name> | Get the value of a UDT UDF on the submitted samples of a given artifact |
SAMPLE.PROJECT.CONTACT | List of the project contacts for all submitted samples of a given artifact |
SAMPLE.PROJECT.CONTACT.ALL | List of the project contacts for the submitted samples of all artifacts. Prints all unique project contact names in a line (first name followed by last name) separated by LIST.SEPARATOR. Also supported in:
|
SAMPLE.PROJECT.LIMSID | List of the project LIMS IDs for all submitted samples of a given artifact |
SAMPLE.PROJECT.NAME | List of projects for all submitted samples of a given artifact (uses CONTROL.SAMPLE.DEFAULT.PROJECT.NAME) |
SAMPLE.PROJECT.NAME.ALL | List of projects for the submitted samples of all artifacts (uses CONTROL.SAMPLE.DEFAULT.PROJECT.NAME). Prints all unique project names in a line, separated by LIST.SEPARATOR. Also supported in:
|
SAMPLE.PROJECT.UDF.<udf name> | Get the value of a UDF for the project containing the submitted samples of a given artifact. Example: |
Other Tokens
Token | Description |
DATE | Current date (i.e., when the script is run). The default format uses the host's locale setting. |
INDEX | Row number of the data row (in <DATA> segment), starting from 1 |
Special Characters
CSV and template file generation special characters have substitution symbols within templates.
Substitution Symbol | Character Represented |
ASTERISK | * |
BACKSLASH | \ |
CARET | ^ |
CLOSING_BRACE | } |
CLOSING_BRACKET | ] |
CLOSING_PARENTHESIS | ) |
COMMA | , |
DOLLAR_SIGN | $ |
DOUBLE_QUOTE | " |
OPENING_BRACE | { |
OPENING_BRACKET | [ |
OPENING_PARENTHESIS | ( |
PERIOD | . |
PIPE | | |
PLUS_SIGN | + |
QUESTION_MARK | ? |
SINGLE_QUOTE | ' |
TAB | tab |
Last updated