Template File Examples

The LIMS provides configuration to support generation of sample sheets that are compatible with some Illumina instruments. For details, see the Illumina Instrument Integrations documentation.

The LIMS provides configured automations that generate sample sheets compatible with some QC instruments.

In the template file, the following OUTPUT.FILE.NAME metadata element renames the generated template file 'NewTemplateFileName':

OUTPUT.FILE.NAME, NewTemplateFileName.csv

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.

bash -c "/opt/gls/clarity/bin/java -cp /opt/gls/clarity/extensions/ngs-common/v5/EPP/DriverFileGenerator.jar

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:

CONTROL.SAMPLE.DEFAULT.PROJECT.NAME, My Control Sample Project

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:

HIDE, ${OUTPUT.UDF.SAMPLEUDF}, IF, NODATA

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:

HIDE, ${OUTPUT.UDF.SAMPLEUDF},${PROCESS.TECHNICIAN}, ${PROCESS.LIMSID}, IF, NODATA

You may also hide only one representation of a specific column or field:

HIDE, ${PROCESS.TECHNICIAN##FirstName}, IF, NODATA

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:

HIDE, ${OUTPUT.UDF.SAMPLEUDF},${PROCESS.TECHNICIAN}, ${PROCESS.LIMSID}, IF, NODATA

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:

GROUP.FILES.BY.INPUT.CONTAINERS,<zip file name>

GROUP.FILES.BY.OUTPUT.CONTAINERS,<zip file name>

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:

GROUP.FILES.BY.INPUT.CONTAINERS,MyZip.zip

MyZip.zip

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:

-outputPath SampleSheet.csv

-q 'true'

-destLIMSID {compoundOutputFileLuid0}

•

Template:

GROUP.FILES.BY.OUTPUT.CONTAINERS,MyZip.zip

OUTPUT.TARGET.DIR,${OUTPUT.CONTAINER.NAME}

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