Available from: BaseSpace Clarity LIMS v5.1.x
When the Template File Generator generates the file, it creates a log file and attaches it to the step in the LIMS.
If the file generation process encounters errors, these error conditions appear in the log file.
If the file generation process completes successfully, the log file contents resemble the following example:
When troubleshooting Template File Generator issues, you will find detailed information in the Automation Worker log files.
Available from: BaseSpace Clarity LIMS v4.2.x
The Template File Generator is a file-generation solution that allows Clarity LIMS admins, such as lab managers, to produce custom template files without requiring scripting or development knowledge or resources.
At run time, the Template File Generator uses a script (driver_file_generator) and the supplied template file to generate a file. This may be a simple file that includes a subset of LIMS data, or a more complex sample sheet file for upload to the sequencing instrument to start a run.
The format of a template file is typically a comma-delimited CSV file. However, the following file formats are also supported: .bak, .groovy, .md5, .tsv, .txt, .xml.
In Clarity LIMS:
An automation is configured and enabled on a step.
The driver_file_generator script is triggered from the automation command line.
The script uses the template file to generate a file, the contents of which are based on the specifications provided in the template.
The script extracts data from the LIMS via the API, based on tokens defined within the template file.
The script parses the template file and processes the sections, metadata, and tokens it contains. Sections may include header block, header, data, and footer, each of which is enclosed inside tags.
For example:
For details on template sections and the tokens you can use in your template files, see Creating Template Files article.
Several special options are available for inclusion in the template. These options do not directly pull data from the LIMS API. Instead, they modify what has been gathered in the template file. For details, refer to TOKEN FORMAT section of the Creating Template Files article.
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
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.
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}.
For steps with ResultFile inputs or outputs, refer to the following entries in the Metadata table:
INCLUDE.INPUT.RESULTFILES
INCLUDE.OUTPUT.RESULTFILES
CSV and template file generation special characters have substitution symbols within templates.
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:
HEADER_BLOCK
file name
INPUT.CONTAINER.NAME OUTPUT.CONTAINER.NAME
The name of the container of a given input / output Also supported in:
HEADER_BLOCK
file name
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:
HEADER_BLOCK
file name
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.
Token
Description
PROCESS.LIMSID
The LIMS ID of the current process Also supported in:
HEADER_BLOCK
file name
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:
HEADER_BLOCK
file name
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:
HEADER_BLOCK
file name
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:
HEADER_BLOCK
file name
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:
HEADER_BLOCK
file name
SAMPLE.PROJECT.UDF.<udf name>
Get the value of a UDF for the project containing the submitted samples of a given artifact. Example:
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
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
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.
If not specified, the default project name for control samples is left empty.
If no project name follows the metadata element, the project name is left empty.
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.
The metadata entry must be followed by one or more control-type name, otherwise file generation is aborted.
Each control-type name must exist in the LIMS and the metadata syntax must match exactly. If this is not the case, file generation continues, but a warning message displays and a warning is logged in the log file.
A warning is issued if the metadata element is included more than once.
EXCLUDE.CONTROL.TYPES.ALL
Excludes all control types. Takes precedence over EXCLUDE.CONTROL.TYPES
The metadata syntax must match exactly.
If this metadata element is included more than once, file generation completes, but a warning message is logged in the log file.
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:
This element is used without the INCLUDE.OUTPUT.RESULTFILES element.
There is no per input or shared result file output analyte in the step (or container if a GROUP.FILES.BY is enabled).
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:
GROUP.FILES.BY.INPUT.CONTAINERS - generates one file per input container
GROUP.FILES.BY.OUTPUT.CONTAINERS- generates one file per output container
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:
Collisions between the file names. (See OUTPUT.FILE.NAME)
Attempting to group files by both input and output container in the same template.
HIDE, <token>, <token>, ... IF <case> The following case is supported:
NODATA: Line/Column is removed if the token has no value.
Removes lines from the HEADER_BLOCK section and columns from the HEADER and DATA sections when a <token> matches the <case>.
All HIDE lines in the template are treated.
There can be one or more <token> on a HIDE line.
If there is no <token> between HIDE and IF, file generation is aborted.
All tokens must be part of the supported tokens list. Unsupported tokens will abort the file generation. Otherwise, file generation is aborted.
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.
Each <character> is replaced by the matching <replacement> element.
Refer to Special Characters section below to determine if the illegal character must be specified using a keyword.
If ILLEGAL.CHARACTERS or ILLEGAL.CHARACTER.REPLACEMENTS is missing, file generation completes with a warning message and a warning is logged in the log file. No character replacement is performed.
The lists following ILLEGAL.CHARACTERS and ILLEGAL.CHARACTER.REPLACEMENTS must match 1-to-1 in order. Otherwise, file generation completes with a warning message and a warning is logged in the log file. No character replacement is performed.
INCLUDE.INPUT.RESULTFILES
Includes inputs of type ResultFile in the generated file. (By default these are excluded.)
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).
If this metadata is not specified, COMMA is used by default.
Must be followed by the separator character(s) to be used. If no separator is specified, file generation is aborted.
Refer to the Special Characters section below to determine if the character must be provided using a keyword.
OUTPUT.FILE.NAME, <file name>
Specifies the name for the generated file(s).
The metadata syntax must match exactly.
A subset of tokens is supported in the file name.
If the metadata element is not followed by the file name, file generation is aborted.
If this metadata element is not provided or is incomplete, the value of the -o script parameter is used instead.
This causes collisions when multiple files are generated. In this case, file generation completes with an exception message and a warning is logged in the log file.
Using a path in the file name is deprecated, but still supported (update to OUTPUT.TARGET.DIR). File generation finishes with a warning message and a warning is logged in the log file.
Characters in the file name must be either alpha-numeric, underscores, dashes or periods.
Illegal characters are replaced (see OUTPUT.FILE.NAME.ILLEGAL.CHARACTER.REPLACEMENT)
File generation finishes with a warning message and a warning is logged in the log file.
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.
Legal characters are either alpha-numeric or an underscore, dash or period.
If this metadata element is not present, an underscore is used instead. (File generation finishes with a warning message and a warning is logged in the log file.)
If the replacement character is an illegal character itself, an underscore is used.
Must be followed by the character(s) to use for replacing illegal characters in file names. Otherwise, file generation is aborted.
OUTPUT.SEPARATOR, <separator> <separator> supports Special Character Mapping
Specifies the character(s) used to separate columns in the output.
If this metadata is not specified, COMMA is used by default.
Must be followed by the separator character(s) to be used. If no separator is specified, file generation is aborted.
Refer to the Special Characters section below to determine if the separator must be provided using a keyword
OUTPUT.TARGET.DIR, <path>
Specifies the name for the generated file(s).
The metadata syntax must match exactly.
A subset of tokens is supported in the file name.
If the metadata element is not followed by a path, file generation is aborted.
If this metadata element is not provided or is incomplete, the value of OUTPUT.FILE.NAME is used instead.
If OUTPUT.FILE.NAME contains a path, it is replaced by <path>.
See also Using Token Values in File Names.
PROCESS.POOLED.ARTIFACTS
Includes pools in the generated file as if they were regular input artifacts.
When this metadata element is present, it uses demultiplexing logic and prints one row per sample in the pool.
In the case of a submitted pool, sample names are generated following this pattern: “<pool-name>-<reagent-id>”
If an input is not pooled in this mode, the input is treated as a pool of one sample.
If the input is a pool of pools with only one sample, then it prints out as a pooled artifact instead of an input prior to the pool.
If this metadata element is not included, if the input is a pool, it is treated as if it were a single sample and only one row is output in the file.
SCRIPT.VERSION, <major>.<minor>.<patch>
Provides the version of the compatible DriverFileGenerator.jar file.
Version compatibility is only checked if this metadata is present.
<major>.<minor>.<patch> must all be present. Otherwise, file generation is aborted.
File generation is aborted if SCRIPT.VERSION <major> does not match the Template File Generator version.
The file generation continues with a warning if the SCRIPT.VERSION is later than the Template File Generator version (<minor> and <patch> only).
SORT.BY.${token}, ${token}, ...
Sorts the <DATA> rows based on the ${token} specified.
There is no reverse order.
If the SORT.BY. metadata element is not followed by ${token}, it is silently ignored.
See Sorting Logic.
SORT.VERTICAL
Sorts the <DATA> rows based on container column placement.
SORT.BY.${INPUT.CONTAINER.ROW}${INPUT.CONTAINER.COLUMN} must also be present in the template. Otherwise SORT.VERTICAL will have no effect and is silently ignored.
See Sorting Logic.
Available from: BaseSpace Clarity LIMS v4.2.x
You can create template files that the Template File Generator script (driver_file_generator) will use to generate custom files for use in your lab.
This article provides details on the following:
The parameters used by the script.
The sections of the template file—these define what is output in the generated file.
Sorting logic—options for sorting the data in the generated file.
Rules and constraints to keep in mind when creating templates and generating files.
Examples of how you can use specific tokens and metadata in your template files.
For a complete list of the metadata elements and tokens that you can include in a template file, see Template File Contents.
Upgrade Note: process vs step URIs The driver_file_generator script now uses steps instead of processes for fetching information. When a process URI is supplied, the script detects it and automatically switches it to a step URI. (The PROCESS.TECHNICIAN token, which is only available on 'process' in the API, is still supported.) The behavior of the script has not changed, except that the long form -processURI parameter must be replaced by -stepURI in configuration. The -i version of this parameter remains supported and now accepts both process and step URI values. If your configuration is using -processURI or --processURI, replace each instance with -i (or -stepURI/--stepURI).
The following table defines the parameters used by the driver_file_generator script.
Command-line example:
Command-line example using -quickAttach and -destLIMS:
See also the Examples section.
The input-output-maps of the step (defined by the -stepURI parameter) are used as the data source for the content of the generated file.
If they are present, input-output-maps with the attribute output-generation-type=PerInput are used. Otherwise, all input-output-map items are used.
By default, the data source entries are sorted alphanumerically by LIMS ID. You can modify the sort order by using the SORT.BY and SORT.VERTICAL metadata elements (see Metadata section of the Template File Contents article).
The content of the generated file is determined by the sections defined in the template. Content for each section is contained within xml-like opening and closing tags that are structured as follows:
Most template files follow the same basic structure and include some or all the following sections (by convention, section names are written in capital letters, but this is not required):
The order of the section blocks in the template does not affect the output. In the output file, blocks will always be in the order shown.
The area outside of the sections can contain metadata elements (see Metadata section of the Template File Contents article). Anything else outside of the section tags is ignored.
The <PLACEMENT> and <TOKEN FORMAT> sections are not part of the list and do not create distinct sections in the generated file. Instead, they alter the formatting of the generated output.
The header block section may include both plain text and data from the LIMS. It consists of information that does not appear multiple times in the generated file—ie, the information is not included in the data rows (see DATA section)
Tokens in the header block always resolve in the context of the first input and first output available. For example, suppose the INPUT.CONTAINER.TYPE token is used in the header block:
If there is only one type of input container present in the data source, that container type will be present in the output file.
If multiple input container types are present in the data source, only the first one encountered while processing the data will be present in the output file.
For this reason, we recommend against using tokens that will resolve to different values for different samples - such as SAMPLE.NAME. If one of these tokens is encountered, a warning is logged and the first value retrieved from the API is used. (Note that you may use.ALL tokens, where available.)
To include a header block section in a template, enclose it within the <HEADER_BLOCK> and </HEADER_BLOCK> tags.
HIDE feature: If one of the tokens of a line is empty and is part of a HIDE statement, that line will be removed entirely. See Using HIDE to Exclude Empty Columns and Using HIDE to Exclude Empty HEADER rows examples.
The header section describes the header line of the data section (see DATA section). A simple example might be "Sample ID, Placement".
The content of this section can only include plain text and is output as is. Tokens are not supported.
To include a header section in a template, enclose it within the <HEADER> and </HEADER> tags.
HIDE feature: See 'Hide feature' in DATA section. Also note:
If multiple <HEADER> lines are present, at least one must have the same number of columns as the <DATA> template line.
<HEADER> lines that do not match the number of columns are unaffected by the HIDE feature.
Each data source entry creates a data row for each template line in the section. All entries are output for the first template line, then the next template line runs, and so on.
The data section allows tokens and text entries. All tokens are supported.
Note the following:
Duplicated rows are eliminated, if present. A row is considered duplicated if its content (after all variables and placeholders have been replaced with their corresponding values) is identical to a previous row. Tokens must therefore provide distinctive enough data (ie, something more than just CONTAINER.NAME) if all of the input-output entry pairs are desired in the generated file.
By default, the script processes only sample entries. However, there are metadata options that allow inclusion of result files/measurements and exclusion of samples.
Metadata sorting options are applied to this section of the template file only.
By default, pooled artifacts are treated as a single input artifact. They can be demultiplexed using the PROCESS.POOLED.ARTIFACTS metadata element.
If there is at least one token relevant to the step inputs or outputs, this section will produce a row for each PerInput entry in the step input-output-map. If no PerInput entries are present in the step input-output-map, the script will attempt to add data rows for PerAllInputs entries.
Input and output artifacts are always loaded if a <DATA> section is present in the template file, due to the need to determine what type of artifacts the script is dealing with.
To include a data section in a template, enclose it within the <DATA> and </DATA> tags.
HIDE feature: If the token in a given column is empty for all lines and that token is part of a HIDE statement, that column (including the matching <HEADER> columns) will be removed entirely. There can only be one <DATA> template line present when using the HIDE feature. See Using HIDE to Exclude Empty Columns and Using HIDE to Exclude Empty HEADER rows examples.
The content of this section can only include plain text and is output as is. Tokens are not supported.
To include a footer section in a template, enclose it within the <FOOTER> and </FOOTER> tags.
This section contains groovy code that controls the formatting of PLACEMENT tokens (see the PLACEMENT tokens in Template File Contents article Tokens table).
Within the groovy code, the following variables are available:
Note the following:
The script must return a string, which replaces the corresponding <PLACEMENT> tag in the template.
Logic within the placement tags can be as complex as needed, provided it can be compiled by a groovy compiler.
If an error occurs while running formatting code, the original location value is used.
To include a placement section in a template, enclose it within the <PLACEMENT> and </PLACEMENT> tags.
Placement Example: Container Type
In the following example:
If the container type is a 96 well plate, sample placement A1 will return as "A_1"
If the container type is not a 96 well plate, sample placement A1 will return as "A:1"
Placement Example: Zero Padding
This section defines logic to be applied to specific tokens to change the format in which they appear in the generated file.
Special formatting rules can be defined per token using the following groovy syntax:
Within the groovy code, the variable 'token' refers to the original value being transformed by the formatting code. The logic replaces all instances of that token with the result.
${token.identifier} marks the beginning of the token formatting code and the end of the previous token formatting code (if any).
You can define multiple formatting logic rules for a given token, by assigning a name to the formatting section (named formatters are called 'variations'). This is done by appending “##” after the token name (eg “${token.identifier##formatterName}”).
Using the named formatter syntax without giving a name (“${token.identifier##}”) will abort the file generation.
If an error occurs while running formatting code, the resulting value will be blank.
If a named formatter is used but not defined, the value is used as is.
To include a placement section in a template, enclose it within the <TOKEN_FORMAT> and </TOKEN_FORMAT> tags.
TOKEN FORMAT Example: Technician Name
In this example, a custom format is defined for displaying the name of the technician who ran a process (step).
The name of the token appears at the beginning of the groovy code that will then be applied. In this code, the variable 'token' refers to the token being affected. The return value is what will replace all instances of this token in the file.
TOKEN FORMAT Example: Appending a String to Container Name or Sample Name
In this second example, when special formatting is required for two tokens, the logic for both appear inside the same set of tags.
The example appends a string to the end of the input container name or a prefix to the beginning of the submitted sample name.
Metadata provides information about the template file that is not retrieved from the API — such as the file output directory to use, and how the data contents should be grouped and sorted.
Metadata is not strictly confined to a section, and is not designated by opening and closing tags. However, each metadata entry must be on a separate line.
Metadata entries can be anywhere in the template, but the recommended best practice is to group them either at the top or the bottom of the file.
For a list of supported metadata elements, rules for using them, and examples, see Template File Contents, Metadata section.
Sorting in the generated file is done either alphanumerically or by vertical placement information, using the SORT.BY. and SORT.VERTICAL metadata elements.
Sorting must be done using a combination of sort keys - provided to SORT.BY. as one or more ${token} values, each of which always produces a unique value in the file. For example, sorting by just OUTPUT.CONTAINER.NAME would work for samples placed in tubes, but would not work for samples in 96 well plates. Sorting behavior on nonunique combinations is not guaranteed to be predictable.
To sort vertically:
Include the SORT.VERTICAL metadata element in the template file. In addition, the SORT.BY.${token}, ${token} metadata must also be included, as follows:
Any SORT.BY. tokens will be sorted using the vertical sorter instead of the alphanumeric sort.
To apply sorting to samples in 96 well plates:
You could narrow the sort key to a unique combination such as:
See also SORT.VERTICAL and SORT.BY. in the Template File Contents article.
The template must adhere to the following rules:
Metadata entries must each appear on a new line and be the only entry on that line.
Metadata entries must not appear inside tags.
Opening and closing section tags must appear on a new line and as the only entry on that line.
Each opened tag must be closed, otherwise it is skipped by the script.
Any sections (opening tag + closing tag combination) can be omitted from the template file.
Entries that are separated by commas in the template will be delimited by the metadata-specified separator (default: COMMA) in the template file.
White space is allowed in the template. However, if there is a blank line inside a tag, it will also be present in the template file produced.
If an entry in the template is enclosed in double quotes it will be imported as a single entry and written to the template file as such, even if it has commas inside.
To include double-quotes or single-quotes in the template file, use the escape character: Example: \" or \'
To include an escape character in the template file, use two escape characters inside double-quotes. For example, if you want to see \\Share\Folder\Filename.txt use "\\\\Share\\Folder\\Filename.txt" as the token.
If any of the following conditions is not met - the tag, and everything inside it, is ignored by the script and a warning displays in the log file:
Except for the metadata, all template sections must be enclosed inside tags.
Each tag must have its own line, and must be the only tag present on that line.
No other entries, even empty ones, are allowed.
All opened tags must be closed.
Custom field names must not contain periods.
The LIMS provides configuration to support generation of sample sheets that are compatible with some Illumina instruments. For details, see the Illumina Instrument Sample Sheets documentation.
The LIMS provides configured automations that generate sample sheets compatible with a number of QC instruments. The default automation command lines are provided below.
In the template file, the following OUTPUT.FILE.NAME metadata element renames the generated template file 'NewTemplateFileName':
In the automation command line, the following will attach the generated file to the {compoundOutputFileLuid0} placeholder, with the name defined by the OUTPUT.FILE.NAME metadata element.
If the quickAttach parameter is provided without destLIMSID parameter, the script logs an error and stops execution.
If destLIMSID is provided without using quickAttach, it is ignored.
The OUTPUT.FILE.NAME and OUTPUT.TARGET.DIR metadata elements support token values. This allows you to name files based on input / output values of the step - the input or output container name, for example.
The following tokens are supported for this feature:
PROCESS.LIMSID
PROCESS.UDF.<UDF NAME>
PROCESS.TECHNICIAN
DATE
INPUT.CONTAINER.NAME
INPUT.CONTAINER.TYPE
INPUT.CONTAINER.LIMSID
OUTPUT.CONTAINER.NAME
OUTPUT.CONTAINER.TYPE
OUTPUT.CONTAINER.LIMSID
Rules and Constraints
When using token values in file names, the following rules and constraints apply:
Container-related functions will return the value from a single container, even if there are multiple containers.
Other tokens will function, but will only return the value for the first row of the file (first input or output).
If the OUTPUT.FILE.NAME specified does not match the LIMS ID of the file, the output file will not be attached in the LIMS user interface. To ensure that the file is attached, include the quickAttach and destLIMSID parameters in the command-line string.
It is highly recommended that you do not use SAMPLE.PROJECT.NAME.ALL or SAMPLE.PROJECT.CONTACT.ALL, because the result is prone to surpassing the maximum length of a file name. There are similar issues with other SAMPLE tokens when dealing with pools.
Only the following characters are supported in the file name. Any other characters will be replaced by an _ (underscore) by default. This replacement character can be configured with the OUTPUT.FILE.NAME.ILLEGAL.CHARACTER.REPLACEMENT metadata element.
a-z
A-Z
0–9
_ (underscore)
- (dash)
. (period)
You can use the CONTROL.SAMPLE.DEFAULT.PROJECT.NAME metadata element to define a project name for control samples. The value specified by this token will be used when determining one or more values for the SAMPLE.PROJECT.NAME and SAMPLE.PROJECT.NAME.ALL tokens.
Example:
Rules and Constraints
If the token is found in the template, but with no value then no project name will be given for control samples.
If the token is not found in the template, then no project name will be given for control samples.
If multiple values are provided, the first one will be used.
The SAMPLE.PROJECT.NAME.ALL list will include the control project name.
You can use tthe HIDE metadata element to optionally hide a column if it contains no data. The following lines in the metadata will hide a data column when empty:
Assuming ${OUTPUT.UDF.SAMPLEUDF} is one of the data columns specified in the template, then that column will be hidden whenever there is no data to show in the output file. If a list of fields is provided, then any empty ones will be hidden:
You may also hide only one representation of a specific column or field:
You can also use the HIDE metadata element with tokens in the header section. If one or more tokens are used for a header key value pair, and there are no values for any of the tokens, the entire row will be hidden.
Assuming ${OUTPUT.UDF.SAMPLEUDF} is one of the rows specified in the template header section, that header row will be hidden whenever there is no data to display in the output file.
If a list of tokens is provided for the value, the row will only be shown if one or more of the tokens resolves to a value:
If you would like to generate multiple files, you can use the following GROUP.FILES.BY metadata elements:
GROUP.FILES.BY.INPUT.CONTAINERS
GROUP.FILES.BY.OUTPUT.CONTAINERS
These elements allow a file to be created per instance of the specified element in the step, for example, one file per input or per output container. Step level information appears in all files, but sample information is specific to the samples in the given container.
For example, suppose that a step has two samples - each in their own container - with a template file calling for information about process UDFs and sample names. Using this metadata will produce two files, each of which will contain:
One sample entry
The same process UDF information
As a best practice, we recommend storing a copy of generated files in the LIMS. To do this, you must use the quickAttach script parameter. This parameter must be used with the destLIMSID parameter, which tells the Template File Generator script which file placeholder to use. (For details, see Script Parameters.)
Naming The Files
When generating multiple files, the script gathers them all into one zip file so only one file placeholder is needed regardless of how many containers are in the step.
The zip file name may be provided in the metadata as follows:
Inside the zip file, include any paths specified for where files should be written. An example final structure inside the zip, where the subfolders are specified using the container name token, could be as follows:
The file naming, writing, and uploading process works as follows:
The outputPath parameter element is required for the script. You can use this parameter to specify the path to which the generated files will be written and/or the name to use for the file. Use this in the following scenarios:
When the target path/name is constant OR
When the target path/name includes something that can only be passed to the script via the command line - for example, if you want to include the value of a {compoundOutputFileLuidN} in the path.
The OUTPUT.TARGET.DIR metadata element overrides any path provided by outputPath, but does not change the file name. Use this:
When the target path includes something that can only be accessed with token templates - for example, the name of the user who ran the step.
The OUTPUT.FILE.NAME metadata element overrides any value provided by outputPath entirely. This token determines the name of the files that are produced for each container - for example, SampleSheet.csv. It may also contain tokens to access information, such as the container name, and it may also contain a path.
If you provide all three of outputPath, OUTPUT.TARGT.DIR, and OUTPUT.FILE.NAME, the result is that outputPath is ignored and the path specified by OUTPUT.TARGET.DIR is used as the parent under which OUTPUT.FILE.NAME is created, even if OUTPUT.FILE.NAME includes a path in addition to the file name.
If you wish to only attach files to placeholders in the LIMS and do not wish to also write anything to disk, then omit OUTPUT.TARGET.DIR and provide the outputPath parameter value as ".". This will cause files to only be written to the temporary directory that is cleaned up after the automation completes.
To produce the example of MyZip.zip, you could use the following:
Script parameters:
Template:
Rules and Constraints
You can only use one GROUP.FILES.BY metadata element in each template file.
To attach the files in the LIMS as a zip file, you must provide the quickAttach parameter along with the destLIMSID.
The zip file name may optionally be specified with the GROUP.FILES.BY metadata.
If quickAttach is used and no zip name is specified in the template, the zip will be named using the destLIMSID parameter value.
The zip file name, file paths, and file names should not contain characters that are illegal for directories and files on the target operating system. Illegal characters will be replaced with underscores.
If a file name is not unique to the target directory, e.g., if multiple SampleSheet.csv files are being written to /my/target/path, an error will be thrown and no files written.
When specifying the OUTPUT.TARGET.DIR metadata element, if a token is used that may resolve to multiple values for a single path (for example, using INPUT.NAME in the path when it will resolve to multiple sample names), one value will be chosen arbitrarily for the path. For example, you may end up with /Container1/Sample1/myfile.csv when there are two samples in the container.
In LIMS v5 and later, ResultFile inputs are only supported in the API.
Ensure your NGS version is up to date.
The output generation type specifies how the step outputs were generated in relation to the inputs. PerInput entries are available for the following step types: Standard, Standard QC, Add Labels, and Analysis.
Only a subset of the tokens is available for use in the header block section. For details, see the Template File Contents article Tokens table. If an unsupported token is included, file generation will complete with a warning message and a warning will appear in the log file.
When the LIMS attaches a file to a placeholder in the LIMS, it assumes that the file is named with the step LIMSID, and uses this LIMSID to identify the placeholder to which the file should be attached. However, when using OUTPUT.FILE.NAME, you can give the file a name that does not begin with the LIMSID of the placeholder to which it will be attached. To do this, you must use the quickAttach and destLIMSID parameters in the automation command line.
Providing a full file path for OUTPUT.FILE.NAME is still supported, but deprecated. If the full path is provided, the file/directory separator will be automatically detected and will not be replaced in the static parts of the file name. Any of these separators derived from the result of a token value will be replaced.
Option
Name
Description
-i {stepURI:v2} -stepURI {stepURI:v2}
Step URI
(Required) LIMS step URI Provides context to resolve all token values. See Upgrade Note above.
-u {username} -username {username}
Username
(Required) LIMS login username
-p {password} -password {password}
Password
(Required) LIMS login password
-t <templateFile> -templatePath <templateFile>
Template file
(Required) Template file path
-o <outputFile> -outputPath <outputFile>
Output file
(Required) Output file path If the folder structure specified in the path does not exist, it is created. Details on the following metadata elements are provided in the Metadata section of the Template File Contents article:
This output file parameter value is overwritten by OUTPUT.FILE.NAME
To output multiple files, use GROUP.FILES.BY.INPUT.CONTAINERS and GROUP.FILES.BY.OUTPUT.CONTAINERS
Files generated are in CSV format by default. Other value-separated formats are available—see OUTPUT.SEPARATOR.
-l <logFile> -logFileName <logFile>
Log file
(Required) Log file name
-q [true
false] -quickAttach [true
false]
-destLIMSID <LIMSID>
Destination LIMS ID
LIMSID of the output to attach the template file to. Use with quickAttach. See Renaming Generated Files and Generating Multiple Files examples.
Variable Name
Description
containerTypeNode
The container type holding the derived sample
row
The row part of the derived sample's location
column
The column part of the derived sample's location