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 Preconfigured Workflow Package (PCWP). 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.

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.

-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

Routing script configured on Normalize Libraries steps in PCWP v1.0

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 'Sequencing Instrument' \

--FIELD_VALUE 'MiSeq' \

--WORKFLOW 'MiSeq Sequencing v1.0' \

--STEP 'Library Pooling (MiSeq v1.0)' \

--INPUTS_OR_OUTPUTS 'OUTPUTS' \

\

--FIELD_NAME 'Sequencing Instrument' \

--FIELD_VALUE 'NextSeq' \

--WORKFLOW 'NextSeq 500/550 Sequencing v1.0' \

--STEP 'Library Pooling (NextSeq 500/550 v1.0)' \

--INPUTS_OR_OUTPUTS 'OUTPUTS' \

\

--FIELD_NAME 'Sequencing Instrument' \

--FIELD_VALUE 'HiSeq2500' \

--WORKFLOW 'HiSeq 2500 Sequencing v1.0' \

--STEP 'Library Pooling (HiSeq 2500 v1.0)' \

--INPUTS_OR_OUTPUTS 'OUTPUTS' \

\

--FIELD_NAME 'Sequencing Instrument' \

--FIELD_VALUE 'HiSeq3000/4000' \

--WORKFLOW 'HiSeq 3000/4000 Sequencing v1.0' \

--STEP 'Library Pooling (HiSeq 3000/4000 v1.0)' \

--INPUTS_OR_OUTPUTS 'OUTPUTS' \

\

--FIELD_NAME 'Sequencing Instrument' \

--FIELD_VALUE 'HiSeqX' \

--WORKFLOW 'HiSeq X Sequencing v1.0' \

--STEP 'Library Pooling (HiSeq X v1.0)' \

--INPUTS_OR_OUTPUTS 'OUTPUTS' \

\

--FIELD_NAME 'Sequencing Instrument' \

--FIELD_VALUE 'NovaSeq' \

--WORKFLOW 'NovaSeq 6000 v2.0' \

--STEP 'Define Run Format (NovaSeq 6000 v2.0)' \

--INPUTS_OR_OUTPUTS 'OUTPUTS'"

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'"

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}"

 

LIMS v5.x

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

LIMS v4.2.x

In the protocol configuration area, on the Next Steps configuration tab, the Next Steps are set by a script toggle switch. Set this switch to Yes.

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.

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.

Field Name

Field Type

Field Constraints / Options

Preset Values / Dropdown Items

Sequencing Instrument
• Single-line Text (v4.2.x)
• Text Dropdown (v5.x)
• Required: Yes
• Read Only: No
• Custom Entries: No
• MiSeq
• NextSeq
• HiSeq2500
• HiSeq3000/4000
• NovaSeq
• HiSeqX

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'"

• 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.