Route Artifacts Based Off a Template File

Workflows do not always have a linear configuration. There are situations when samples progressing through a workflow must branch off and be directed to different stages, or even different workflows. You can add samples to a queue using the /api/{version}/route/artifacts endpoint.

In the lab, decisions are made dynamically. At the initiation of this example workflow, it is not known whether the sample is destined to be sequenced on a HiSeq or MiSeq instrument. As a result, the derived samples must be routed to a different workflow stage midworkflow.

This programmatic approach to queuing samples can be used many times throughout a workflow. This approach eliminates the need to write multiple complex scripts - each of which must be maintained over time.

This example describes a Python script that takes instruction from a .csv template file. Removing any hard-coded reference to specific UDFs / custom fields or workflow stages from the script allows for easy configuration and support. All business logic can be implemented solely through generation of a template and EPP / automation command.

The template contains UDF / custom field names and values. If samples in the active step have fields with matching values, they are queued for the specified workflow stage.

Step Configuration

The step is configured to display the two checkbox analyte UDFs / derived sample custom fields. These fields are used to select the destination workflow stages for each derived sample / analyte. You can queue the sample for HiSeq, MiSeq, or both.

In the preceding example of the Sample Details screen, the user selected:

• Two samples to be queued for HiSeq

• Two samples for MiSeq

• Two samples where routing is not selected

• Two samples for both HiSeq and MiSeq

In the preceding example of the Step Details screen, the user selected:

• A step level UDF / custom field to assign all samples to a given step. All output samples are routed to the associated step. Samples can be duplicated in the first step of the following protocol if:

• Samples are routed as the last step of a protocol and;

• The action of the next step is Mark Protocol as Complete.

The duplication is due to the Next Steps action queuing the artifact for its default destination in addition to the script routing the same artifact.

The solution here is to set the default Next Steps action to Remove from Workflow instead. This action can be automated using the Lab Logic Toolkit or the API.

LIMS v6.x

On the protocol configuration screen, make sure that Start Next Step is set to Automatic.

Template Configuration

Each UDF name and value pair correspond to a workflow and stage combination as the destination to route the artifact.

• The UDF name in the template could be configured as a step or analyte level UDF. If a step level UDF has a value that is specified in the template, all analytes in the step are routed.

• The UDFs can be of any type (Numeric, Text, Checkbox ). If a checkbox UDF is used, the available values are true or false.

• UDF values in the template are not case-sensitive.

The template requires four columns:

• UDF_NAME

• UDF_VALUE

• WORKFLOW_NAME

• STAGE_NAME

For this example, the template values would be:

• UDF_NAME, UDF_VALUE, WF_NAME, STAGE_NAME

• Route all samples to: Step A, Workflow A, Stage A

• Route all samples to: Step B, Workflow B, Stage B

• Route A, True, Workflow A, Stage A

• Go to HiSeq, True, TruSeq Nano DNA for HiSeq 5.0, Library Normalization (Illumina SBS) 5.0

• Go to MiSeq, True, TruSeq DNA PCR-Free for MiSeq 5.0, Sort MiSeq Samples (MiSeq) 5.0

This script might be used numerous times in different EPP / automation scripts, with each referencing a different template.

Using a Template String Instead of a Template File

Due to restrictions on file server access, this script accepts routing template instructions using a string EPP parameter with lines separated by a newline character ('\n'). The following example shows how this parameter string would be added to represent the previous template:

"Route all samples to:, Step A, Workflow A, Stage A\nRoute all samples to:, Step B, Workflow B, Stage B\nRoute A, True, Workflow A, Stage A\nGo to HiSeq, True, TruSeq Nano DNA for HiSeq 5.0, Library Normalization (Illumina SBS) 5.0\nGo to MiSeq, True, TruSeq DNA PCR-Free for MiSeq 5.0, Sort MiSeq Samples (MiSeq) 5.0"

Required Parameters

The EPP/automation that calls the script must contain the following parameters:

-p	--password	The password of the current user (Required)
-s	--stepURI	The URI of the step that launches the script, the {stepURI:v2} token (Required)
-l	--log	The path, or limsid of the log file, the {compoundOutputFileLuidN} token (Required)
-t	--template	The path to the template file (Required)*
-r	--template_string	A string containing the template information (Required)*

*Either --template or --template_string is required. If both are provided, --template_string is used.

Optional Parameter

--input

Uses the input artifacts instead of output artifacts. Default = False

When the --input parameter is used, the script routes input artifacts instead of the default output artifacts. UDF values of the input artifacts (instead of outputs) are against the template file.

An example of the full syntax to invoke the script is as follows:

bash -c "/usr/bin/python /opt/gls/clarity/customextensions/Route_by_template.py -u {username} -p {password} -s {stepURI:v2} -t /opt/gls/clarity/customextensions/routing_template.csv -l {compoundOutputFileLuid0}"

Or, if you wish to route the inputs instead of outputs:

bash -c "/usr/bin/python /opt/gls/clarity/customextensions/Route_by_template.py --input -u {username} -p {password} -s {stepURI:v2} -t /opt/gls/clarity/customextensions/routing_template.csv -l {compoundOutputFileLuid0}"

User Interaction

When the Record Details screen is entered, the UDF / custom field checkboxes or drop-down options specify to which workflow/stage combination each derived sample is sent.

About the Code

The first important piece of information required is the URI of the destination stage. There is a unique stage URI assigned to each workflow and stage combination.

A stage URI can change across LIMS instances (such as switching from Dev to Prod). Therefore, the script gathers the stage URI from the workflow and stage name. This process occurs even when the workflows are identical.

The main method in the script is routeAnalytes() and it carries out several operations:

1. Gathers the information for the process that triggered the script, including output (or input) analytes.

2. For each analyte, evaluates which UDFs have been set, and adds the analyte to a list of analytes to route.

3. Creates the XML message for each stage.

4. Does a POST to the REST API to add the analytes to the queue in Clarity LIMS

This example, while in itself useful, also serves to demonstrate a more general concept. Routing artifacts is valuable in any situation where a sample must be queued for a stage outside of the usual order of a workflow. This routing is applicable even when routing newly submitted samples to the first stage in a workflow.

For more information, see the artifact/route REST API documentation.

Assumptions and Notes

• You are running a version of Python supported by Clarity LIMS, as documented in the Clarity LIMS Technical Requirements.

• The attached files are placed on the LIMS server, in the /opt/gls/clarity/customextensions folder.

• The Python API Library (glsapiutil.py) is placed on the Clarity LIMS server, in the /opt/gls/clarity/customextensions folder. You can download the latest glsapiutil library from the GitHub page.

• The example code is provided for illustrative purposes only. It does not contain sufficient exception handling for use 'as is' in a production environment.

Attachments

routing_template.csv:

303B

routing_template.csv

route_by_template.py:

7KB

route_by_template.py