Finding the Contents of a Well Location in a Container

Compatibility: API version 2 revision 21 and later

As samples are processed in the lab, they are kept in a container of some sort. Some containers may hold multiple samples, and lab scientists often need to switch between container tracking and sample tracking.

Imagine a lab scientist who processes several containers each day and tracks them in a list. To record specifics from these container-based activities in relation to the samples in Clarity LIMS, they will need to find which samples are in those containers.

This example finds which sample is located in a given well of a multi-well container.

Prerequisites

• Several samples exist in the LIMS.
• A step has been run on the samples.
• The outputs of the step have been placed in a 96-well plate.

Code Example

Clarity LIMS captures detailed information for a container - its name, LIMS ID, and the names of the sample in each of its wells.

Information about the container and what it currently contains is available in the individual XML resource for the container.

• The individual container resource contains a placement element for each sample placed on the container.
• Each placement element has a child element, named value, that describes one position on the container. For example, the placement elements for a 96-well plate include A:1, B:5, E:2.

Step 1: Retrieve the container information

In the following script:

1. The GET request retrieves the container specified by the container LIMS ID provided as input to the {containerLIMSID} parameter.
2. The XML representation returned from the API is stored as the value of the container variable.

// Determine the specified container's URI and retrieve it

containerURI = "http://${hostname}/api/v2/containers/${containerLIMSID}"

container = GLSRestApiUtils.httpGET(containerURI, username, password)

An example of the XML format returned for a container is shown below. The XML includes a placement element for each artifact that is currently placed in a well location in the container.

<con:container uri="http://yourIPaddress/api/v2/containers/27-1259" limsid="27-1259">

<name>PC0006</name>

<type uri="http://yourIPaddress/api/v2/containertypes/1" name="96 well plate"/>

<occupied-wells>96</occupied-wells>

<placement uri="http://yourIPaddress/api/v2/artifacts/HAM751A495PA1" limsid="HAM751A495PA1">

<value>B:3</value>

</placement>

<placement uri="http://yourIPaddress/api/v2/artifacts/HAM751A496PA1" limsid="HAM751A496PA1">

<value>B:4</value>

</placement>

<placement uri="http://yourIPaddress/api/v2/artifacts/HAM751A493PA1" limsid="HAM751A493PA1">

<value>B:1</value>

</placement>

<placement uri="http://yourIPaddress/api/v2/artifacts/HAM751A497PA1" limsid="HAM751A497PA1">

<value>B:5</value>

</placement>

</con:container>

Step 2: Find the artifact URI

To find the artifact at the target location:

1. The script searches through the placement elements looking for one with a value element that matches the target. If a match is found, it is stored as the value of the contents variable.
2. The >uri attribute of the matching placement element is the URI of the artifact that is currently in the target well location. This is stored as the value of the artifactURI variable, and printed as the output of the script.

// Print the artifact that is located at the specified placement

contents = container.placement.find { it.value.text() == targetPlacement }

artifactURI = contents?.@uri

println artifactURI

Expected Output and Results

Running the script in a console produces the following output:

http://yourIPaddress/api/v2/artifacts/HAM751A496PA1

Attachments

GetContentsOfWellLocation.groovy