In the Clarity LIMS API (v2 r21 or later), the initial submitted sample is referred to as a sample (or root artifact). Any derived sample output from a process/step is referred to as an analyte, or artifact of type analyte. This example demonstrates the relationship between samples and analyte artifacts. You must have a sample in the system and one or more processes/steps done that output analyte (derived sample) artifacts.
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.
There are two types of custom fields:
Master step fields—Configured on master steps. Master step fields only apply to the following:
The master step on which the fields are configured.
The steps derived from those master steps.
Global fields—Configured on entities (eg, submitted sample, derived sample, measurement, etc.). Global fields apply to the entire Clarity LIMS system.
The code example does the following when it is used:
Retrieves the URI of an arbitrary analyte artifact.
Retrieves the corresponding sample of the artifact
Retrieves the original root analyte artifact from the sample, as shown in the following example:
You can generate XML for an arbitrary analyte artifact. The analyte artifact is downstream and has a parent-process element (as shown in line 5). The sample artifact is an original artifact. Downstream artifacts relate to at least one sample, but can also relate to more than one sample, like with pooling or shared result files. The following is an example of XML generated for an analyte artifact:
You can also generate XML for a submitted sample. Every submitted sample has exactly one corresponding original root artifact. A sample representation does not link to downstream artifacts, but you can find them using query parameters in the artifacts list resource. The following is an example of XML generated for a submitted sample:
Lastly, you can generate XML for an original sample artifact called a root artifact. The following is an example of XML generated from an original sample artifact. In this case, both the downstream artifact and the original root artifact point to the same original sample (eg, LIMS ID EXA2241A1).
SampleAndAnalyteRelations.groovy:
When working with submitted samples, you can do the following:
You can use the API (v2 r21 and later) to automate the process of assigning samples to a workflow. This example shows how to create the required XML. The example also provides a brief introduction on how to use the route/artifacts endpoint, which is the endpoint used to perform the sample assignment.
The example takes two samples that exist in Clarity LIMS and assigns each of them to a different workflow.
Define the assignment endpoint URI using the following example. The assignment endpoint allows you to assign the artifacts to the desired workflow.
You can also retrieve the base artifact URIs of the samples using the following example:
Use the following example to gather the workflow URIs:
Next, you can construct the XML that is posted to perform the workflow assignment. You can do this construction by using the StreamingMarkupBuilder and the following example.
Assign the analyte (derived sample) artifact of the sample to a workflow as follows.
Create an assign tag with the URI of the destination workflow as an attribute.
Create an artifact tag inside the assign tag with the URI of the analyte as an attribute.
After the assignment XML is defined, you can POST it to the API. This POST performs the sample assignment.
After the script has run, the samples display in the first step of the first protocol in the specified workflows.
AssigningArtifactsToWorkflows.groovy:
You can rename samples in the system using API (v2 r21 and later). The amount of information provided in the sample name is sometimes minimal. After the sample is in the system, you can add additional information to the name. For example, you can help lab scientists understand what they must do with a sample, or where it is in processing.
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.
There are two types of custom fields:
Master step fields—Configured on master steps. Master step fields only apply to the following:
The master step on which the fields are configured.
The steps derived from those master steps.
Global fields—Configured on entities (eg, submitted sample, derived sample, measurement, etc.). Global fields apply to the entire Clarity LIMS system.
Clarity LIMS displays detailed information for each sample, including its name, container, well, and date submitted.
In this example, the sample name is Colon-1. To help keep context when samples are processed by default, the submitted sample name is used for the downstream samples (or derived samples) generated by a step in Clarity LIMS.
Before you rename a sample, you must first request the resource via a GET. As REST resources are self-contained entities, always request the full XML representation before editing the portion that you wish to change.
The XML representations of individual REST resources are self-contained entities. Always request the full XML representation before editing any portion of the XML. If you do not use the complete XML when you update the resource, you can inadvertently change data.
The following GET method below returns the full XML structure for the sample:
The variable sample now holds the complete XML structure returned from the sampleURI.
The following example shows the XML for the sample, with the name element on the second line. In this particular case, the Clarity LIMS configuration has expanded the sample with 18 custom fields that provide sample information.
Renaming the sample consists of the following:
The name change in the XML
The PUT call to update the sample resource
The name change is executed with the nameNode XML element node, which references the XML element containing the name of the sample.
The PUT method updates the individual sample resource using the complete XML representation, which includes the new name. Such complete updates provide a simple interaction between client and server.
The updated sample view displays the new name. You can also view the results in a web browser via the URI at
http://<YourIPaddress>/api/v2/samples/<SampleLIMSID>
RenamingSample.groovy:
You can add samples to the system using API (v2 r21 and later). This example assumes that you have sample information in a file that is difficult to convert into a format suitable for importing into Clarity LIMS. The aim is to add the samples, and all associated data, into Clarity LIMS without having to translate the file manually. You can use the REST API to add the samples.
Follow the instructions provided in the following examples:
To add a sample in Clarity LIMS, you must assign it to a project and place it into a container. This example assumes that you are adding a new project and container for the samples being created.
As shown in Add a New Project to the System with UDF/Custom Field Value, you define a project by using StreamingMarkupBuilder. StreamingMarkupBuilder is a built-in Groovy data structure designed to build XML structures. This structure creates the XML that is used in a POST to the projects resource:
If the POST to projects is successful, the following XML is returned:
As shown in the Add an Empty Container to the System example, you can add a container by using StreamingMarkupBuilder to create the XML for a new container. This creates the XML that is used in a POST to the containers resource:
If the POST to containers is successful, the following XML is returned:
Now that you have the project and container, you can use StreamingMarkupBuilder to create the sample. The XML created to add the sample uses the URIs for the project and container that were created in the previous steps.
This POST to the samples resource creates a sample in Clarity LIMS, adding it to the project and container specified in the POST.
In Clarity LIMS Projects and Samples dashboard, open the project to find the new sample in its container.
PostSample.groovy:
The most important information about a sample is often recorded in custom fields in API (v2 r21 and later). These fields often contain information that is critical to the processing of the sample, such as species or sample type.
When samples come into the lab, you can provide lab scientists with information about priority or quality. You can provide this information by changing the value of specific sample custom fields.
This example shows how to change the value of a sample custom field called Priority after you have entered a submitted sample into the system.
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.
There are two types of custom fields:
Master step fields—Configured on master steps. Master step fields only apply to the following:
The master step on which the fields are configured.
The steps derived from those master steps.
Global fields—Configured on entities (eg, submitted sample, derived sample, measurement, etc.). Global fields apply to the entire Clarity LIMS system.
In Clarity LIMS, you can display detailed information for a sample, including the following:
Name
Clarity LIMS ID
Custom fields
In the following figure, you can see that the sample name is DNA Sample-1 and the field named Priority has the value High.
In this example, change the value of the Priority custom field to Critical.
Before you can change the value of the field, you must first request the resource via a GET method.
To change a sample submitted in Clarity LIMS, use the individual sample resource. The XML returned from a GET on the individual sample resource contains the information about the sample.
The following GET method returns the full XML structure for the sample:
The sample variable now holds the complete XML structure returned from the sample GET request.
The XML representations of individual REST resources are self-contained entities. Always request the complete XML representation before editing any portion of the XML. If you do not use the complete XML when you update the resource, you can inadvertently change data.
The following shows XML returned for the sample, with the Priority field shown in red in the second to last line. In this example:
The Clarity LIMS configuration has added three fields to the expanded sample information.
The UDFs are named Sample Type, Phenotypic Information, and Priority.
When updating the Priority field, you need to do the following:
Change the value in the XML.
Use a PUT method to update the sample resource.
You can change the value for Priority to Critical by using the utility files setUdfValue method.
The subsequent PUT method updates the sample resource at the specified URI using the complete XML representation, which includes the new custom field value for XML.
A successful PUT returns the new XML in the returnNode. The results can also be reviewed in a web browser at <YourIPaddress>/api/v2/samples/<SampleLIMSID> URI.
An unsuccessful PUT returns the HTTP response code and message in the returnNode XML .
NOTE: The values for the other two fields, Sample Type and Phenotypic Information, did not change. These values did not change because they were included in the XML used in the PUT (eg, they were held in the sample variable as part of the complete XML structure).
If those custom fields had not been included in the XML, they would have been updated to have no value.
The following XML from our example shows the expected output:
In Clarity LIMS, the updated sample details now show the new Priority value.
UpdateSampleUDF.groovy:
