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.

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

Prerequisites

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

Example

Step 1. Add Master Step, Protocol, and Library Pooling Step

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.

   

Step 2. Configure Step Automation and Trigger

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:

   1. Trigger Location—Step

   2. Trigger Style—Automatic upon entry

      

Step 3. Configure Protocol and Add Pool ID Step

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.

   

Step 4. Create Workflow and Add Samples

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.

   

Step 5. Run Samples Through the Steps

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 Work to execute the script.

   

How the script works

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)

Expected Output and Results

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

Attachments

WorkingWithStepsPoolingEndpoint.groovy:

3KB

WorkingWithStepsPoolingEndpoint.groovy

GLSRestApiUtils.groovy:

10KB

GLSRestApiUtils.groovy