Routing Script | Clarity LIMS

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.

The default command line includes one section, and will always send the samples to the same workflow. To offer multiple workflow and/or step choices, you must add multiple sections, as shown in the following examples.

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

Script Parameters

Example 1

This example route the output without checking the UDF name and value

Example 2

Routing script configured on DNA/RNA Extraction step in TruSight Tumor 170 v1.0 workflow

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.

Set the next step manually

At run time, on the Assign Next Steps screen, the lab scientist sets the Next Step value to Remove from workflow.

ℹ The Remove from workflow option is only available on the Assign Next Steps screen for users who have the RemoveSampleFromWorkflow permission. If you use the manual method, you must make sure that users who need to set this option at run time have the correct permission. For details on configuring role-based permissions, see the Core LIMS documentation.

Set the next step automatically

Add the following script to an automation command line enabled on the step. Configure the protocol and set the Assign Next Step function to Automatic.

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.

To remove an instrument

Remove the unwanted FIELD_VALUE from the list of presets.
In the automation command line, remove the section that corresponds to the unwanted FIELD_VALUE.

To add an instrument

Add a field option / preset for the new FIELD_VALUE.
Add a section in the routing script command line to set the parameters for the additional FIELD_VALUE.
For example, to add "New instrument" to the Routing Script - Normalize Libraries automation, add the following to the end of the script:

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.