The Illumina Preconfigured Workflows Package (PCWP) supports the integration of Clarity LIMS with established lab protocols. The integration provides preconfigured workflows that map to lab protocols and steps, and support Illumina library prep kits, reagent kits, and controls. For detailed information on the installed workflows, see the instrument integrations and protocols documentation.

Release Date: July 2025

These release notes detail the key changes to software components for the Next Generation Sequencing (NGS) Extensions Package v5.25.1.

Compatibility

Refer to Compatibility under Instruments & Integrations.

Defects and Security Vulnerability Fixed

• Template File Generator - fixed script failure when reading project UDF from a pool containing control sample.

• Fixed security vulnerabilities.

Known Issues

An error occurs when reformatting the date using the Lab Logic Toolkit with the Date utility class. The date reformatting can be done with java.time instead.

Last Updated: November 2024

Release Date: June 2024

Document Version: 2

These release notes detail the key changes to software components for the Next Generation Sequencing (NGS) Extensions Package v5.25.0.

Compatibility

Refer to under Instruments & Integrations.

New Features

Added the download_attachments script. This script copies one or more result files attached in a step to a user-specified directory within Clarity LIMS. For example, this script can copy a generated sample sheet to a mounted directory so that the user can access it directly from the instrument control software.

Defects Fixed

None

Known Issues

An error occurs when reformatting the date using the Lab Logic Toolkit with the Date utility class. The date reformatting can be done with java.time instead.

Revision History

Last Updated: November 2024

Release Date: February 2024

Document Version: 2

These release notes detail the key changes to software components for the Next Generation Sequencing (NGS) Extensions Package v5.24.0.

Compatibility

The Clarity LIMS NGS Extensions Package includes the AccessionReagentKitLots script, which automates the accessioning of reagent lots based on container names. This section provides details on the script and its parameters, and LIMS configuration requirements.

Script Overview

Designed for use in automated workflows, the AccessionReagentKitLots creates a new reagent lot, matching the Reagent Kit Name specified in the command line to a reagent kit configured in the LIMS.

The script populates the lot details according to the following logic (see Script Parameters section for details):

• Lot Name = Lot name (specified by lotName parameter)

• Lot Number = Container name (specified by from parameter)

• Expires = now + expiry days (specified by expiryDays parameter)

Before accessioning the reagent lot, the script verifies that:

• The expiryDays parameter value is greater than 0, and is a whole number

• The reagent lot does not already exist in the LIMS - lots are not reusable.

The script checks whether there is an existing reagent lot in the LIMS that matches the combination of lot name + lot number provided. If so, validation fails. (Kit name is not checked during this validation process.)

If a unique combination of lot name + lot number is provided, the LIMS creates the new lot—even if there are already lots in the LIMS matching either the name or the number.

Note that it is therefore possible to create both of these lots:

• Lot 'ABC' with number '123'

• Lot 'ABD' with number '123'

Script Parameters

Command Line Example

Configuration

The following sections describe the configuration intended to support the AccessionReagentKitLots script.

Master Step Custom Fields

Configure master step custom fields (step UDFs in v4.x) for reagent kit name and lot name, and display them in the Step Details area of the Record Details screen. When running the step, the user fills in these values and they are supplied to the reagentKit and lotName parameters in the script. In this scenario, configure the automation command line as follows:

Automation trigger

The script is intended to be automatically triggered at the end of a step. However, you may include the -t option to run the script in test mode and trigger the script via button on the Record Details screen.

Rules and Constraints

• Reagent Kit Name specified in the command line must match a reagent kit configured in the LIMS.

• expiryDays parameter value must meet the following criteria:

  • Must be a whole number greater than 0.

Available from: Clarity LIMS v2.0.5.

Often, a user has certain values associated with libraries prior to preparing a flow cell. When loading the libraries into the flow cell, the user needs to track these values as attributes of the flow cell lane to help interpret the metrics generated during sequencing.

For example, one might need to record a concentration as a sample UDF on normalized and pooled libraries. This can be accomplished by copying the value of identically named UDFs from inputs to non-shared outputs.

Script Overview

The copyUDFs script provides the ability to selectively copy the value of an input UDF to a UDF of the same name on outputs generated by a protocol step (process). Other capabilities of this script include:

• The ability to map a single input to one or more outputs

• The ability to define which UDF is copied across to outputs

Script Parameters

Command Line Example

Constraints

• Only the UDFs named in the -f (fields) parameter will be copied.

• If input UDFs are not defined or have no value, nothing will be copied for those UDFs.

• UDFs not being defined on an output result in the script aborting after displaying an error message.

Available from: Clarity LIMS v2.0.5

This section discusses using the initArtifactUDFs script to transfer the UDFs associated with samples and processes to downstream artifacts. Typically, the script is used to copy UDFs from sample inputs and processes to sample outputs.

Script Overview

For each output, the initArtifactUDFs script searches for UDFs of the same name - in both the input samples and the process. If a match is found, it then copies the UDF values to the corresponding UDFs on the sample output.

How it works:

1. Identify the list of sample UDFs configured as output UDFs for this process (e.g. as would be defined in the 'Output Details' section of the process configuration).

2. For each sample UDF, look for an identically named UDF on the submitted sample; if a match exists, copy the value from the submitted sample to the sample's output UDF. If there is no UDF match, do nothing.

3. For each sample UDF, look for an identically named UDF on the process; if a match exists, copy the value from the process to the sample's output UDF. If there is no UDF match, do nothing.

Useful information

• If both process and any number of samples have values for the same UDF name, the process UDF value is used.

• If multiple samples have different values for the same UDF name, the values are combined using '+' as a separator (up to 5 values, additional values are omitted and represented with ''...').

• In the case where an output UDF value already exists, the initArtifactUDFs script will NOT override existing values. (This scenario is extremely rare - one has to be very fast to manually set UDF values before an EPP script runs.)

Script Parameters

Command Line Example

Clarity LIMS NGS Extensions Package v5.17 and later includes the validateCompletePlateStarted script. This script checks that all samples in a container were started together on the current step. This section provides details on the script and its parameters, and LIMS configuration requirements.

Script Overview

The purpose of the validateCompletePlateStarted script is to make sure that all of the samples in the input plate were started together. The validation supports partially-filled plates and multiple plates.

You can supply additional parameters to the script, to optionally enforce:

• 'Cannot proceed with partial plate' logic for only for the samples that are queued to the current step, instead of the entire plate contents. Default is false—the entire plate contents are verified.

• Contiguous row-major or column-major layout. This makes sure that the input plate(s) are in the expected layout and contain no gaps between the first and last sample. By default, this is not enforced.

Script Parameters

Command Line Examples

Configuration

The validateCompletePlateStarted script is intended to run when the user selects the Begin Work button on the Ice Bucket screen and starts the step.

To achieve this, configure the automation trigger as follows:

• Trigger Location: Step

• Trigger Style: Automatic upon entry

Available from: Clarity LIMS v1.0

This section discusses the normalizationBufferVolumes script, which is used to calculate buffer volumes.

Script Overview

The normalizationBufferVolumes script generates a comma-separated file — Normalization buffer volumes.csv — file that holds the calculated buffer volumes information. The generated file is a attached to the Library Normalization step in the LIMS.

The script calculates the 'Volume of Dilution Buffer (uL)' as follows:

• "Volume of Dilution Buffer (uL)" = ( ("Source Volume (uL)" * "Source Conc.") / "Destination Conc." ) - "Source Volume (uL)"

Script Parameters

Command Line Example

Configuration

The following step UDFs are configured on the Library Normalization step:

• Library volume (ul) transferred to DESTINATION plate: Numeric, Default = 10

• Normalized conc. (nM): Numeric, Default = 2

• Maximum destination container volume (ul): Numeric, Default = 800

The inputs to the step must have values for the following sample UDFs:

• Concentration: Numeric

• Conc. Units: Single Line Text

Rules & constraints

• One sample input generates one sample output and one shared result file.

• The CSV file header contains the date and a record of the user who generated the file.

• The contents of the CSV file are ordered by source plate and then source well.

Additional information

Other scripts you may find useful:

The Clarity LIMS NGS Extensions Package v5.14 and later includes the validateUniqueIndexes script. When defining a batch of samples for library prep, this script ensures that the resulting batch will be valid for later workflow steps - such as pooling or sample sheet generation.

This section provides details on the script, its parameters, and LIMS configuration requirements.

Script Overview

The validateUniqueIndexes script checks that the reagent labels (referred to as reagent types in LIMS v4.x and earlier) attached to the input samples have distinct index sequences.

Available from: Clarity LIMS v2.0.5

Often, a user wants to determine what work has been performed on several samples by running the Sample History Report. However, suppose they were to use the sampleHistoryReport script on 600 samples that involve the same four processes. The result would be 600 reports (one for each sample), each of which provides information on only that one sample.

A preferable alternative is to use the processHistoryReport script, which is run only once for each process. In this example, therefore, it would produce only four reports (one for each process) allowing for a better grouping of information and less files.

The Clarity LIMS NGS Extensions Package v5.14 includes the computeReplicateAverage script, which automates calculation of replicate (referred to as derivatives in the LIMS) average values. The script can also optionally calculate standard deviation and %CV values.

This section provides details on the script, its parameters, and LIMS configuration requirements.

Script Overview

The computeReplicateAverage script uses data stored in a source UDF / custom field (specified by the src parameter) to calculate the average across replicates, and writes the resulting value to a destination UDF / custom field (specified by the dest parameter).

The routing script allows for the movement of samples from one workflow to another. The script can move sample individually or in bulk.

• Individually — the script uses derived sample custom fields (analyte UDFs in v4.x)

• In bulk — the script uses master step custom fields (step UDFs in v4.x).

To move samples, first define the workflow and the step to which the samples will be sent. The script can be modified in the automation command line.

This section discusses the Routing script - Normalize Libraries automation used in the Illumina Preset Protocols (IPP). The automation invokes the changeWorkflow script, which routes step outputs to the next protocol in the workflow according to the Sequencing Instrument field value of each sample.

Automation Configuration

Command Line

The default automation command line for the routing script is as follows.

To send samples into a QC Protocol, use the protocol name instead of the name of the step name.

Script Parameters

Configuration Requirements

Next Step Configuration

For the routing script to be triggered, the Next Step value for all samples in the step must be set to Remove from workflow. You can set this value manually or automatically, using a script.

On the protocol configuration screen, in the Next Steps section, the method of assigning the next step must be set to Automatic.

Automation Trigger Configuration

By default, the routing script automation should be configured to be automatically triggered at the end of the step.

After the script has completed, a dialog box displays. This dialog box shows the number of samples routed to each step — or an error message if something went wrong.

Global Custom Fields / UDFs

The following table provides configuration details for the global custom field configured to support the routing script automation. This example is based on the Routing Script - Normalize Libraries automation.

The field is configured on Analyte in LIMS v4.2.x and Derived Sample in LIMS v5.x onwards.

Modifying the Default Configuration

You can modify the default configuration by removing / adding instruments.

Rules and Constraints

• The --FIELD_NAME and --FIELD_VALUE are only available for derived sample and master step custom fields.

• If no custom field should be checked, provide "N/A" to FIELD_NAME and FIELD_VALUE.

• If the --FIELD_VALUE parameter value passed to the script does not match the value in the --FIELD_NAME custom field, the routing script does not route the sample.

Available from: Clarity LIMS v2.0.5

A user may need to add reagent labels to sample outputs that do not have reagent labels assigned to them.

Script Overview

The labelNonLabeledOutputs script provides the ability to add reagent labels to sample outputs for which there is no pre-existing reagent label.

The script checks each process output for existing reagent labels; if an output does not have at least one pre-existing reagent label then the label supplied as a script parameter is applied.

• For each output that does not already have a reagent label applied to it (e.g. control samples), the script will apply a reagent label named with the supplied string.

• In the Preconfigured Package for Illumina NGS, all sequencing libraries go through a demultiplex process to both convert data to FASTQ and demultiplex reads if necessary. Note that presently, inputs that do not have a reagent label do not create an output in a demultiplex process even though we need BCL convertor to convert their reads to FASTQ.

Script Parameters

Command Line Example

You may also find the following script useful:

Clarity LIMS NGS Extensions Package v5.17 and later includes computeLinearRegression script. This script calculates values for slope, intercept, and r-squared, and uses these values to populate corresponding fields. The field names are configurable via script parameters, and will differ depending on the LIMS integration.

In addition, the script requires values for y-axis and x-axis. These values are both related to control samples:

• y-axis: This is configured as an analyte UDF / derived sample custom field on the control sample. The field name is configurable and is passed in as a script parameter.

The Clarity LIMS NGS Extensions Package includes the validateSampleCount script, which checks the number of samples being input to or output by the step.

This article provides details on the script and its parameters, and LIMS configuration requirements.

Script Overview

The script validates the number of step inputs or outputs, comparing it against configurable minimum and maximum values - determined by -min and -max parameters.

By default, the script runs in count inputs mode and validates the step inputs. If you supply the optional -o parameter with value set to true, the script runs in count outputs mode and validates the step outputs.

Script Parameters

Command Line Examples

Configuration

The validateSampleCount script is intended to run when the user clicks the Begin Work button on the Ice Bucket screen and starts the step.

To achieve this, configure the automation trigger as follows:

• Trigger Location: Step

• Trigger Style: Automatic upon entry

Available from: Clarity LIMS v2.0.5

Often, a user would like to set or change the value of a UDF. If the UDF is accessible from the initial process URI, the setUDF script can be used.

Script Overview

The setUDF script allows several operations to take place, including - but not limited to the following:

• Set a UDF on an output container to today's date.

• Set a UDF on any sample associated with any input to a person's name.

• Set a UDF on any output to a lab name (referred to as 'Account' in Clarity LIMS).

• Set the input container name as a process level UDF.

• Read a project UDF and set it on a sample.

Script Parameters

Examples

There are multiple ways to implement this script, as illustrated by the following examples.

Rules & constraints

• Both the target entity and (optionally) the source value are expressed as chains of XPath expressions (using -> as separators).

• Even if you are using XPath to specify the source value, setUDF applies a single value per invocation to all target objects. It cannot apply different source values to different target objects.

• You can use -z as an option when running the script to simulate the effects it would have. Note that even though an output identifying the target object(s) and the value that would be set is produced no changes are actually made.

Additional information

Other scripts you may find useful:

Last Updated: November 2024

Release Date: September 2023

Document Version: 2

These release notes detail the key changes to software components for the Next Generation Sequencing (NGS) Extensions Package v5.23.0.

Compatibility

Refer to under Instruments & Integrations.

New Features

• Updates Java and third-party dependency libraries.

• Updates Groovy to v3.0.7.

• Stopwatch parameter -s is replaced with the -stopwatch parameter for NGS 5.21.0 and later.

Defects Fixed

• The sample sheet for the MiSeq now shows the following information:

  • The pool name instead of the sample name when the pool contains only one sample.

  • The well and plate information for submitted samples instead of for libraries.

Known Issues

• An error occurs when reformatting the date using the Lab Logic Toolkit with the Date utility class. The date reformatting can be done with java.time instead.

Revision History

The Clarity LIMS NGS Extensions Package includes the place_indexes script, which assigns indexes (reagent labels) to samples in the destination container, based on the pattern defined in a specified index pattern file — and optionally validates the indexes against the pattern file.

This section provides details on the script and its parameters, and LIMS configuration requirement

Script Overview

The place_indexes script is intended to be run on entry to, and optionally on exit from, the Add Labels / Reagents screen of a step.

On entry to Add Labels / Reagents screen, the script assignes an index (label) to each sample in the destination container, based on the pattern defined in the specified index pattern file.

On exit from Add Labels / Reagents screen, the script validates the indexes against the pattern file. You can also use the script to check:

• If the user has modified the indexes.

• If the current step permits user modifications.

Script Parameters

Command Line Example

Pattern File

The index pattern file is a tab-separated file consisting of two columns, DEST_WELL and INDEX_NAME, and is in the following format:

The destination well format provided in the file must match the well placement configuration of the container type intended for use in the LIMS. The reagent index name must match the name of a reagent in the LIMS.

Validation

There are three levels of validation provided by the script:

• Index placement can be modified by the user on the fly.

• Index placement is locked down by an administrator and cannot be modified by the user.

• Index placement must be locked down by an administrator prior to use.

Two options determine which level of validation to apply:

• The presence of a corresponding checksum file for the given pattern file.

• The presence of the locked script parameter.

When there is no checksum file, and locked is not provided to the script (or is provided as false), index placement is user-modifiable.

Checksum file

If the reagent index placement pattern is not user-modifiable, an administrator can create a checksum file to ensure that the user has not changed the index placement on the fly.

This checksum file should have the same name as the placement pattern file, but with the file extension .md5. For example:

• placement_pattern_index_pcramp_01.tsv

• placement_pattern_index_pcramp_01.md5

The checksum file must be placed in the same location as the corresponding index pattern file. When a checksum file is found and the user has modified the indexes on the samples in the step, the script reverses the changes made by the user.

The checksum file contains the .md5 checksum for the corresponding pattern file itself. This checksum value is compared against the pattern file to validate whether the pattern file has been modified. If it has been modified, the script displays an error message and index placement does not occur. If an administrator wishes to change the pattern file contents, they must also regenerate the checksum when the updated pattern is available for use.

Locked patterns

The locked parameter provides an additional layer of validation. If this is provided to the script, the current pattern requires the presence of a checksum file. This ensures that an administrator has approved the pattern for use before it is used in a step.

Ignored categories

In some steps where reagent autoplacement is configured, there may be some reagent categories where this is not desired.

For example, the workflow may permit either a full 96 well plate of samples in the indexing step, or merely 8 samples in tubes. For the 8 samples, a different reagent category is used than for the batch of 96. In this case, the ignoredCategory parameter may be used to indicate that if the 8-sample reagent category is selected for the step, index placement will be performed manually.

Configuration

The place_indexes script is intended to be run on entry to / exit from the Add Labels / Reagents screen of a step.

To achieve this, configure the automation trigger as follows:

• Trigger Location: Add Labels screen

• Trigger Style: Automatic upon entry / exit

Rules and Constraints

• The step must be configured for adding reagent indexes.

• The script must run on entry to or exit from the Add Labels / Reagents screen.

• The pattern file must be a tab-separated (.tsv) file.