Rename 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 returns the full XML structure for the sample:
// Retrieve the sample sampleURI = "http://${hostname}/api/v2/samples/${sampleLIMSID}" sample = GLSRestApiUtils.httpGET(sampleURI, username, password)
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.
<smp:sample uri="http://yourIPaddress/api/v2/samples/HAM754A1" limsid="HAM754A1"><name>Colon-1</name><date-received>2010-03-25</date-received><project uri="http://yourIPaddress/api/v2/projects/HAM754" limsid="HAM754"/><artifact uri="http://yourIPaddress/api/v2/artifacts/HAM754A1PA1?state=11822" limsid="HAM754A1PA1"/><udf:field type="String" name="Organism">Homo sapiens</udf:field><udf:field type="String" name="Gender">Unknown</udf:field><udf:field type="Numeric" name="Concentration (ng/uL)">200.0</udf:field><udf:field type="Numeric" name="Total Volume (uL)">50</udf:field><udf:field type="String" name="Investigator Sample Name">F3_5016</udf:field><udf:field type="String" name="Sample Group Phase">Pick Plate</udf:field><udf:field type="String" name="Date of Sample Group Phase">2010-05-19</udf:field><udf:field type="String" name="Sample QC">FAILED</udf:field><udf:field type="String" name="Sample QC Date">2010-04-12</udf:field><udf:field type="String" name="Sample Picked">Yes</udf:field><udf:field type="String" name="Sample Latest Pick Date">2010-05-19</udf:field><udf:field type="Numeric" name="Sample Picked Iteration">3</udf:field><udf:field type="String" name="Sample Library Requeue Status"/><udf:field type="String" name="Sample Library Requeue Date">2010-05-19</udf:field><udf:field type="Numeric" name="Paired End Read Sequencing Lane Iteration">2</udf:field><udf:field type="String" name="Paired End Read Sequencing Last Date">2010-01-15</udf:field><udf:field type="String" name="Investigator Last Name">Hershberger</udf:field><udf:field type="String" name="Cohort">Not Applicable</udf:field></smp:sample>
Step 2. Rename the Sample
Renaming the sample consists of the following:
| • | Changing the name in the XML |
| • | Using the PUT method 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.
// Rename the sample nameNode = sample.name[0] nameNode.setValue(newName) returnNode = GLSRestApiUtils.httpPUT(sample, sample.@uri, username, password)
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>.
<smp:sample uri="http://yourIPaddress/api/v2/samples/HAM754A1" limsid="HAM754A1"><name>Colon-1 Updated</name><date-received>2010-03-25</date-received><project uri="http://yourIPaddress/api/v2/projects/HAM754" limsid="HAM754"/><artifact uri="http://yourIPaddress/api/v2/artifacts/HAM754A1PA1?state=11822" limsid="HAM754A1PA1"/><udf:field type="String" name="Organism">Homo sapiens</udf:field><udf:field type="String" name="Gender">Unknown</udf:field><udf:field type="Numeric" name="Concentration (ng/uL)">200.0</udf:field><udf:field type="Numeric" name="Total Volume (uL)">50</udf:field><udf:field type="String" name="Investigator Sample Name">F3_5016</udf:field><udf:field type="String" name="Sample Group Phase">Pick Plate</udf:field><udf:field type="String" name="Date of Sample Group Phase">2010-05-19</udf:field><udf:field type="String" name="Sample QC">FAILED</udf:field><udf:field type="String" name="Sample QC Date">2010-04-12</udf:field><udf:field type="String" name="Sample Picked">Yes</udf:field><udf:field type="String" name="Sample Latest Pick Date">2010-05-19</udf:field><udf:field type="Numeric" name="Sample Picked Iteration">3</udf:field><udf:field type="String" name="Sample Library Requeue Status"/><udf:field type="String" name="Sample Library Requeue Date">2010-05-19</udf:field><udf:field type="Numeric" name="Paired End Read Sequencing Lane Iteration">2</udf:field><udf:field type="String" name="Paired End Read Sequencing Last Date">2010-01-15</udf:field><udf:field type="String" name="Investigator Last Name">Hershberger</udf:field><udf:field type="String" name="Cohort">Not Applicable</udf:field></smp:sample>
