Filter Containers by Name

Samples in the lab are always in a container (eg, a tube, plate, or flow cell). When a container holds more than one sample, it is often easier to track the container rather than the individual samples. These containers can be found in API (v2 r21 or later).

In Clarity LIMS, containers are identified the LIMS ID or by name. The best way to find a container in the API is with the LIMS ID. However, the API also supports searching for containers by name by using a filter.

• LIMS ID—This is a unique ID. The container resource with LIMS ID 27-42 can be found at\

  http://<YourIPaddress>/api/containers/27-42.

• Name—Container names can be unique, depending on how the server software was set up. In some labs, container names are reused to show when a container is recycled or when samples are submitted in containers.

The following example shows a container list filtered by name. Your system contains a series of containers, named with a specific naming convention.

Code example

the queried containers are named Smith553 and 001TGZ.

The request for a container with a specific name is structured in the same way as the request for all containers, but also includes a parameter to filter by name:

http://<YourIPaddress>/api/<apiversion>containers?name=<yourcontainername>

The name parameter is repeatable, and the results returned match any of the names queried:

// Determine the containers URIs and retrieve them
containersURI = "http://${hostname}/api/v2/containers?name=" + URLEncoder.encode('Smith553') + "&name=" + URLEncoder.encode('001TGZ')
containers = GLSRestApiUtils.httpGET(containersURI, username, password)
 
// For each container, print its limsid
containers.'container'.each {
    println it.@limsid
}

The GET method returns the full XML structure for the list of containers matching the query. In this case, the method returns the XML structure for containers with the names Smith553 and 001TGZ.

The XML contains a list of container elements. The .each method goes through each container node in the list and prints the container LIMS ID.

The XML returned is placed in the variable containers:

<con:containers>
    <container uri="http://yourIPaddress/api/v2/containers/27-505" limsid="27-505">
        <name>Smith553</name>
    </container>
    <container uri="http://yourIPaddress/api/v2/containers/27-511" limsid="27-511">
        <name>001TGZ</name>
    </container>
</con:containers> 

If the system has no containers named Smith553 or 001TGZ, then containers.container is an empty list. The .each method does nothing, as expected.

Expected Output and Results

When execution completes, the code returns the list of LIMS IDs associated with the container names Smith553 and 001TGZ. The name and LIMS IDs are different in this case (eg, 27-505 27-511).

Attachments

GetContainerNameFilter.groovy:

1KB

GetContainerNameFilter.groovy