1 of 6

Work with Submitted Samples

When working with submitted samples, you can do the following:

Adding Samples to the System

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.

Prerequisites

Follow the instructions provided in the following examples:

Code example

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.

Step 1. Create a New Project

As shown in , 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:

Step 2. Create a New Container

As shown in the 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:

Step 3. Create a New Sample

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.

Expected Output and Results

In Clarity LIMS Projects and Samples dashboard, open the project to find the new sample in its container.

Attachments

PostSample.groovy:

Renaming Samples

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.

Code example

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.

Step 1. Retrieve the Sample

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.

Step 2. Rename the Sample

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.

Expected Output and Results

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>

Attachments

RenamingSample.groovy:

Assigning Samples to Workflows

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.

Code example

Updating Sample Information

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.

Code example

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.

Step 1. Retrieve the Resource

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.

Step 2. Update the Sample UDF

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.

Expected Output and Results

The following XML from our example shows the expected output:

In Clarity LIMS, the updated sample details now show the new Priority value.

Attachments

UpdateSampleUDF.groovy:

Show the Relationship Between Samples and Analyte Artifacts (Derived Samples)

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.

Code example

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:

Expected Output and Results

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).

Attachments

SampleAndAnalyteRelations.groovy:

Renaming Samples

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.

Code example

Clarity LIMS displays detailed information for each sample, including its name, container, well, and date submitted.

Step 1. Retrieve the Sample

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.

Step 2. Rename the Sample

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.

Expected Output and Results

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>

Attachments

RenamingSample.groovy:

Updating Sample Information

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.

Code example

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.

Step 1. Retrieve the Resource

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 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.

Step 2. Update the Sample UDF

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 .

If those custom fields had not been included in the XML, they would have been updated to have no value.

Expected Output and Results

The following XML from our example shows the expected output:

In Clarity LIMS, the updated sample details now show the new Priority value.

Attachments

UpdateSampleUDF.groovy:

Work with Submitted Samples

Adding Samples to the System

hashtagPrerequisites

hashtagCode example

hashtagStep 1. Create a New Project

hashtagStep 2. Create a New Container

hashtagStep 3. Create a New Sample

hashtagExpected Output and Results

hashtagAttachments

Renaming Samples

hashtagCode example

hashtagStep 1. Retrieve the Sample

hashtagStep 2. Rename the Sample

hashtagExpected Output and Results

hashtagAttachments

Assigning Samples to Workflows

hashtagCode example

Updating Sample Information

hashtagCode example

hashtagStep 1. Retrieve the Resource

hashtagStep 2. Update the Sample UDF

hashtagExpected Output and Results

hashtagAttachments

Show the Relationship Between Samples and Analyte Artifacts (Derived Samples)

hashtagCode example

hashtagExpected Output and Results

hashtagAttachments

Adding Samples to the System

hashtagPrerequisites

hashtagCode example

hashtagStep 1. Create a New Project

hashtagStep 2. Create a New Container

hashtagStep 3. Create a New Sample

hashtagExpected Output and Results

hashtagAttachments

Renaming Samples

hashtagCode example

hashtagStep 1. Retrieve the Sample

hashtagStep 2. Rename the Sample

hashtagExpected Output and Results

hashtagAttachments

Assigning Samples to Workflows

hashtagCode example

Work with Submitted Samples

hashtagStep 2. Retrieve the Samples' Base Artifact URIs

hashtagStep 3. Gather Workflow URIs

hashtagStep 4. Construct and POST the XML

hashtagExpected Output and Results

hashtagAttachments

Show the Relationship Between Samples and Analyte Artifacts (Derived Samples)

hashtagCode example

hashtagExpected Output and Results

hashtagAttachments

Updating Sample Information

hashtagCode example

hashtagStep 1. Retrieve the Resource

hashtagStep 2. Update the Sample UDF

hashtagExpected Output and Results

hashtagAttachments

Prerequisites

Code example

Step 1. Create a New Project

Step 2. Create a New Container

Step 3. Create a New Sample

Expected Output and Results

Attachments

Code example

Step 1. Retrieve the Sample

Step 2. Rename the Sample

Expected Output and Results

Attachments

Code example

Code example

Step 1. Retrieve the Resource

Step 2. Update the Sample UDF

Expected Output and Results

Attachments

Code example

Expected Output and Results

Attachments

Prerequisites

Code example

Step 1. Create a New Project

Step 2. Create a New Container

Step 3. Create a New Sample

Expected Output and Results

Attachments

Code example

Step 1. Retrieve the Sample

Step 2. Rename the Sample

Expected Output and Results

Attachments

Code example

Step 2. Retrieve the Samples' Base Artifact URIs

Step 3. Gather Workflow URIs

Step 4. Construct and POST the XML

Expected Output and Results

Attachments

Code example

Expected Output and Results

Attachments

Code example

Step 1. Retrieve the Resource

Step 2. Update the Sample UDF

Expected Output and Results

Attachments