Add an Empty Container to the System
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 Batch Resources Overview section.
Code Example
Step 1: Define the New Container
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.
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.
// Determine the containers list URI
String containersListURI = "http://${hostname}/api/v2/containers"
def builder = new StreamingMarkupBuilder()
builder.encoding = "UTF-8"
// Create a new container using the Markup Builder
def containerDoc = builder.bind {
mkp.xmlDeclaration()
mkp.declareNamespace(con: 'http://genologics.com/ri/container')
mkp.declareNamespace(udf: 'http://genologics.com/ri/userdefined')
'con:container'{
'name'(containerName)
'type'(uri:"http://${hostname}/api/v2/containertypes/1", name:"96 well plate")
}
}
Step 2: Post the New Container
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.
// Post the new container to the API
def containerNode = GLSRestApiUtils.xmlStringToNode(containerDoc.toString())
containerNode = GLSRestApiUtils.httpPOST(containerNode, containersListURI, username, password)
println GLSRestApiUtils.nodeToXmlString(containerNode)
Expected Output and Results
The XML for the new container is as follows.
<con:container xmlns:con="http://genologics.com/ri/container">
<name>containerPOSTScript</name>
<type uri="http://yourIPaddress/api/v2/containertypes/1" name="96 well plate"/>
</con:container>
The XML for the list of containers, with the newly added container shown at the end of the list, is as follows.
<con:containers>
<container uri="http://yourIPaddress/api/v2/containers/27-1858" limsid="27-1858">
<name>27-1858</name>
</container>
<container uri="http://yourIPaddress/api/v2/containers/27-2182" limsid="27-2182">
<name>27-2182-1</name>
</container>
<container uri="http://yourIPaddress/api/v2/containers/27-2202" limsid="27-2202">
<name>testingContainerPOST</name>
</container>
</con:containers>
For Clarity LIMS v4.2 and earlier, in the Operations Interface, the updated Containers view displays the new container.
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.
