Update UDF/Custom Field Information for a Process/Step

Steps can have user-defined fields (UDFs)/custom fields that can be used to describe properties of the steps.

For example, while a sample UDF/custom field might describe the gender or species of the sample, a process UDF/custom field might describe the room temperature recorded during the step or the reagent lot identifier. Sometimes, some of the information about a step is not be known until it has completed on the instrument, but after it was run in Clarity LIMS.

In this example, we will record the Actual Equipment Start Time as a process UDF/custom field after the step has been run in Clarity LIMS. The ISO 8601 convention is used for recording the date and time. For more information, see Filter Processes by Date and Type.

NOTE: In the API, information about a step is stored in the process resource.

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.

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

Prerequisites

Before you follow the example, make sure you have the following items:

• Samples added to the system.

• A custom field named Actual Equipment Start Time that has been configured on a master step (master step field).

• On the master step , you have configured the field to display on the Record Details milestone, in the Master Step Fields section.

• You have run samples through a step based on the master step on which the Actual Equipment Start Time field is configured.

Code Example

Detailed information for each step run in Clarity LIMS, including its name, LIMS ID, and custom fields can be viewed on the Record Details screen.

In the image below, an Actual Equipment Start Time master step field has been configured to display in the Step Details section of the Record Details screen. However, a value for this field has not yet been specified.

Step 1. Request the Process Resource

Before you can change the value of a process UDF/custom field, you must first request the individual process resource via a GET HTTP call. The XML returned from a GET on the individual process resource contains the information about that process. The following GET method provides the complete XML structure for the process:

// Determine the specified process URI and retrieve it
processURI = "http://${hostname}/api/v2/processes/${processLIMSID}"
processNode = GLSRestApiUtils.httpGET(processURI, username, password)
 
// Retrieve the process's 'Actual Equipment Start Time' UDF
startTimeUDF = processNode.'udf:field'.find { it.@name == 'Actual Equipment Start Time' }
newStartTime = parseInstrumentStartTime() 

The variable processNode now holds the complete XML structure retrieved from the resource at processURI.

The variable startTimeUDF references the XML element node contained in the structure that relates to the Actual Equipment Start Time UDF/custom field (if one exists).

The variable newStartTime is a string initialized with a value from the method parseInstrumentStartTimes. The details of this method are omitted from this example, but its function is to parse the date and time the instrument started from a log file.

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 code shows the XML structure for the process, as stored in the variable processNode. There are no child UDF/custom field nodes.

<prc:process uri="http://yourIPaddress/api/v2/processes/A22-BMJ-100927-24-2188" limsid="A22-BMJ-100927-24-2188">
    <type>HiSEQ PE</type>
    <date-run>2017-05-11</date-run>
    <technician uri="http://yourIPaddress/api/v2/researchers/305">
        <first-name>System</first-name>
        <last-name>Administrator</last-name>
    </technician>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/AFF853A49PA1?state=21004" post-process-uri="http://yourIPaddress/api/v2/artifacts/AFF853A49PA1?state=21009" limsid="AFF853A49PA1"/>
        <output uri="http://yourIPaddress/api/v2/artifacts/AFF853A49AP3?state=21010" output-type="Analyte" limsid="AFF853A49AP3"/>
    </input-output-map>
</prc:process> 

Step 2. Update the Process Resource

After modifying the process stored in the variable processNode, you can use a PUT method to update the process resource.

You can check if the UDF/custom field exists by verifying the value of the startTimeUDF variable. If the value is not null, then the field is defined and you can set a new value in the XML. If the field does not exist, you will must append a new node to the process XML resource using the UDF/custom field name and new value.

Before you can append a node to the XML, you must first specify the namespace for the new node. You can use the Groovy built-in QName class to do this. A QName object defines the qualified name of an XML element and specifies its namespace. The node you are specifying is a UDF element, so the namespace is http://genologics.com/ri/userdefined. The local part is field and the prefix is udf for the QName, which specifies the element as a UDF/custom field.

To append a new node to the process using the appendNode method of the variable processNode (which appends a node with the specified QName, attributes, and value). Specify the following attributes for the UDF/custom field element:

• the type

• the name

Both of these elements must match a UDF/custom field that has been specified in the Configuration window for the process type.

// If the process's UDF was set, replace it, otherwise create a new node and attach it to the process
if (startTimeUDF) {
    startTimeUDF.setValue(newStartTime)
} else {
    startTimeQName = new QName('http://genologics.com/ri/userdefined', 'field', 'udf')
    processNode.appendNode(startTimeQName, [type:'Numeric',name:'Actual Equipment Start Time'], newStartTime)
}

• The variable processNode now holds the complete XML structure for the process with the updated, or added, UDF named Actual Equipment Start Time.

You can save the changes you have made to the process using a PUT method on the process resource:

// Update the process in the API
returnNode = GLSRestApiUtils.httpPUT(processNode, processNode.@uri, username, password)
println GLSRestApiUtils.nodeToXmlString(returnNode)

The PUT updates the sample resource at the specified URI using the complete XML representation, including the new value for Actual Instrument Start Time.

If the PUT was successful, it returns the XML resource, as shown below. The updated information is also available at the http://yourIPaddress/api/v2/processes/A22-BMJ-100927-24-2188\ URI.

<prc:process uri="http://yourIPaddress/api/v2/processes/A22-BMJ-100927-24-2188" limsid="A22-BMJ-100927-24-2188">
    <type>HiSEQ PE</type>
    <date-run>2017-05-11</date-run>
    <technician uri="http://yourIPaddress/api/v2/researchers/305">
        <first-name>System</first-name>
        <last-name>Administrator</last-name>
    </technician>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/AFF853A49PA1?state=21004" post-process-uri="http://yourIPaddress/api/v2/artifacts/AFF853A49PA1?state=21009" limsid="AFF853A49PA1"/>
        <output uri="http://yourIPaddress/api/v2/artifacts/AFF853A49AP3?state=21010" output-type="Analyte" limsid="AFF853A49AP3"/>
    </input-output-map>
    <udf:field type="String" name="Actual Equipment Start Time">2017-05-13T3:14:15-0700</udf:field>
</prc:process>

• If the PUT was unsuccessful, an XML resource is returned with contents that detail why the call was unsuccessful. In the following example error, an incorrect UDF/custom field name was specified. A UDF/custom field named Equipment Start Time was created in the process resource, but no UDF/custom field with that name was configured for the process type/master step.\

  <exc:exception xmlns:exc="http://genologics.com/ri/exception">
    <message>Field Equipment Start Time does not exist</message>
  </exc:exception>

Expected Output and Results

The Step Details section of the updated Record Details screen now shows the Actual Equipment Start Time value.

The ability to modify process properties allows you to update automatically and store lab activity information as it becomes available. Information from equipment log files or other data sources can be collected in this way.

Updating per-run or per-process/step information is powerful because the information can be used to optimize lab work (eg, by tracking trends over time). The data can be compared by instrument, length of run, lab conditions, and even against quality of molecular results.

Attachments

UpdateProcessUDFInfo.groovy:

2KB

UpdateProcessUDFInfo.groovy