When working with containers, you can do the following:
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\
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.
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:
The name parameter is repeatable, and the results returned match any of the names queried:
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:
If the system has no containers named Smith553 or 001TGZ, then containers.container is an empty list. The .each method does nothing, as expected.
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).
GetContainerNameFilter.groovy:
When a lab processes samples, the samples are always in a container of some sort (eg, a tube, a 96-well plate, or a flow cell). In Clarity LIMS, this processing is modeled by placing all samples into containers. Because the Clarity LIMS interface relies on container placement for the display of many of its screens, adding containers is a critical step when running a process or adding samples through the API (v2 r21 or later).
The following example demonstrates how to add an empty container, of a predefined container type, to Clarity LIMS through the API.
If you would like to add a batch of containers to the system, you can increase the script execution speed by using batch operations. For more information, refer to the API Portal and the articles in the Working with Batch Resources section.
Before you can add a container to the system, you must first define the container to be created. You can construct the XML that defines the container using StreamingMarkupBuilder, a built-in Groovy data structure designed to build XML structures.
To construct the XML, you must declare the container namespace because you are building a container. The minimum information that can be specified to create a container are the container name and container type.
If you also want to add custom field values to the container you are creating, you must declare the userdefined namespace.
NOTE: 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.
The POST command posts the XML constructed by StreamingMarkupBuilder to the containers resource of the API. The POST command also adds a link from the containers URI (the list of containers) to the new container.
The XML for the new container is as follows.
The XML for the list of containers, with the newly added container shown at the end of the list, is as follows.
For Clarity LIMS v5 and above, the Operations Interface Java client has been deprecated, and there is no equivalent Containers view screen in which to view empty containers added via the API. However, if you intend to add samples to Clarity LIMS through the API, this example is still relevant, as you must first add containers in which to place those samples.
PostContainer.groovy:
As samples are processed in the lab, they are kept in a container. Some of these containers hold multiple samples, and lab scientists often must switch between container tracking and sample tracking.
If you process several containers each day and track them in a list, you would need to find which samples are in those containers. This way, you can record specifics from these container-based activities in relation to the samples from Clarity LIMS.
The example finds which sample is in a given well of a multi-well container using Clarity LIMS and API (v2 r21 or later).
Before you follow the example, make sure that you have the following items:
Several samples exist in the Clarity LIMS.
A step has been run on the samples.
The outputs of the step have been placed in a 96-well plate.
Clarity LIMS captures detailed information for a container (eg, 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 (eg, the placement elements for a 96-well plate include A:1, B:5, E:2).
In the script, the GET request retrieves the container specified by the container LIMS ID provided as input to the {containerLIMSID} parameter. The XML representation returned from the API is stored as the value of the container variable:
The following example shows the XML format returned for a container. The XML includes a placement element for each artifact that is placed in a well location in the container.
When you look for the artifact at the target location, the script searches through the placement elements 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.
The >uri attribute of the matching placement element is the URI of the artifact that is in the target well location. This is stored as the value of the artifactURI variable, and printed as the output of the script:
Running the script in a console produces the artifact at
GetContentsOfWellLocation.groovy: