Update UDF/Custom Field Values for a Derived Sample Output

As processing occurs in the lab, associated processes and steps are run in Clarity LIMS. Often, key data must be recorded for the derived samples (referred to as analytes in the API) generated by these steps.

The following example explains how to change the value of an analyte UDF/global custom field.

If you would like to update a batch of output derived samples (analytes), you can increase the script execution speed by using batch operations. For more information, see Working with Batch Resources.

Prerequisites

In Clarity LIMS v5 or later, the key data fields are configured as global custom fields on derived samples. If you are using Clarity LIMS v5 or later, make sure you have the following items:

• A defined global custom field named Library Size on the Derived Sample object.

• A configured Library Prep step to apply Library Size to generated derived samples.

• A Library Prep process that has been run and has generated derived samples.

Terminology

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 v5 and later, the Record Details screen displays the information about the derived samples generated by a step. You can view the global fields associated with the derived samples in the Sample Table.

The following screenshot shows the Library Size values for the derived samples.

Derived sample information is stored in the API in the analyte resource. Step information is stored in the process resource. Each global field value is stored as an udf.

An analyte resource contains specific derived sample details that are recorded in lab steps. Those details are typically stored in global custom fields (configured in Clarity LIMS on the Derived Sample object) and then associated with the step.

When you update the information for a derived sample by updating the analyte API resource, only the global fields that are associated with the step can be updated.

Step 1. Request the Process Resource

To update the derived samples generated by a step, you must first request the process resource through a GET method.

The following GET method provides the full XML structure for the step:

// Retrieve Process processURI = "http://${hostname}/api/v2/processes/${processLIMSID}" process = GLSRestApiUtils.httpGET(processURI, username, password)

The process variable now holds the complete XML structure returned from the GET request.

The XML returned from a GET on the process resource contains the URIs of the process output artifacts (the derived samples generated by the step). You can use these URIs to query for each individual artifact resource.

The process resource contains many input-output-map elements, where each element represents an artifact. The following snippet of the XML shows the process:

Because processes with multiple inputs and outputs tend to be large, many of the input-output-map nodes have been omitted from this example.

<prc:process uri="http://yourIPaddress/api/v2/processes/A14-BMJ-100830-24-1472" limsid="A14-BMJ-100830-24-1472"> <type>API Cookbook Example 1.4</type> <date-run>2010-08-30</date-run> <technician uri="http://yourIPaddress/api/v2/researchers/305"> <first-name>Brandon</first-name> <last-name>Johnson</last-name> </technician> <input-output-map> <input uri="http://yourIPaddress/api/v2/artifacts/HAM754A4PA1?state=15633" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A4PA1?state=15641" limsid="HAM754A4PA1"/> <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A4AP8?state=15644" output-type="Analyte" limsid="HAM754A4AP8"/> </input-output-map> <input-output-map> <input uri="http://yourIPaddress/api/v2/artifacts/HAM754A1PA1?state=15622" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A1PA1?state=15646" limsid="HAM754A1PA1"/> <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A1AP8?state=15642" output-type="Analyte" limsid="HAM754A1AP8"/> </input-output-map> <input-output-map> <input uri="http://yourIPaddress/api/v2/artifacts/HAM754A3PA1?state=15626" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A3PA1?state=15637" limsid="HAM754A3PA1"/> <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A3AP8?state=15639" output-type="Analyte" limsid="HAM754A3AP8"/> </input-output-map></prc:process>

Step 2. Request the Artifact Resource and Update the Analyte UDF/Custom Field

After you have retrieved each individual artifact resource, you can use this information to update the UDFs/custom fields for each output analyte after you request its resource.

Request the analyte output resource and update the UDF/custom field as follows.

1. If the output-type is analyte, then run through each input-output-map and request the output artifact resource.

2. Use a GET to return the XML for each artifact and store it in a variable.

3. When you have the analytes stored, change the analyte UDF/custom field through the following methods:

   • The UDF/custom field change in the XML.

   • The http PUT call to update the artifact resource.

The UDF/custom field change can be achieved with the Library Size UDF/custom field XML element defined in the following code. In this example, the Library Size value is updated to 25.

The PUT method updates the artifact resource at the specified URI using the complete XML representation, including the UDF/custom field. The setUdfValue method of the util library is used to perform this in a safe manner.

// For each input-output-map, if its output is an Analyte, set its Library Size UDF process.'input-output-map'.each { if (it.output.@'output-type'[0] == "Analyte") { analyteURI = it.output.@uri[0] analyte = GLSRestApiUtils.httpGET(analyteURI, username, password) analyte = GLSRestApiUtils.setUdfValue(analyte, 'Library Size', '25') GLSRestApiUtils.httpPUT(analyte, analyte.@uri, username, password) } }

The output-type attribute is the user-defined name for each of the output types generated by a process/step. This is not equivalent to the type element of an artifact whose value is one of several hard-coded artifact types.

If you must filter inputs or outputs from the input-output-map based on the artifact type, you will must GET each artifact in question to discover its type.

It is important that you remove the state from each of the analyteURIs before you GET them, to make sure that you are working with the most recent state.

Otherwise, when you PUT the analyteURI back with your UDF/custom field changes, you can inadvertently revert information, such as QC, volume, and concentration, to previous values.

Expected Output and Results

The results can be reviewed in a web browser through the following URI:

http://yourIPaddress/api/v2/artifacts/HAM754A4AP8\

<art:artifact uri="http://yourIPaddress/api/v2/artifacts/HAM754A4AP8?state=15644" limsid="HAM754A4AP8"> <name>Colon-4</name> <type>Analyte</type> <output-type>Analyte</output-type> <parent-process uri="http://yourIPaddress/api/v2/processes/A14-BMJ-100830-24-1472" limsid="A14-BMJ-100830-24-1472"/> <volume unit="uL">0.0</volume> <concentration unit="ug/mL">10.0</concentration> <qc-flag>UNKNOWN</qc-flag> <location> <container uri="http://yourIPaddress/api/v2/containers/27-2320" limsid="27-2320"/> <value>1:1</value> </location> <working-flag>true</working-flag> <sample uri="http://yourIPaddress/api/v2/samples/HAM754A4" limsid="HAM754A4"/> <udf:field type="Numeric" name="Library Size">25</udf:field></art:artifact>

In Clarity LIMS v5 or later, in the Record Details screen, the Sample table now shows the updated Library Size.

Attachments

UpdateProcessUDFInfo.groovy:

2KB

UpdateProcessUDFInfo.groovy

UpdateUDFAnalyteOutput.groovy:

1KB

UpdateUDFAnalyteOutput.groovy