Work with the Steps Pooling Endpoint

Pooling steps require that each input analyte artifact (derived sample) in the step be inserted into a pool. You can automate this task by using the API steps pooling endpoint. Automation of pooling allows you to reduce error and user interaction with Clarity LIMS.

In this example, a script pools samples based on the value of the pool id user-defined field (UDF)/custom field of the artifact.

As of Clarity LIMS v5, the term user-defined field (UDF) has been replaced with custom field in the user interface. However, the API resource is still called UDF.

There are two types of custom fields:

• Master step fields—Configured on master steps. Master step fields only apply to the following:
• The master step on which the fields are configured.
• The steps derived from those master steps.
• Global fields—Configured on entities (eg, submitted sample, derived sample, measurement, etc.). Global fields apply to the entire Clarity LIMS system.

To keep this example simple, the script does not handle samples with reagent labels.

In the API, an artifact is an item generated by an earlier step. There are two types of artifacts: analyte (derived sample) and resultfile (measurement). In the Clarity LIMS web interface, the terms artifact, analyte, and resultfile have been replaced with derived sample or measurement. However, in Clarity LIMS v4.2 and earlier, some areas of the Operations Interface still refer to the former terms.

Before you follow the example, make sure that you have the following items:

• A configured analyte UDF/derived-sample custom field named pool id in Clarity LIMS.
• Groovy that is installed on the server and accessible at /opt/groovy/bin/groovy.
• The GLSRestApiUtils.groovy file that is stored in /opt/groovy/lib/.
• The WorkingWithStepsPoolingEndpoint.groovy script that is stored in /opt/gls/clarity/customextensions/.
• A compatible version of API (v2 r21 or later).
1. In the Clarity LIMS Operations Interface, in the Configuration area, select the pooling step to automate. Select Modify.
2. On the Attributes tab, select the Allow pooling of artifacts with the same reagentcheck box.

This example does not handle input artifacts with reagent labels.

3. On the External Programs tab, associate the process with the WorkingWithStepsPoolingEndpoint.groovy script. The command line call used in this example is as follows.

bash -c "/opt/groovy/bin/groovy -cp /opt/groovy/lib /opt/gls/clarity/customextensions/WorkingWithStepsPoolingEndpoint.groovy -u {username} -p {password} -s {stepURI:v2:http}"

1. In the Clarity LIMS web interface, create a protocol and add the following two steps:
• The add pool id step that sets the pool id UDF of the artifacts.
• The pooling step modified in Step 1. Modify Pooling Step.

2. Modify the add pool id step and drag the pool id UDF into the Selected Fields area, making it editable in Record Details view.
3. Modify the pooling step once more. This time, on the Automation tab, configure the automation so that so that the script is automatically initiated at the beginning of the step.
1. Create a workflow containing the protocol created in Step 2. Create Protocol, Display pool id UDF, and Configure Automation Trigger.
2. Create a project and add samples to it. Assign those samples to the workflow.
1. Begin working on the samples. In the first step, enter values into the pool id UDF.
2. Continue to the pooling step and add samples to the Ice Bucket. Select Begin Workto execute the script.
1. In Clarity LIMS, under Configuration, select the Lab Work tab.,
2. Select an existing Pooling master step or add a new one.

3. On the master step configuration form, select the Pooling milestone.
4. On the Pooling Settings form, set the Label Uniqueness toggle switch to Off.
5. Select Save.
6. Add a new protocol.
7. With the protocol selected, add a new Library Pooling step based on the master step you configured.
1. In Clarity LIMS, under Configuration, select the Automation tab.
2. Add a new step automation. Associate the automation with the WorkingWithStepsPoolingEndpoint.groovy script. The command line used in this example is as follows.

bash -c "/opt/groovy/bin/groovy -cp /opt/groovy/lib /opt/gls/clarity/customextensions/WorkingWithStepsPoolingEndpoint.groovy -u {username} -p {password} -s {stepURI:v2:http}"

3. Enable the automation on the configured pooling master step. Select Save.

You can now configure the automation trigger on the step or the master step. If you configure the trigger on the master step, the settings will be locked on all steps derived from the master step.

4. On the Lab Work tab, select the library pooling step or master step.
5. On the Step Settings or Master Step Settings form, in the Automation section, configure the automation trigger so that the script is automatically initiated at the beginning of the step:
• Trigger Location—Step
• Trigger Style—Automatic upon entry

1. In Clarity LIMS, under Configuration, select the Lab Work tab.
2. Select the pooling protocol containing the Library Pooling step.
3. Add the Add Pool ID step that sets the pool id custom field of the samples. Move this step to the top of the Steps list.

4. Select the Add Pool ID step.
5. On the Record Details milestone, add the pool id custom field to the Sample Details table.

1. In Clarity LIMS, under Configuration, select the Lab Work tab.
2. Create a workflow containing the configured pooling protocol. Activate the workflow.

3. On the Projects and Samples screen, create a project and add samples to it. Assign the samples to your pooling workflow.

1. Begin working on the samples. In the first step, enter values into the pool id custom field.

2. Continue to the Library Pooling step and add samples to the Ice Bucket. Select Begin Workto execute the script.

The script is passed the URI of the pooling step. Then, using the URI, the pool node of the step is retrieved. This node contains an available-inputs node that lists the URIs of the available input artifacts.

// Get the pool for this step poolNode = GLSRestApiUtils.httpGET(stepURI + '/pools', username, password) poolNode.'available-inputs'.'input'.each{ artifact_uris.add(it.@uri) }

The script retrieves all available input artifacts, and then iterates through the list of retrieved artifacts. For each artifact, the script looks for the pool id custom field. If the field is not found, the script moves on to the next artifact. If the field is found, its value is stored in the poolID variable.

When the script encounters a new pool ID, it creates a new pool with a name equal to that ID. Input artifacts are sorted into pools based on the value of its pool id field, and as they are inserted into pools they are removed from the list of available inputs.

// Get all input artifacts artifacts = GLSRestApiUtils.batchGET(artifact_uris, username, password) // Iterate through retrieved artifacts artifacts.each { // If the artifact has a UDF pool ID, then pool the artifact and remove it from the available-inputs node poolID = it.find { artifact_field -> artifact_field.@name == POOL_ID_UDF}?.value()[0] if (poolID != null) { // If a new pool ID is encountered, then use that new pool ID as the name for a new pool node if (!poolNode.'pooled-inputs'.'pool'.find { pool -> pool.@name == poolID }) { newPool = NodeBuilder.newInstance().pool(name:poolID) poolNode.'pooled-inputs'[0].append(newPool) } inputNode = NodeBuilder.newInstance().input(uri:it.@uri) // Add the input artifact to the pool with the name equal to 'poolID' poolNode.'pooled-inputs'.'pool'.find { poolID == it.@name }.append(inputNode) // Remove the input artifact from the 'available-inputs' node contained in the pool node poolNode.'available-inputs'[0].remove(inputNode) } }

After all of the available inputs are iterated through, the updated pool node is sent back to Clarity LIMS:

//Update the pool for this step and examine the result data resultNode = GLSRestApiUtils.httpPUT(poolNode, poolNode.@uri, username, password)

Artifacts with the same Pool ID UDF/custom field will be automatically added to the same pool.

• WorkingWithStepsPoolingEndpoint.groovy.txt
• GLSRestApiUtils.groovy.txt