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 Batch Resources Overview and Introduction to Batch Resources.
Prerequisites
Before you follow the example, make sure that you have the following items:
| • | Several samples that have been added to Clarity 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 Example
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, you retrieve the input artifacts and their respective containers.
To do this effectively using batch operations, we must collect the URIs of the entities. These URIs must be unique, otherwise the batch operation fails. Then, 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 input-output-map of the process. 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 containers of the analytes:
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 input-output-map of the step. 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 )
