Routing Script

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.

bash -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -u {username} -p {password} -i {stepURI:v2} -l {compoundOutputFileLuid0} script:changeWorkflow \
\
--FIELD_NAME 'Name of the field' \
--FIELD_VALUE 'Preset value of the field' \
--WORKFLOW 'Name of the workflow' \
--STEP 'Name of the Step in the workflow \
--INPUTS_OR_OUTPUTS 'One or the other'"

ℹ️ 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

Parameter	Description
-i {lims step uri} -stepURI {lims step uri}	LIMS step URI (Required)
-u {username} -username {username}	LIMS login username (Required - requires admin credentials)
-p {password} -password {password}	LIMS login password (Required)
-l <log file path and name> -logFileName <log file path and name>	Path destination for the log file (Required)
--FIELD_NAME	LIMS custom field name (derived sample (analyte) or step)
--FIELD_VALUE	LIMS UDF preset /custom field option value If the field type is a check box/toggle, the --FIELD_VALUE should be set as 'true' or 'false'
--WORKFLOW	Name of LIMS workflow to which the samples will be sent
--STEP	LIMS step within the workflow
--INPUTS_OR_OUTPUTS	Specifies whether the LIMS UDF / custom field is from the input or the output

Example 1

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

--FIELD_NAME 'N/A' \
--FIELD_VALUE 'N/A' \
--WORKFLOW 'NovaSeq 6000 v3.8' \
--STEP 'AUTOMATED - NovaSeq Run (NovaSeq 6000 v3.8)' \
--INPUTS_OR_OUTPUTS 'OUTPUTS' \

Example 2

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

bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -u {username} -p {password} -i {stepURI:v2} -l {compoundOutputLuid0} script:changeWorkflow \
\
--FIELD_NAME 'Sample Type' \
--FIELD_VALUE 'RNA' \
--WORKFLOW 'TruSight Tumor 170 v1.0' \
--STEP 'Qubit RNA QC (TruSight Tumor 170 v1.0)' \
--INPUTS_OR_OUTPUTS 'OUTPUTS' \
\
--FIELD_NAME 'Sample Type' \
--FIELD_VALUE 'DNA' \
--WORKFLOW 'TruSight Tumor 170 v1.0' \
--STEP 'Qubit DNA QC (TruSight Tumor 170 v1.0)' \
--INPUTS_OR_OUTPUTS 'OUTPUTS'"

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.

bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar
-i {stepURI:v2} -u {username} -p {password} script: evaluateDynamicExpression -t false -h false
-exp 'nextStep = ::REMOVE::' -log {compoundOutputFileLuid0}"

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.

Field Name	Field Type	Field Constraints / Options	Preset Values / Dropdown Items
Sequencing Instrument	Single-line Text (v4.2.x) Text Dropdown (v5.x and later)	Required: Yes Read Only: No Custom Entries: No	MiSeq NextSeq NovaSeq

Modifying the Default Configuration

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

To remove an instrument

1. Remove the unwanted FIELD_VALUE from the list of presets.

2. In the automation command line, remove the section that corresponds to the unwanted FIELD_VALUE.

To add an instrument

1. Add a field option / preset for the new FIELD_VALUE.

2. 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:

   \
   --FIELD_NAME 'Sequencing Instrument' \
   --FIELD_VALUE 'New instrument' \
   --WORKFLOW 'Workflow name for New instrument' \
   --STEP 'Step of the Workflow for New instrument' \
   --INPUTS_OR_OUTPUTS 'OUTPUTS'"

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.

• The routing script works with the Remove from workflow function in the Next Steps of any step. Make sure that the correct settings or permissions are in place to allow for this function. For details, see the preceding Configuration Requirements section.