Retrieve Multiple Entities with a Single API Interaction

In Clarity LIMS, you want to process multiple entities. To accomplish this quickly and effectively, you can use batch operations, which allows you to retrieve multiple entities using a single interaction with the API, instead of iterating over a list and retrieving each entity individually.

Batch operations greatly improve the performance of the script. These methods are available for containers and artifacts. In this example, both entities are retrieved using the batchGet() operation. If you would like to update a batch of output analytes (derived samples), you can increase the script execution speed by using batch operations. For more information, refer to Work with Batch Resources and Introduction to Batch Resources.

Prerequisites

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

• Several samples have been added to the LIMS.

• A process / step that generates derived samples in containers has been run on the samples.

• A compatible version of API (v2 r21 or later).

Code Examples

When derived samples ('analyte artifacts' in the API) are run through a process / step, their information can be accessed by examining that process / step. In this example, we will retrieve all of the input artifacts and their respective containers.

To do this effectively using batch operations, we must collect all of the entities' URIs. These URIs must be unique, otherwise the batch operation will fail. Then, all of the entities can be retrieved in one action. It is important to note that only one type of entity can be retrieved in a call.

Groovy Example

Step 1. Retrieve the Process Information

To retrieve the process step information, use the GET method with the process LIMS ID:

processURI = "http://${hostname}/api/v2/processes/${processLIMSID}"
processNode = GLSRestApiUtils.httpGET(processURI, username, password)

Step 2. Retrieve the Artifact URIs

To retrieve the artifact URIs, collect the inputs of the process's input-output-map. A condition of the batchGET operation is that every entity to get must be unique. Therefore, you must call unique on your list.

def inputUris = processNode.'input-output-map'.collect { it.'input'[0].@uri }.unique()

Step 3. Retrieve Unique Input Analytes and Their Containers

You can now use batchGET to retrieve the unique input analytes:

def inputNodes = GLSRestApiUtils.batchGET(inputUris, username, password) 

The same can be done to gather the analytes' containers:

def containerUris = inputNodes.collect { it.'location'.'container'[0].@uri }.unique()
def containerNodes = GLSRestApiUtils.batchGET(containerUris, username, password)

Expected Output and Results

You have collected the unique containers in which the artifacts are located. By printing the name and URI of each container, an output similar to the following is obtained.

AutomatedTestContainer-549374968
http://yourIpAddress/api/v2/containers/27-1478 

Python Example

Step 1. Retrieve the Step Information

To retrieve the step information, use the GET method with the step LIMS ID:

stepXML = api.GET( stepURI + "/details" )

Step 2. Retrieve the Artifact URIs

To retrieve the artifact IDs, collect the inputs of the step's input-output-map. A condition of the batch retrieve operation is that every entity to get must be unique. To do this, you add the LUIDs to a set().

LUIDs = set()
for inputArtifact in parseString( stepXML ).getElementsByTagName( "input" ):
    artifactLUID = inputArtifact.getAttribute( "limsid" )
    LUIDs.add( artifactLUID )

Step 3. Retrieve Unique Input Analytes

You can now use the function getArtifacts(), which is included in the glsapiutils.py to retrieve the unique input analytes:

batchXML = api.getArtifacts( LUIDs ) 

Attachments

UsingBatchGet.groovy:

2KB

UsingBatchGet.groovy

Batchexample.py:

1KB

Batchexample.py