File attachments

When reading a recipe, look for file attachments. Almost all examples have an attached Groovy script to download.

Working with the attached scripts

To use the scripts with a non-production server, edit the script to include your server network address and credentials.

For illustration purposes, most scripts use populated information. You must add your own sample, process (eg, a master step in Clarity LIMS v5 and later), and other data. The non-production server has a directory set up for this purpose at

/opt/gls/clarity/customextensions/ 

Using Full Production Scripts

When using full production scripts, the following considerations must be taken:

• Cookbook scripts are written to explain concepts. They are not deeply engineered code written in a defensive programming style. Always think through the expected and unexpected input of your scripts when incorporating concepts or code from Cookbook recipe examples.

• Full production servers can require different configurations for scripting languages other than Groovy, and for the EPP/automation worker node. For example, your script directory can be accessible by the user account running the EPP/automation worker node for User Interface (UI) triggers.

Discuss the software deployment plans with your system administrator to coordinate between non-production and production servers. For more information on using production scripts, see REST General Concepts and Automation.

Version Compatibility

Each recipe was written with a specific API version. For information on how to check the version of the API on your system, see Requesting API Version Information.

Apache Groovy is required for most Cookbook examples. It is open source and is available under an Apache license from groovy-lang.org/download.html. It is installed on non-production servers, but you can also install it to your desktop. The Cookbook examples were developed with Groovy v1.7.

Python is required for some Cookbook examples. It is available from www.python.org/download. The Cookbook examples were developed with Python v2.7.

Path to Groovy

The automation worker node executing the command uses the first instance of Groovy it finds in the executable search path for the limited shell. This is the $PATH variable.

If you have multiple versions of Groovy (or multiple users using different versions) and experience problems with your command-line calls, declare the full path to Groovy/Java in your command.

To see your executable search path, and other environment variables available to you, run the following command:

bash -c "env > {outputFileLuid0}.txt"

Compare this command to the full logon shell, which is

bash -l -c "env > {outputFileLuid0}.txt"

For more information on command-line actions, see Supported Command Line Interpreters.

References

For details on the programming interface methods and data elements available, refer to the following documentation:

• https://github.com/illumina-swi/clarity-int-docs/blob/main/docs/api-docs/resources-and-references.md

• Automation Tokens

Browser Plug-Ins

Browsing for, and adjusting resources, in Firefox, Chrome, or other browsers is great for getting started or for troubleshooting.

The following plug-ins are available with Firefox:

• Text Link—Makes any URI in the XML a hyperlink.

• Linkificator—Converts text links into selectable links.

• RESTClient—Provides a simple interface to call HTTP methods on REST resources. It is useful for troubleshooting, checking error codes, and for getting comfortable with GET, PUT, and POST requests.

The following plug-ins are available with Chrome:

• Advanced REST Client—Provides similar functionality to Poster by Firefox.

• XML Tree—Displays XML data in a user-friendly way.

Before downloading your first script, do the following actions:

• Familiarize yourself with the API Cookbook prerequisites and key concepts found in Development Prerequisites and REST General Concepts.

• Use a non-production server for script development.

• Familiarize yourself with the coding language.

• Use the GLSRestApiUtils file to assist with recipe development.

• Review Tips and Troubleshooting.

Script Development with a Non-Production Server

The example script recipes really come to life when you change them and see what happens. Running the scripts often requires new custom fields and master steps to be added to the system. You need unrestricted access to development and test servers (licensed as non-production servers) with Groovy (a coding language). You also need an AI node/automation worker installed so that you can experiment freely.

For more information and recommendations for deploying and copying scripts in development, test, and product environments, refer to Useful Tools.

Script Types

Groovy

The Cookbook Recipe Examples are written in Groovy. Many of our examples use the following Groovy concepts:

• Closures: Groovy closures are essentially blocks of code that can be stored for later use.

• The each method: The each method takes a closure as an argument. It then iterates through each element in a collection, performing the closure on the element, which is (by default) stored in the 'it' variable. For example:

  Copy

  outputNodes.each {
      GLSRestApiUtils.setUdfValue(it, 'Library Size', '25')
  }

Python

The Cookbook also provides a few examples written in Python, which uses the minidom module. The following script shows how the minidom module is used:

dom = parseString(pXML)
elementList = dom.getElementsByTagName("udf:field")
for element in elementList:
    name = element.getAttribute("name")
    if name == udfName:
        udf = api.getInnerXml(element.toxml(), "udf:field")

This same functionality can be obtained using any programming language capable of interacting with the Web API. For more information on the minidom module, refer to Python Minidom.

Use GLSRestApiUtils

In addition to the Groovy file example attached to each Cookbook recipe page, most recipes require the glsapiutil.py file, which is available on our GitHub repository. The mature glsapiutil.py library is strictly for Python 2. A newer version, glsapiutil3.py, works with Python 3.

For more information on these files, see Obtain and Use the REST API Utility Classes.

The Clarity LIMS Cookbook uses example scripts to help you learn how to work with REST and EPP automation scripts. Cookbook recipes are small, specific how-to articles designed to help you understand REST and automation script concepts. Each recipe includes the following:

• Explanations about a concept and how a particular programming interface is used in a script.

• A snippet of script code to demonstrate the concept.

The API documentation includes the terms External Program Integration Plug-in (EPP) and EPP node.

As of Clarity LIMS v5.0, these terms are deprecated.

• EPP has been replaced with automation.

• EPP node is referred to as the Automation Worker or Automation Worker node. These components are used to trigger and run scripts, typically after lab activities are recorded in the LIMS.

The best way to get started is to download the example script and try it out. After you have seen how the script works, you can dissect it and use the pieces to create your own script.

Automations (formerly referred to as EPP triggers or automation actions) allow lab scientists to invoke scripts as part of their workflow. These scripts must successfully complete for the lab scientist to proceed to the next step of the workflow.

EPP automation/support is compatible with API v2 r21 and later.

The API documentation includes the terms External Program Integration Plug-in (EPP) and EPP node.

As of Clarity LIMS v5.0, these terms are deprecated.

• EPP has been replaced with automation.

• EPP node is referred to as the Automation Worker or Automation Worker node. These components are used to trigger and run scripts, typically after lab activities are recorded in the LIMS.

Automations have various uses, including the following:

• Workflow enforcement—Makes sure that samples only enter valid protocol steps.

• Business logic enforcement—Validates that samples are approved by accounting before work is done on them. This automation can also make sure that selected samples are worked on together.

• Automatic file generation—Automates the creation of driver files, sample sheets, or other files specific to your protocol and instrumentation.

• Notification—Notifies external systems of lab progress. For example, you can notify Accounting of completed projects so that they can then bill for services rendered.

Configuration

You can enable automations on master steps in two configuration areas of Clarity LIMS:

• On the Automations tab, when adding/configuring an automation. See the Adding and Configuring Automations article in the Automations section of the Clarity LIMS documentation.

• On the Lab Work tab, on the master step configuration form. See the _Adding & Configuring Master Steps and Step_s article in the Steps and Master Steps section of the Clarity LIMS documentation.

After it is enabled on a master step, the automation becomes available for use on all steps derived from that master step.

You can configure the automation trigger on the master step, or on the steps derived from that master step.

Script messages

Progress message

While executing a script, if more than one script would be triggered for a single user action, they are reported in sequence. This reporting continues until all scripts complete, or one of them fails.

An example scenario would be a step that is configured to execute the following:

• One script upon exit of the Placement screen.

• A second script upon entry of the Record Details screen.

In this scenario, when the lab scientist advances their protocol step from the Placement screen to the Record Details screen, the scripts are executed in sequence.

The parameter string/automation name configured on the master step is displayed in a progress message. You can use this feature by giving your parameter strings/automations meaningful names that provide you with context about what the script is doing. The following is an example of a progress message.


You cannot proceed until the script completes successfully.

Non-responsive scripts

You can request to cancel a script that is not responsive. While canceling abandons the monitoring of script execution, it does not stop the execution of the script.

After canceling a script, follow up with the Clarity LIMS administrator to determine if the AI node/automation worker must be restarted.

Non-Blocking Success and Warning Message

The scientific programmers in your facility can provide you with a message upon successful execution of a script. There are two possible non-fatal messages: OK and WARNING. These messages can be set using the step program status REST API endpoint.

Message boxes display the script name, followed by a message that is set by the script using the step program status REST API endpoint. Line breaks are permitted in the custom message. The following is an example of a success message:

After you select OK, you are permitted to proceed in the workflow.

Blocking Script Failure Message

When a script fails, a message box displays. There are two ways to produce fatal messages:

• By using the step program status REST API endpoint (informing FAILURE as the status)

• By generating output to the console and returning a non-zero exit code.

For example, when beginning a step, if the script does not allow you to work on the samples together in Ice Bucket, the samples will be returned to Ice Bucket after acknowledging the error message. In this case, the step is prevented from being tracked. The following is an example of a failure message:

If you attempt to advance a step from the Pooling screen, but an error is detected, the error state prevents you from continuing. The following is an example of this type of message:

After you select OK, you are prevented from proceeding in the workflow. Instead, you must return to the Pooling screen and address the problem before proceeding.

This page is maintained for posterity, but customers are encouraged to visit the GitHub repository for all subsequent updates to the library (including changelogs). Unless otherwise specified, changes are only made in the Python version of the library.

Changelog

Dec. 19, 2017:

• glsapiutil v3 ALPHA (bleeding-edge library) released on GitHub. GitHub has the most current library.

• Links to library removed from this page.

Dec. 15, 2016:

• reportScriptStatus() function had a bug that caused it to not work when a <message> node was unavailable. This has been fixed.

• deleteObject() functions now available for both v1 and v2 of the library.

• getBaseURI() should now return a trailing slash at the end of the URI string.

• getFiles() function added to batch retrieve files.

NOTE: The Python glsapiutil.py and glsapiutil3.py classes are now available on GitHub. GitHub has the most current libraries. glsapiutil3.py works with both Python v2 and v3.

Legacy Overview

The GLSRestApiUtils utility class provides a consistent way to perform common REST operations, such as REST HTTP methods or common XML string manipulation. It is a utility class written in Python and Groovy for the API Cookbook examples. This utility class is specific to the Cookbook examples. The class is not required for the API with Groovy or Python, as there are many other ways to manipulate HTTP and XML in these languages. However, it is required if you want to run the Cookbook examples as written. It is also not part of REST or EPP/automation.

Using Utility Calls in your Scripts

Almost all Cookbook example files use the HTTP methods from the GLSRestApiUtils class.

The HTTP method calls in Groovy resemble the following example:

returnNode = GLSRestApiUtils.httpGET(uri, username, password)
returnNode = GLSRestApiUtils.httpPUT(inputNode, uri, username, password)
returnNode = GLSRestApiUtils.httpPOST(inputNode, uri, username, password)

In this example, the returnNode and inputNode are Groovy nodes containing XML. The XML in the returnNode contains the XML available from the server after a successful method call. If the method call was unsuccessful, the XML contains error information. The following is an example of the XML manipulation functions in the utility:

println GLSRestApiUtils.nodeToXmlString(returnNode)

As you can see from these examples, the utility class is easy to include in your scripting. The code is contained in the GLSRestApiUtils files attached to this page.

Deploying Groovy and Python scripts

Deploying a Groovy Script that Uses the Utility Class

To deploy a Groovy script that uses the utility class, you must include the directory containing GLSRestApiUtils.groovy in the Groovy class path.

Groovy provides several ways to package and distribute source files, including the following methods:

• Call Groovy with the -classpath (or -cp) parameter.

• Add to the CLASSPATH environment variable.

• Create a ~/.groovy/lib directory for jar files for common libraries.

If you would like to experiment with the Cookbook examples, you can also copy the file into the same directory as the example script.

Use the Python Library

Library functions

The HTTP method calls for the Python version of the library resemble the following:

returnXML = api.GET( uri )
returnXML = api.PUT( xml, uri )
returnXML = api.POST( xml, uri )

Unlike with the Groovy library, the rest functions in the Python library require XML (text) as input (not DOM nodes). The return values of the GET, PUT, and POST functions are also XML text.

Deploy Scripts with the Python Library in Clarity LIMS (v4 and Later)

If a script must work with a running process or step, it is normal to use either the {processURI:v2} or the {stepURI:v2} tokens. The following example has the {stepURI:v2} token:

bash -l -c "/usr/bin/env python /opt/gls/clarity/customextensions/myScript.py 
-u {username} -p {password} -s {stepURI:v2} -f {compoundOutputFileLuid0}"

In Clarity LIMS v4 and above, these tokens sometimes resolve to https://localhost:9080/api/v2/... instead of the expected HOSTNAME. Setting up the API object with a hostname other than https://localhost:9080 can cause Access Denied errors. To avoid this issue, alter the API authentication code slightly as follows.

import platform

HOSTNAME = platform.node() # get the system hostname
VERSION = 'v2' # API version 2
BASE_URI = HOSTNAME + '/api/' + VERSION + '/'

USERNAME = 'username'
PASSWORD = 'password'
api = None

[...]

def setupGlobalsFromURI( uri ):

    global HOSTNAME
    global VERSION
    global BASE_URI

    tokens = uri.split( '/' )
    HOSTNAME = '/'.join( tokens[0:3] )
    VERSION = tokens[4]
    BASE_URI = '/'.join( tokens[0:5] ) + '/'

def main():
    global api
    api = glsapiutil.glsapiutil2() #initialise the API object, using version 2 of the API

    setupGlobalsFromURI( args.stepURI ) # assuming the step URI was passed by the EPP / automation trigger

    api.setHostname( HOSTNAME ) # set the hostname, currently taken from the system
    api.setVersion( VERSION ) # the version, currently set to 'v2'
    api.setup( USERNAME, PASSWORD ) # authenticate with the Clarity LIMS API user credentials 

TThe changes are highlighted in red. This code takes the resolved {stepURI:v2} token (assumed to be stored in the args object) and resets the HOSTNAME variable to the new value (eg, https://localhost:9080) before authenticating.

These changes are fully backward-compatible with Clarity LIMS v4 or earlier. The EPP/automation URI tokens resolve to the expected hostname, and the setupGlobalsFromURI() function still parses it correctly.

NOTE: On GitHub, in addition to the libraries, a basic_complete_recipe.py script that contains the skeleton code is needed to get started with the Python API. This script also includes the modifications required to work with Clarity LIMS v4 and later. The legacy Groovy library can still be obtained using the attachment.

Attachments

GLSRestApiUtils.groovy:

At the completion of a process (using API v2 r21 or later), EPP can invoke any external program that runs from a command line. In this example, a process with a reference to a declared EPP program is configured and executed entirely via the API.

EPP automation/support is compatible with API v2 r21 and later.

The API documentation includes the terms External Program Integration Plug-in (EPP) and EPP node.

As of Clarity LIMS v5.0, these terms are deprecated.

• EPP has been replaced with automation.

• EPP node is referred to as the Automation Worker or Automation Worker node. These components are used to trigger and run scripts, typically after lab activities are recorded in the LIMS.

Prerequisites

1. You have defined a process that has:

   • An input of type analyte.

   • A single output per input.

   • A single shared result file.

2. The process type is associated with an external program that has the following requirements:

   • At least one process-parameter defined - named TestProcessParam.

   • A parameter string of: bash -c "echo HelloWorld > {compoundOutputFileLuid0}.txt"

3. Samples have been added to the LIMS.

Code example

Step 1. Identify the Sample

To run a process on a sample, you must first identify the sample to be used as the input to the process.

For this example, run the process on the first highlighted sample.

After you have identified the sample, you can use its LIMS ID to as a parameter for the script. The artifact URI is then used as the input in constructing the XML to POST and executing a process.

Step 2. Identify the Container

The following code block outlines this action and obtains the URI of the container for the process execution POST.

NOTE: As shown in other examples, you can use StreamingMarkupBuilder to construct the XML needed for the POST.

Step 3. Construct and POST the XML to Execute the Process

You now have all the pieces of data to construct the XML for the process execution. The following is an example of what this XML looks like.

Elements

Executing a process uses the processexecution (prx) namespace. The following elements are required for a successful POST:

• type - the name of the process being run

• technician uri - the URI for the technician that will be listed as running the process

• input-output-map - one input-output-map element for each pair of inputs and outputs

• input uri - the URI for the input artifact

• output type - the type of artifact of the output

If the outputs of the process are analytes, then the following elements are also required:

• container uri - the URI for the container the output will be placed in

• value - the well placement for the output

To use the configured EPP process, the process-parameter element is required. This element is the name of the configured EPP that is executed when this process is posted.

Requirements

The following elements that match the processParamName variable must exist in the system before the process can be executed:

• Process type

• Technician

• Input artifact

• Container

• EPP parameter

With analyte outputs, if there are no containers with empty wells in the system, you must create one before running the process.

The XML constructed must match the configuration of the process type. For example, if the process is configured to have both analytes and a shared result file as outputs, you must have the following:

• An input-output-map for each pair of analyte inputs and outputs.

• An additional input-output-map for the shared result file.

The name on the process execution XML must match one of the possibly declared EPP parameter names. This requirement is true for any EPP parameters.

Expected Output and Results

If the POST is Successful, then the process XML is returned.

In the following example, there are two <input-output-map> elements. The second instance has the output-generation-type of PerAllInputs. This element indicates that the result file is shared and only one is produced, regardless of the number of inputs.

If the POST is Not Successful, then the XML that is returned contains the error that occurred when the POST completed. The following example shows this error:

Attachments

ExecuteProcessWithEPP.groovy:

autocomplete-process.py:

You can configure the automation trigger and use automation to invoke any external program that runs from a command line. Refer to the following for details:

EPP automation/support is compatible with API v2 r21 and later.

The API documentation includes the terms External Program Integration Plug-in (EPP) and EPP node.

As of Clarity LIMS v5.0, these terms are deprecated.

• EPP has been replaced with automation.

• EPP node is referred to as the Automation Worker or Automation Worker node. These components are used to trigger and run scripts, typically after lab activities are recorded in the LIMS.

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

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

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:

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

1. The name change in the XML

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

When working with containers, you can do the following:

• Add an Empty Container to the System

• Find the Contents of a Well Location in a Container

• Filter Containers by Name

When working with containers, you can do the following:

• Remove Samples from Workflows

• Requeue Samples

• Rearray 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:

// Determine the analyte's URI and retrieve it
arbitraryAnalyteArtifactURI = "http://${hostname}/api/v2/artifacts/${artifactLIMSID}"
arbitraryArtifactNode = GLSRestApiUtils.httpGET(arbitraryAnalyteArtifactURI, username, password)
println GLSRestApiUtils.nodeToXmlString(arbitraryArtifactNode)
 
// Retrieve the analyte's sample
def rootSampleURI = arbitraryArtifactNode.'sample'[0].'@uri'
rootSampleNode = GLSRestApiUtils.httpGET(rootSampleURI, username, password)
println GLSRestApiUtils.nodeToXmlString(rootSampleNode)
 
// Retrieve the sample's root analyte
def rootAnalyteArtifactURI = rootSampleNode.'artifact'[0].'@uri'
rootAnalyteArtifactNode = GLSRestApiUtils.httpGET(rootAnalyteArtifactURI, username, password)
println GLSRestApiUtils.nodeToXmlString(rootAnalyteArtifactNode)

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:

<art:artifact xmlns:art="http://genologics.com/ri/artifact" uri="http://yourIPaddress/api/v2/artifacts/EXA2241A1DN3?state=18882" limsid="EXA2241A1DN3">
  <name>Example Analyte Artifact</name>
  <type>Analyte</type>
  <output-type>Analyte</output-type>
  <parent-process uri="http://yourIPaddress/api/v2/processes/DNA-SA1-100914-24-1917" limsid="DNA-SA1-100914-24-1917"/>
  <qc-flag>UNKNOWN</qc-flag>
  <location>
    <container uri="http://yourIPaddress/api/v2/containers/27-3543" limsid="27-3543"/>
    <value>A:2</value>
  </location>
  <working-flag>false</working-flag>
  <sample uri="http://yourIPaddress0/api/v2/samples/EXA2241A1" limsid="EXA2241A1"/>
</art: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:

<smp:sample xmlns:smp="http://genologics.com/ri/sample" uri="http://yourIPaddress/api/v2/samples/EXA2241A1" limsid="EXA2241A1">
  <name>Example Sample</name>
  <project uri="http://yourIPaddress/api/v2/projects/EXA2241" limsid="EXA2241"/>
  <artifact uri="http://yourIPaddress/api/v2/artifacts/EXA2241A1SAM1?state=18879" limsid="EXA2241A1SAM1"/>
  <biosource/>
  <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="String" name="String Type UDF">Updated String UDF Value</udf:field>
  <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="Text" name="Text Type UDF">Updated Text UDF Value</udf:field>
  <udf:field xmlns:udf="http://genologics.com/ri/userdefined" unit="u" type="Numeric" name="Numeric Type UDF">3.140</udf:field>
  <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="Boolean" name="Boolean Type UDF">true</udf:field>
  <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="Date" name="Date Type UDF">2010-09-14</udf:field>
  <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="URI" name="URI Type UDF">http://www.genologics.com</udf:field>
  <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="Executable" name="Executable Type UDF">/usr/bin/yes</udf:field>
</smp: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).

<art:artifact xmlns:art="http://genologics.com/ri/artifact" uri="http://yourIPaddress/api/v2/artifacts/EXA2241A1SAM1?state=18879" limsid="EXA2241A1SAM1">
  <name>Example Analyte Artifact</name>
  <type>Analyte</type>
  <output-type>Analyte</output-type>
  <qc-flag>UNKNOWN</qc-flag>
  <location>
    <container uri="http://yourIPaddress/api/v2/containers/27-3543" limsid="27-3543"/>
    <value>A:1</value>
  </location>
  <working-flag>true</working-flag>
  <sample uri="http://yourIPaddress/api/v2/samples/EXA2241A1" limsid="EXA2241A1"/>
</art:artifact>

Attachments

SampleAndAnalyteRelations.groovy:

Samples in the lab are always in a container (eg, a tube, plate, or flow cell). When a container holds more than one sample, it is often easier to track the container rather than the individual samples. These containers can be found in API (v2 r21 or later).

In Clarity LIMS, containers are identified the LIMS ID or by name. The best way to find a container in the API is with the LIMS ID. However, the API also supports searching for containers by name by using a filter.

• LIMS ID—This is a unique ID. The container resource with LIMS ID 27-42 can be found at\

  Copy

  http://<YourIPaddress>/api/containers/27-42.

• Name—Container names can be unique, depending on how the server software was set up. In some labs, container names are reused to show when a container is recycled or when samples are submitted in containers.

The following example shows a container list filtered by name. Your system contains a series of containers, named with a specific naming convention.

Code example

the queried containers are named Smith553 and 001TGZ.

The request for a container with a specific name is structured in the same way as the request for all containers, but also includes a parameter to filter by name:

http://<YourIPaddress>/api/<apiversion>containers?name=<yourcontainername>

The name parameter is repeatable, and the results returned match any of the names queried:

// Determine the containers URIs and retrieve them
containersURI = "http://${hostname}/api/v2/containers?name=" + URLEncoder.encode('Smith553') + "&name=" + URLEncoder.encode('001TGZ')
containers = GLSRestApiUtils.httpGET(containersURI, username, password)
 
// For each container, print its limsid
containers.'container'.each {
    println it.@limsid
}

The GET method returns the full XML structure for the list of containers matching the query. In this case, the method returns the XML structure for containers with the names Smith553 and 001TGZ.

The XML contains a list of container elements. The .each method goes through each container node in the list and prints the container LIMS ID.

The XML returned is placed in the variable containers:

<con:containers>
    <container uri="http://yourIPaddress/api/v2/containers/27-505" limsid="27-505">
        <name>Smith553</name>
    </container>
    <container uri="http://yourIPaddress/api/v2/containers/27-511" limsid="27-511">
        <name>001TGZ</name>
    </container>
</con:containers> 

If the system has no containers named Smith553 or 001TGZ, then containers.container is an empty list. The .each method does nothing, as expected.

Expected Output and Results

When execution completes, the code returns the list of LIMS IDs associated with the container names Smith553 and 001TGZ. The name and LIMS IDs are different in this case (eg, 27-505 27-511).

Attachments

GetContainerNameFilter.groovy:

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

Step 1. Define Assignment Endpoint URI

Define the assignment endpoint URI using the following example. The assignment endpoint allows you to assign the artifacts to the desired workflow.

// Define the assignment endpoint URI
assignmentOrderURI = "http://${hostname}/api/v2/route/artifacts/" 

Step 2. Retrieve the Samples' Base Artifact URIs

You can also retrieve the base artifact URIs of the samples using the following example:

// Retrieve the samples' base artifact URIs
sampleAArtifactURI = GLSRestApiUtils.httpGET(sampleURIs[0], username, password).'artifact'.@uri
sampleBArtifactURI = GLSRestApiUtils.httpGET(sampleURIs[1], username, password).'artifact'.@uri 

Step 3. Gather Workflow URIs

Use the following example to gather the workflow URIs:

// Gather the required workflow URIs
workflowAURI = workflowURIs[0]
workflowBURI = workflowURIs[1] 

Step 4. Construct and POST the XML

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.

1. Create an assign tag with the URI of the destination workflow as an attribute.

2. Create an artifact tag inside the assign tag with the URI of the analyte as an attribute.

3. After the assignment XML is defined, you can POST it to the API. This POST performs the sample assignment.

// Create a new routing assignment using the Markup Builder
def assignmentOrder = builder.bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(rt: 'http://genologics.com/ri/routing')
    'rt:routing' {
        'assign'('workflow-uri': workflowAURI) {
            'artifact'(uri: sampleAArtifactURI)
        }
        'assign'('workflow-uri': workflowBURI) {
            'artifact'(uri: sampleBArtifactURI)
        }
    }
}

// Post the commands to the API
assignmentOrderNode = GLSRestApiUtils.xmlStringToNode(assignmentOrder.toString())
assignmentOrderNode = GLSRestApiUtils.httpPOST(assignmentOrderNode, assignmentOrderURI, username, password)
println GLSRestApiUtils.nodeToXmlString(assignmentOrderNode)

Expected Output and Results

After the script has run, the samples display in the first step of the first protocol in the specified workflows.

Attachments

AssigningArtifactsToWorkflows.groovy:

In high throughput labs, samples are worked on in batches and some work is executed by a robot. Sometimes, a set of plates must be rearrayed to one larger plate before the robot can begin the lab step.

This example accomplishes this using two scripts. One script is configured on a derived sample automation, while the second script is included in a command line configured on a step automation.

Prerequisites

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

• A project containing samples assigned to a workflow in Clarity LIMS.

• The workflow name.

• Given samples are assigned to the same workflow stage.

Code Example

This example demonstrates the following scripts:

• AssignToRearrayWf.groovy—Executed as a derived sample automation, this script assigns selected samples to the rearray step.

• AssignToLastRemoved.groovy—Executed after the rearray step, this script assigns the samples to the stage to which they were originally assigned. The script is included in a command line configured on a step automation.

Configure the Assign To Rearray Automation

1. In Clarity LIMS, under Configuration, select the Automation tab.

2. Select the Derived Sample Automation tab.

3. Select New Automation and create an automation that prompts the user for the workflow stage name to be used.

In the example, note the following:

• The {groovy_bin_location} and {script_location} parameters must be customized to reflect the locations on your computer.

• The –w option allows for user input to be passed to the script as a command-line variable.

AssignToRearrayWf Script Methods

Step 1. Retrieve the Artifact Nodes Using the Artifact LIMS IDs

The AssignToRearrayWf script has a list of artifact (sample) LIMS IDs given on the command line. To begin, use this script to build a list of artifact nodes.

The following code example builds a list of artifact URIs using the artifact LIMS ID list and the getArtifactNodes function. The resulting artifact URI list can then be used for a batchGET call to return the artifact nodes.

Step 2. Retrieve Workflow Name and URI

In this example, you can assume that the workflow name is known by the user and is passed to the script by user input when the automation is initiated.

The workflow can then be queried for using the passed workflow name. The workflow name is first encoded, and from this, you can retrieve the workflow URI.

Step 3. Make Sure that the Samples Belong to the Same Workflow Stage

For the samples to be placed in the same container, they must all belong to the same workflow and be currently queued to the same stage in that workflow.

Using the workflow name passed in by the user, do the following:

1. Search the workflow stage list of the first artifact and store the URI of the most recent stage that is part of the workflow, if it is queued. Otherwise, the script exits with an error message.

2. After storing the workflow stage URI of the first artifact, use the checkMatch function check against the remaining artifacts in the list to verify they are all currently queued to the same stage.

If all artifacts are queued for the stage, they are removed from the queue of the stage under the lastWfStageURI function.

Step 4. Build the XML for stage assignment using Streaming Markup Builder

In this example, all the artifacts are unassigned from the previous workflow stage returned and assigned to the rearray stage using the queuePlacementStep function. The previous methods have verified that the artifacts in the list can be rearrayed together.

The returned XML node is then posted using httpPOST.

Step 2. Configuring Placement Workflow, Protocol, and Step

1. In Clarity LIMS, under Configuration, select the Lab Work tab.

2. Create a master step of Standard step type.

3. From Configuration, select the Automation tab.

4. Select the Step Automation tab.

5. Create an automation for the AssignToLastRemoved.groovy script.

   The {groovy_bin_location} and {script_location} parameters must be customized to reflect the locations on your computer.
6. Enable the automation on the master step you created in step 2.
7. Configure a new protocol and step as follows.

   • On the Lab Work tab, create a non-QC protocol.

   • In the Protocols list, select the new protocol and then add a new step to it. Base the new step on the master step you created in step 2.
   • On the Step Settings form, in the Automation section, you see the step automation you configured. Configure the automation triggers as follows.

     • Trigger Location—Step

     • Trigger Style—Automatic upon exit
   • On the Placement milestone, Add 96 well plate and 384 well plate as the permitted destination container types for the step.
   • Remove the default Tube container type.
   • Save the step.

8. Configure a new workflow as follows:

   • On the Lab Work tab, create a workflow.

   • Add the protocol you created to the workflow.

AssignToLastRemovedStage Script Methods

Step 1. Build List of Artifact Nodes from the Step Input-Output Map

The first step of AssignToLastRemovedStage script is the same as for the AssignToRearrayWf script: return the artifact node list.

However, in this script, you are not directly given the artifact LIMS IDs. Instead, because you receive the step URI from the process parameter command line, you can collect the artifact URIs from the inputs of the step details input-output map using the getArtifactNodes function.

An example step details URI might be {hostname}/api/v2/steps/{stepLIMSID}/details.

Step 2. Assign Artifacts Back to the Original Stage

Each artifact in the list was removed from this stage before going through the rearray step.

With this in mind, and because the Clarity LIMS API stores artifact history by time (including stage history), the stage to which you now want to assign the samples to be the second-to-last stage in the workflow-stage list.

The following method finds the stage from which the artifacts were removed using the getLastRemoved function:

Step 3. Make Sure that Artifacts are Assigned to the Same Stage

You can then check to make sure all artifacts originated in this stage. This helps you avoid the scenario where the AssignToRearrayStage.groovy script was run on two groups of artifacts queried while in different workflow stages.

Step 4. Build the XML to Assign the Samples Back to the Returned Stage

Function: assignStage

This returned stage URI is then used to build the assignment XML to assign all the samples back to this stage with the assignStage function.

After posting this XML node, the samples are assigned back to the stage in which they began.

Step 3. Running the Assign to Rearray Automation

1. In the Projects Dashboard, select the samples to be rearrayed and run the 'Assign to Rearray' automation.

   On automation trigger, the {userinput} phrase will invoke a dialog that prompts for the full name of the workflow.

Step 4. Placing the Samples and Running the Rearray Step

1. The samples assigned by the Assign to Rearray automation is available to assign to a new container.
2. Add the samples to the Ice Bucket and begin work.

3. The placement screen opens, allowing you to place the samples into the new container, in your desired placement pattern.
4. Proceed to the Record Details screen, then on to Next Steps. Do not perform any actions on these screens.

5. In the next step drop-down list, select Mark Protocol as Complete and select Apply.

6. Selec Next. This initiates the 'Assign to last removed' trigger, which assigns the samples back to the step from which they were removed.

Attachments

AssignToRearrayWf.groovy:

AssignToLastRemoved.groovy:

As samples are processed in the lab, they are kept in a container. Some of these containers hold multiple samples, and lab scientists often must switch between container tracking and sample tracking.

If you process several containers each day and track them in a list, you would need to find which samples are in those containers. This way, you can record specifics from these container-based activities in relation to the samples from Clarity LIMS.

The example finds which sample is in a given well of a multi-well container using Clarity LIMS and API (v2 r21 or later).

Prerequisites

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

• Several samples exist in the Clarity LIMS.

• A step has been run on the samples.

• The outputs of the step have been placed in a 96-well plate.

Code example

Clarity LIMS captures detailed information for a container (eg, its name, LIMS ID, and the names of the sample in each of its wells). Information about the container and what it currently contains is available in the individual XML resource for the container.

The individual container resource contains a placement element for each sample placed on the container. Each placement element has a child element named value that describes one position on the container (eg, the placement elements for a 96-well plate include A:1, B:5, E:2).

Step 1. Retrieve the Container Information

In the script, the GET request retrieves the container specified by the container LIMS ID provided as input to the {containerLIMSID} parameter. The XML representation returned from the API is stored as the value of the container variable:

The following example shows the XML format returned for a container. The XML includes a placement element for each artifact that is placed in a well location in the container.

Step 2. Find the Artifact URI

When you look for the artifact at the target location, the script searches through the placement elements for one with a value element that matches the target. If a match is found, it is stored as the value of the contents variable.

The >uri attribute of the matching placement element is the URI of the artifact that is in the target well location. This is stored as the value of the artifactURI variable, and printed as the output of the script:

Expected Output and Results

Running the script in a console produces the artifact at

Attachments

GetContentsOfWellLocation.groovy:

When a lab processes samples, the samples are always in a container of some sort (eg, a tube, a 96-well plate, or a flow cell). In Clarity LIMS, this processing is modeled by placing all samples into containers. Because the Clarity LIMS interface relies on container placement for the display of many of its screens, adding containers is a critical step when running a process or adding samples through the API (v2 r21 or later).

The following example demonstrates how to add an empty container, of a predefined container type, to Clarity LIMS through the API.

Code example

Step 1. Define the New Container

Before you can add a container to the system, you must first define the container to be created. You can construct the XML that defines the container using StreamingMarkupBuilder, a built-in Groovy data structure designed to build XML structures.

To construct the XML, you must declare the container namespace because you are building a container. The minimum information that can be specified to create a container are the container name and container type.

If you also want to add custom field values to the container you are creating, you must declare the userdefined namespace.

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

Step 2. Post the New Container

The POST command posts the XML constructed by StreamingMarkupBuilder to the containers resource of the API. The POST command also adds a link from the containers URI (the list of containers) to the new container.

Expected Output and Results

The XML for the new container is as follows.

The XML for the list of containers, with the newly added container shown at the end of the list, is as follows.

For Clarity LIMS v5 and above, the Operations Interface Java client has been deprecated, and there is no equivalent Containers view screen in which to view empty containers added via the API. However, if you intend to add samples to Clarity LIMS through the API, this example is still relevant, as you must first add containers in which to place those samples.

Attachments

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

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 .

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:

In Clarity LIMS, derived sample automations are automations that users can run on derived samples directly from the Projects Dashboard.

The following example uses an automation to initiate a script that removes multiple derived samples from workflows. The example also describes the main functions included in the script, and shows how to configure the automation in Clarity LIMS and run it from the Projects Dashboard.

Prerequisites

Before removing samples from the workflows, make sure you have the following items:

• A project containing at least one sample assigned to a workflow.

• A step has been run on a sample, resulting in a derived sample.

• The derived sample is associated with one or more workflows.

Code example

The attached UnassignSamplesFromWorkflows.groovy script uses the derived sample automations feature to remove selected derived samples from their associated workflows. The following actions must be done when removing samples from these workflows.

Step 1. Create Sample Node List

This getSampleNodes function is passed a list of derived sample LIMS IDs (as a command-line argument) to build a list containing the XML representations of the samples. A for-each loop on the derived sample list makes a GET call for each sample and creates the sample node list. The following command-line example shows how the getSampleNodes function works:

This list is used to retrieve the sample URIs and the workflow-stage URIs. These URIs are required to build the unassignment XML.

Step 2. Retrieve Workflow URIs

The for loop does the following actions:

1. Makes a GET call for each workflow-stage to which the passed sample is assigned.

2. Retrieves the associated workflow URIs.

3. Returns a list containing all URIs for the workflows with which the sample is associated.

Step 3. Build and POST the Unassignment XML

Now that the functions used to retrieve both the derived sample URIs and the workflow URIs have been built, you can use StreamingMarkupBuilder to create the XML and then POST to the unassignment URI. This process can be done with the unassignSamplesFromWorkflows and unassignSamplesXML functions.

To unassign the derived samples, you can POST to the artifacts URI at ${hostname}v2/route/artifacts. Nested loops create the declaration for each sample and their associated workflows. The following example shows the declaration built in the format of the workflow URI, with the unassign flag followed by the URI of the sample being unassigned.

Now that the XML is built, convert the XML to a node and post it as follows.

1. Use GLSRestApiUtils to convert the XML to a node

2. POST the node using the following command:

Configuring and Running the Automation

Automations can be configured and run using Clarity LIMS

1. In Clarity LIMS, under Configuration, select the Automation tab.

2. Select the Derived Sample Automation tab.

3. Select New Automation and enter the following information:

   • Automation Name—This is the name that displays to the user running the automation from the Projects Dashboard. Choose a descriptive name that reflects the functionality/purpose (eg, Remove from Workflows).

   • Channel Name—Enter the channel name.

   • Command Line—Enter the command line required to invoke the script.\

4. Select Save.

Run the automation as follows.

1. Open the Projects Dashboard.

2. Select a project containing in-progress samples. Select In-progress samples.

   In the sample list, you see the submitted and derived samples that are currently in progress for this project.

3. Select one or more derived samples.

   Selecting samples activates the Action button and drop-down list.

4. In the Action drop-down list, select the Remove From Workflows automation created in the previous step.

Expected Output and Results

The API of the selected samples now shows an additional workflow stage with a status of REMOVED.

Attachments

UnassignSamplesFromWorkflows.groovy:

Derived sample automations are automations that users can run on derived samples directly from the Projects Dashboard in Clarity LIMS.

The following example uses an automation to initiate a script that requeues samples to an earlier step in the workflow. The example also describes the main functions included in the script and demonstrates the configuration options that prompt the user for input. These options allow for greater flexibility during script runs. Before you follow the example, make sure that you have the following items:

• A project containing samples assigned to a multi-stage workflow.

• Samples that must be requeued. These samples must have completed at least one step in the workflow and must be available for requeue.

Code Example

The purpose of the attached RequeueSamples.groovy script is to requeue selected derived samples to a previous step in the workflow with the derived sample automations feature.

Step 1. Get Sample Nodes

The getSampleNodes function is passed a list of derived sample LIMS IDs (as a command-line argument) to build a list containing the XML representations of the samples. The resulting sample URI list can then be used with a batchGET to return the sample nodes:

Step 2. Retrieve Workflow and Stage URIs

To retrieve the workflow name, you can URL encode the workflow name and use the result to query and retrieve the workflow URI:

The stage names are guaranteed to be unique for each workflow. However, they may not be unique in the Clarity LIMS system. As a result, the stage URI cannot be queried for in the same way as the workflow URI.

Instead, you can navigate through the workflow node to find the stage that matches the stage name specified using the getStageURI function. If a match is found, return the stage URI.

Step 3. Verify Each Sample Meets the Requeue Criteria

Next, you must make sure that each sample meets the criteria to be requeued using the canRequeue function. The following method checks all workflow stages for the samples:

• If a match is found between a workflow stage URI and the stage URI specified, the sample node is added to a list of samples that can be requeued using the requeueList function.

• If all the samples have this match and a status that allows for requeue, the list is returned. Otherwise, the script exits with an error message that states the first sample to cause failure.

Step 4. Check and Retrieve Workflow Stage for Sample Node

In this example, both unassignment from and assignment to a workflow stage must occur to complete the requeue. As the samples are requeuing to a previous stage in the workflow and can currently be queued for another stage, you must remove them from these queues.

The getCurrentStageURI and lastStageRun functions check the sample node for its most recent workflow stage. If the node is in a queued status, it returns that stage URI to be unassigned.

Step 5. Build the XML Assignment

Using the previous methods and their results, the following code uses Streaming Markup Builder and the assignmentXML function to build the XML to be posted:

The returned XML node is then posted using httpPOST.

Configuring and Running the Automation

Add and configure the automation

1. In Clarity LIMS, under Configuration, select the Automation tab.

2. Select the Derived Sample Automation tab.

3. Select New Automation and enter the following information:

   • Automation Name—This is the name that displays to the user running the automation from the Projects Dashboard. Choose a descriptive name that reflects the functionality/purpose (eg, Requeue Samples).

   • Channel Name—Enter the channel name.

   • Command Line—Enter the command line required to invoke the script.
4. Select Save.

Run the automation as follows.

1. Open the Projects Dashboard.

2. Select a project containing in-progress samples. Select In-progress samples.

   In the sample list, you will see all of the submitted and derived samples that are currently in progress for this project.

3. Select one or more derived samples. Selecting samples activates the Action button and drop-down list.

4. In the Action drop-down list, select the Requeue Samples automation.

In this example, the –w and -t {userinput} options invoke a dialog box on automation trigger. The user is required to enter two parameters: the full name of the stage and the workflow for which selected samples are to be requeued. The names must be enclosed in quotation marks.

Expected Output and Results

If the requeue is successful, each requeued sample is marked with a complete tag. Hovering over a sample shows a more detailed message.

Attachments

RequeueSamples.groovy:

When working with projects and accounts, you can do the following:

• Remove Information from a Project

• Add a New Project to the System with UDF/Custom Field Value

• Get a Project Name

• Find an Account Registered in the System

• Update Contact (User and Client) Information

When working with process and step outputs, you can do the following:

• Update UDF/Custom Field Values for a Derived Sample Output

• Rename Derived Samples Using the API

• Find the Container Location of a Derived Sample

• Traverse a Pooled and Demultiplexed Sample History/Genealogy

• View the Inputs and Outputs of a Process/Step

When working with multiplexing, you can do the following:

• Find the Index Sequence for a Reagent Label

• Demultiplexing

• Pool Samples with Reagent Labels

• Apply Reagent Labels with REST

• Apply Reagent Labels When Samples are Imported

• Apply Reagent Labels by Adding Reagents to Samples

As samples are processed in the lab, substances are moved from one container to another. Because container locations are sometimes used to reference the sample in data files, tracking the location of these substances within containers is one of the key values that Clarity LIMS provides to the lab.

Within the REST API (v2 r21 or later), analytes represent the substances on which processes/steps are run. These analytes are the substances that are chemically altered and transferred between containers as samples are processed in the lab.

Each individual sample resource has an analyte artifact that describes its container location and is used to run processes.

In Clarity LIMS, steps are not run on the original submitted samples, but are instead run on (and can also generate) derived samples. In the API, derived samples are known as analytes. Each sample resource, which is the original submitted sample in Clarity LIMS, has a corresponding analyte that is used for running processes/steps and describing placement in a container.

For more information on analyte artifacts and other REST resources, see Structure of REST Resources.

Prerequisites

For all Clarity LIMS users, make sure you have done the following actions:

• Added a sample to Clarity LIMS.

• Run a process/step on the sample, with the same process/step generating a derived sample output.

• Added the generated derived sample to a multi-well container (eg, a 96-well plate).

Code Example

The container location information for an individual derived sample/analyte is located within the XML for the individual artifact resource. Because artifacts are generated by running steps in the LIMS, this is a logical place to keep track of the location.

Within a script, you can use a GET method to request the artifact. The resulting XML structure contains all the information related to the artifact, including its container and well location.

In this example, a derived sample named Brain-600 is placed in well A:1 of a container with LIMS ID 27-1259. This information is found in the location element.

<art:artifact uri="http://yourIPaddress/api/v2/artifacts/HAM751A481PA1?state=9995" limsid="HAM751A481PA1">
    <name>Brain-600</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <volume unit="uL">645.0</volume>
    <concentration unit="ug/mL">0.5478</concentration>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://yourIPaddress/api/v2/containers/27-1259" limsid="27-1259"/>
        <value>A:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/HAM751A481" limsid="HAM751A481"/>
</art:artifact> 

The location elements has two child data elements:

• One linking to the container URI, which specifies which container the analyte is in.

• One for the well location, which has the name 'value' in the XML structure.

Valid values for a well location can be either numeric or alphabetic, and are determined by the configuration of the container in Clarity LIMS.

Well locations are always represented in the row:column format. For example, a 96-well plate can have locations A:1 and C:12, and a tube can have a single well called 1:1.

Step 1. Retrieve the Artifact

Use the following XML example to retrieve the artifact:

// Retrieve the artifact
artifactURI = "http://${hostname}/api/v2/artifacts/${artifactLIMSID}"
artifact = GLSRestApiUtils.httpGET(artifactURI, username, password)

Step 2. Access, Store, and Print the Container Location

Because the container position is structured in the row:column format, you can store the row and column in separate variables by splitting the container position on the colon character. You can access the string value of the location value node using the text() method, as shown in the following code:

// Separate the artifact's position inside of its container
containerPosition = artifact.location.value.text()
positionList = containerPosition.tokenize(':')
 
// Output its position
row = positionList[0]
column = positionList[1]
println "This sample is located at row: $row, column: $column"

Expected Output and Results

Running the script in a console produces the following output:

This sample is located at row: A, column: 1

Attachments

GetContainerAnalyteLocation.groovy:

The large capacity of current Next Generation Sequencing (NGS) instruments means that labs are able to perform multiplexed experiments with multiple samples pooled into a single lane or region of the container. Before being pooled, samples are assigned a unique tag or index. After sequencing and initial analysis are complete, the sequencing results must be demultiplexed to separate data and relate the results back to each individual sample.

Clarity LIMS allows you to track a multiplexing workflow by adding reagents and reagent labels to artifacts, and then using the reagent labels to demultiplex the resulting files.

There are several ways to apply reagent labels. However, all methods involve creating placeholders that link the final sequences back to the original submitted samples. Either the lab scientist or an automated process must determine which file actually belongs with which placeholder. For more information on applying reagent labels, refer to Work with Multiplexing.

This example walks through assigning user-defined field (UDF)/custom field values to the demultiplexed output files based on upstream derived sample (analyte) UDF/custom field values. This includes upwards traversal of a sample history / genealogy, based on assigned reagent labels. This differs from upstream traversal based strictly upon process input-output mappings.

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.

Prerequisites

If you are using Clarity LIMS v5 or later, make sure you have completed the following actions:

• Created a project and have added multiple samples to it.

• Run the samples through a sequence of steps that perform the following:

  • Reagent addition / reagent label assignment

  • Pooling

  • Demultiplexing (to produce a set of per-reagent-label result file outputs).

• Set a Numeric custom field value on each derived sample input to the reagent addition process.

• A Numeric custom field with no assigned value exists on each of the per-reagent-label result file outputs. The value of this field will be computed from the set of upstream derived sample custom field values corresponding to the reagent label of the result file.

You also must make sure that API v2 r21 or later is installed.

Code Example

Due to the complexity of NGS workflows, beginning at the top level submitted sample resource and working down to the result file is not the most efficient way to traverse the sample history/genealogy. It is easier to start with the result file artifact, and then trace upward to find the process with the UDFs/custom fields that you are looking for.

Starting from the per-reagent-label result file, you can traverse upward in the sample history using the parent process URI in the XML returned for each artifact. At each level of the sample history, the number of artifacts returned may increase due to processes that pooled individual artifacts.

In this example:

• The upstreamArtifactLUIDs list represents the current set of relevant artifacts.

• The foundUpstreamArtifactNodes list stores the target upstream artifact nodes found.

• The sample history traversal stops at the inputs to the process that performed the reagent addition/reagent label assignment.

targetDownstreamArtifactNode = GLSRestApiUtils.httpGET(artifactsListURI + artifactLUID, username, password)
    targetReagentLabel = targetDownstreamArtifactNode.'reagent-label'[0]?.'@name'
    if (!targetReagentLabel) {
        println "Specified artifact should contain at least one reagent-label.  Skipping ${artifactLUID}..."
        continue
    }
    // At each upstream level of the workflow the number of searched artifacts may increase due to Pooling processes
    upstreamArtifactLUIDs = [ artifactLUID ]
    /*
     * This 'stack' will store all upstream artifacts that serve as input to an 'Add Multiple Reagents' process
     * which are subsequently assigned the 'target' Reagent Label by this process.
     */
    foundUpstreamArtifactNodes = []

The traversal is executed using a while loop over the contents of the upstreamArtifactLUIDs list.

The list serves as a stack of artifacts. With each iteration of the loop, an artifact is removed from the end of the list and the relevant input artifacts to its parent process are pushed back onto the end of the list.

while (!upstreamArtifactLUIDs.isEmpty()) {
        currentArtifactLUID = upstreamArtifactLUIDs.pop()
        currentArtifactNode = GLSRestApiUtils.httpGET(artifactsListURI + currentArtifactLUID, username, password)
        /*
         * Upstream traversal will stop when either an artifact is found that does not have reagent label(s) assigned
         * (i.e. the artifact is the input to a process that adds reagents and reagent labels), or a root artifact is found.
         * At this point, the current artifact is added to the list of 'found' upstream artifact nodes.
         */
        if (currentArtifactNode.'reagent-label'.isEmpty() || currentArtifactNode.'parent-process'.isEmpty()) {
            foundUpstreamArtifactNodes += [currentArtifactNode]
        } else if (currentArtifactNode.'reagent-label'.collect { it.'@name' }.contains(targetReagentLabel)) {
            /*
             * If the current artifact contains the 'target' reagent label, continue traversing upstream.
             * Get the artifact's parent process
             */
            parentProcessURI = currentArtifactNode.'parent-process'[0].@uri
            parentProcessNode = GLSRestApiUtils.httpGET(parentProcessURI, username, password)
            // Find all input-output maps for the parent process
            parentProcessNode.'input-output-map'.each {
                ioMapInputLUID = it.'input'[0].@limsid
                ioMapOutputLUID = it.'output'[0].@limsid
                // Push all process input artifacts that have the current artifact as the mapped process output onto the 'stack'
                if( ioMapOutputLUID == currentArtifactLUID && !upstreamArtifactLUIDs.contains(ioMapInputLUID) ) {
                    upstreamArtifactLUIDs.push(ioMapInputLUID)
                }
            }
        }
    }

After the loop has executed, the foundUpstreamArtifactNodes list will contain all of the artifacts that are assigned the reagent label of interest upon execution of the next process in the sample history.

The final step in the script assigns a value to a Numeric UDF / custom field on the per-reagent-label output result file, Mean DNA Prep 260:280 Ratio, by computing the mean value of a Numeric UDF / custom field on each of the foundUpstreamArtifactNodes, DNA prep 260:280 ratio.

First, compute the mean using the following example:

/*
 * Compute the 'Mean DNA Prep 260:280 Ratio' for all upstream analyte artifacts that have the
 * target Reagent Label applied.  The assumption here is that the 'DNA prep 260:280 ratio' UDF
 * is set on analytes that serve as input to an 'Add Multiple Reagents' process that assigns Reagent Labels.
 */
avgAcrossUpstreamArtifacts = foundUpstreamArtifactNodes.collect {
    foundUdf = it.'udf:field'.find{ it.'@name' == upstreamArtifactUdfToMine }
    return foundUdf ? foundUdf.value()[0] as double : 0.0
}.sum()/foundUpstreamArtifactNodes.size()

Then, set the UDF/custom field on the per-reagent-label output result file using the following example:

// Set the computed mean on the 'Mean DNA Prep 260:280 Ratio' UDF on the target downstream ResultFile
targetDownstreamAritfactUDF = targetDownstreamArtifactNode.'udf:field'.find{ it.'@name' == downstreamArtifactUdfToUpdate }
if (targetDownstreamAritfactUDF) {
    targetDownstreamAritfactUDF.setValue(avgAcrossUpstreamArtifacts)
} else {
    targetDownstreamArtifactNode.appendNode('udf:field',
                    ['name':downstreamArtifactUdfToUpdate,
                     'xmlns:udf':'http://genologics.com/ri/userdefined'],
                     avgAcrossUpstreamArtifacts)
}

Attachments

TraversingPooledDemuxGenealogy.groovy:

When samples are processed in the lab, they generally produce child samples that are altered in some way. Eventually, the samples are analyzed on an instrument, with the result being a data file. Often these data are analyzed further, which produces additional data files.

The sample processing that occurs in the lab is modeled as steps in the Clarity LIMS web interface. In the REST API (v2 r21 or later), this processing is modeled as processes, and the samples and files that are processed are represented as artifacts. Understanding the representation of inputs and outputs within the XML for an individual process is critical to being able to use the REST API effectively.

Prerequisites

If you are using Clarity LIMS v5 or later, make sure that you have done the following actions:

• Added samples to the LIMS.

• Configured a step that generates derived samples in the Lab Work tab.

• Configured a file placeholder for a sample measurement file to be generated and attached by an automation script at run time. This configuration is done in the Master Step Settings of the step on the Record Details milestone.

• Configured an automation that generates the sample measurement file and have enabled it on the step. This configuration is done in the Automation tab.

• Configured the automation triggers. This configuration is done in the Step Settings screen, under the Record Details milestone.

• Run the step on some samples.

Code Example

As of Clarity LIMS v5, the Operations Interface Java client has been deprecated. In LIMS v5 and later, there is no equivalent screen to the Input/Output Explorer where you can select step inputs/outputs and generated files and view their corresponding inputs/outputs and files.

However, the following API code example is still relevant and will produce the same results.

Step 1. Request Individual Process Resource

The first step in this example is to request the individual process resource through a GET method. The full XML representation returned includes the input-output-map.

To illustrate the relationships between the inputs and outputs, you can save them using a Groovy Map data structure. This maps the output LIMS IDs to a list of input LIMS IDs associated with each output, as shown in the following example:

outputToInputMap = [:]
processURI = "http://${hostname}/api/v2/processes/${processLIMSID}"
p+cess = GLSRestApiUtils.httpGET(processURI, username, password) 

The process variable now holds the complete XMLstructure returned from the processURI.

In the following example XML snippet, elements of the input-output-map are labeled with <input-output-map>:

<prc:process uri="http://IPAddress/api/v2/processes/TES-SA1-130107-24-5259" limsid="TES-SA1-130107-24-5259">
    <type uri="http://IPAddress/api/v2/processtypes/355">Cookbook Example Process</type>
    <date-run>2013-01-07</date-run>
    <technician uri="http://IPAddress/api/v2/researchers/1">
        <first-name>System</first-name>
        <last-name>Administrator</last-name>
    </technician>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A3PA1?state=8055" uri="http://IPAddress/api/v2/artifacts/ADM224A3PA1?state=8040" limsid="ADM224A3PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/92-13007?state=8065" output-generation-type="PerAllInputs" output-type="ResultFile" limsid="92-13007" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A3PA1?state=8055" uri="http://IPAddress/api/v2/artifacts/ADM224A3PA1?state=8040" limsid="ADM224A3PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/ADM224A3TE3?state=8054" output-generation-type="PerInput" output-type="Analyte" limsid="ADM224A3TE3" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A5PA1?state=8053" uri="http://IPAddress/api/v2/artifacts/ADM224A5PA1?state=8047" limsid="ADM224A5PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/92-13007?state=8065" output-generation-type="PerAllInputs" output-type="ResultFile" limsid="92-13007" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A5PA1?state=8053" uri="http://IPAddress/api/v2/artifacts/ADM224A5PA1?state=8047" limsid="ADM224A5PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/ADM224A5TE3?state=8060" output-generation-type="PerInput" output-type="Analyte" limsid="ADM224A5TE3" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A2PA1?state=8056" uri="http://IPAddress/api/v2/artifacts/ADM224A2PA1?state=8042" limsid="ADM224A2PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/92-13007?state=8065" output-generation-type="PerAllInputs" output-type="ResultFile" limsid="92-13007" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A2PA1?state=8056" uri="http://IPAddress/api/v2/artifacts/ADM224A2PA1?state=8042" limsid="ADM224A2PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/ADM224A2TE3?state=8059" output-generation-type="PerInput" output-type="Analyte" limsid="ADM224A2TE3" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A4PA1?state=8063" uri="http://IPAddress/api/v2/artifacts/ADM224A4PA1?state=8048" limsid="ADM224A4PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/92-13007?state=8065" output-generation-type="PerAllInputs" output-type="ResultFile" limsid="92-13007" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A4PA1?state=8063" uri="http://IPAddress/api/v2/artifacts/ADM224A4PA1?state=8048" limsid="ADM224A4PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/ADM224A4TE3?state=8057" output-generation-type="PerInput" output-type="Analyte" limsid="ADM224A4TE3" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A1PA1?state=8061" uri="http://IPAddress/api/v2/artifacts/ADM224A1PA1?state=8046" limsid="ADM224A1PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/92-13007?state=8065" output-generation-type="PerAllInputs" output-type="ResultFile" limsid="92-13007" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A1PA1?state=8061" uri="http://IPAddress/api/v2/artifacts/ADM224A1PA1?state=8046" limsid="ADM224A1PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/ADM224A1TE3?state=8058" output-generation-type="PerInput" output-type="Analyte" limsid="ADM224A1TE3" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A6PA1?state=8064" uri="http://IPAddress/api/v2/artifacts/ADM224A6PA1?state=8045" limsid="ADM224A6PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/92-13007?state=8065" output-generation-type="PerAllInputs" output-type="ResultFile" limsid="92-13007" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://IPAddress/api/v2/artifacts/ADM224A6PA1?state=8064" uri="http://IPAddress/api/v2/artifacts/ADM224A6PA1?state=8045" limsid="ADM224A6PA1" />
        <output uri="http://IPAddress/api/v2/artifacts/ADM224A6TE3?state=8062" output-generation-type="PerInput" output-type="Analyte" limsid="ADM224A6TE3" />
    </input-output-map>
</prc:process> 

All of the input and output URIs include a ?state= some number. State allows Clarity LIMS to track historical values for QC, volume, and concentration, so you can compare the state of an analyte before and after a process was run. However, when you make changes to an artifact you should always work with the most current state.

To make sure that you are getting the current state when you do a GET request, simply remove the state from the artifact URI.

Step 2. Map Output LIMS IDs to Input LIMS IDs

You can examine each input-output-map to find details about the relationship represented between inputs and outputs. The following code puts the output and input LIMS IDs into an array named outputToInputMap.

As the output type is also important for further processing, outputToInputMap is formatted as follows:

outputLIMSID -> [output-type, inputLIMSID-1, inputLIMSID-2, inputLIMSID-3, ...|output-type, inputLIMSID-1, inputLIMSID-2, inputLIMSID-3, ...]

If the output is shared for all inputs (eg, the sample measurement file with LIMS ID 92-13007), the inputs to the process are listed. If the output relates to an individual input, only the LIMS ID for that particular input will be listed.

// For each io-map in the process, add its information to outputToInputMap
process.'input-output-map'.each {
    outputType = it.'output'[0].'@output-type'
    outputLIMSID = it.'output'[0].@limsid
    inputLIMSID = it.'input'[0].@limsid
    // outputToInputMap stores all the output type and LIMS IDs of all the inputs to the output
    if (!outputToInputMap[outputLIMSID]) {
        outputToInputMap[outputLIMSID] = [outputType, inputLIMSID]
    } else {
        // If entry already exists, add another input to the list
        outputToInputMap[outputLIMSID] << inputLIMSID
    }
}

Outputs are listed in multiple input-output-map elements when they have multiple input files generating them. The first time any particular output LIMS ID is seen, the output type and input LIMS ID in the input-output-map are added to the list, stored in outputToInputMap.

If the output LIMS ID already has a list in outputToInputMap, then the code adds input LIMS ID to the list.

Step 3. Print the List

One way to access the information is to print it out. You can run through each key-value pair and print the information it contains, as shown in the following example:

// Print the contents of the map, which stores the inputs LIMSIDs under the output's LIMSID
o+tputToInputMap.each { key, value ->    println "$key is a(n) ${value[0]} with input:"
    for (int i = 1; i < value.size(); i++) {
        println '\t' + value[i]
    }
}

Expected Output and Results

After running the script on the command line, an output similar to the following will be generated, whereby the inputs used to generate each output are listed.

92-13007 is a(n) ResultFile with input:
        27-2028
        27-2029
        27-2030
        27-2031
        27-2032
        27-2033
27-2034 is a(n) Analyte with input:
        27-2028
27-2035 is a(n) Analyte with input:
        27-2029
27-2036 is a(n) Analyte with input:
        27-2030
27-2037 is a(n) Analyte with input:
        27-2031
27-2038 is a(n) Analyte with input:
        27-2032
27-2039 is a(n) Analyte with input:
        27-2033

Attachments

GetProcessInputOutput.groovy:

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.

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:

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

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:

UpdateUDFAnalyteOutput.groovy:

A common requirement in applications involving indexed sequencing is to determine the sequence corresponding to a reagent label. This example shows how to configure index reagent types, which you can then use to find the sequence for a reagent label. Before you follow the example, make sure that you have a compatible version of API (v2 r14 to v2 r24).

Code Example

Reagents and reagent labels are independent concepts in the API. However, the recommended practice is to name reagent labels after reagent types. This allows you to use the label name to look up the sequence information on the reagent type resource. This practice is consistent with the Operations Interface process wizards. When a reagent is applied to a sample in the user interface, a reagent label with the same name of the reagent type is added to the analyte resource.

The following actions are also recommended:

1. Configure an index reagent type with the correct sequence for each type of index or tag you plan to use.

2. Use the names of the index reagent types as reagent labels.

Following these practices allows you to find the sequence for a reagent label by looking up the sequence in the corresponding reagent type.

Step 1. Configure Index Reagent Types

For each index or tag you plan to use in indexed sequencing, configure a corresponding index reagent type as follows.

1. As administrator, click Configuration > Consumables > Labels.

2. Add a new label group.

3. Then, to add labels to the group:

   • Download a template label list (Microsoft® Excel® file) from the Labels configuration screen.

   • Add reagent type details to the downloaded template.

   • Upload the completed label list.

Step 2. Retrieve the sequence for a reagent label using the REST API

After you have configured reagent types for each indexing sequence you intend to use, and have used those reagent type names as reagent label names, you can easily retrieve the corresponding sequence using the REST API.

The following code snippet shows how to retrieve the index sequences (when available):

// Determine the URI of the labeled artifact and retrieve it
labeledArtifactURI = "http://${hostname}/api/v2/artifacts/${labeledArtifactLIMSID}"
labeledArtifact = GLSRestApiUtils.httpGET(labeledArtifactURI, username, password)
 
// Gather its reagent labels
reagentLabels = labeledArtifact.'reagent-label'.@name
if (!reagentLabels) {
    println "No labels found"
    return
}
 
// Build a query URI for possibly multiple reagent labels and execute it
queryParameters = reagentLabels.collect { "name=${it.replace(' ', '+')}" }.join('&')
reagentTypesURI = "http://${hostname}/api/v2/reagenttypes/"
reagentTypeQueryURI = reagentTypesURI + '?' + queryParameters
reagentTypeLinks = GLSRestApiUtils.httpGET(reagentTypeQueryURI, username, password)
 
// For each reagent type found, retrieve it
reagentTypeLinks.'reagent-type'.@uri.each {
    reagentType = GLSRestApiUtils.httpGET(it, username, password)
    reagentTypeName = reagentType.@name
    reagentLabels.remove(reagentTypeName)
    index = reagentType.'special-type'.'attribute'.find { it.@name = 'Sequence' }?.@value
 
    // Output the result
    println "Label: $reagentTypeName"
    println "Index: $index"
}
 
// If there are reagent labels that found no matches
if (reagentLabels) {
    unmatchedLabels = reagentLabels.join(',')
    println "No reagent types found for labels: $unmatchedLabels"
}

For an artifact labeled with Index 1, this would produce the following information:

Label: Index 1
Index: ATCACG

Attachments

RetrievingReagentLabelIndex.groovy:

Imagine that you use projects in Clarity LIMS to track a collection of sample work that represents a subset of work from a larger translational research study. The translational research study consists of several projects within the LIMS and the information about each of the projects that make up the research study is predefined in another system.

Before the work starts in the lab, you can use the information in the other system to automatically create projects. This reduces errors and means that lab scientists do not have to spend time manually entering data a second time.

This example shows how to automate the creation of a project using a script and the projects resource POST method.

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.

Prerequisites

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

• A user-defined field (UDF) / custom field named Objective is defined for projects.

• A project name that is unique and does not exist in the system.

• A compatible version of API (v2 r21 or later).

Code Example

Before you can add a project to the system via the API, you must construct the XML representation for the project you want to create. You can then POST the new project resource.

Step 1. Define the Project

You can define the project XML using StreamingMarkupBuilder, a built-in Groovy data structure designed to build XML structures.

• Declare the project namespace because you are building a project.

• If you wish to include values for project UDFs as part of the project XML you are constructing, then you must also declare the userdefined namespace.

In the following example, the project name, open date, researcher, and a UDF / custom field named Objective are included in the XML constructed for the project.

• For Clarity LIMS v5 or later, UDTs are only supported in the API.

Step 2. Post the project

For the POST to the projects resource to be successful, only project name and researcher URI are required. Adding more details is a good practice for keeping your system organized and understanding what must be accomplished for each project.

The following POST command adds a new project resource using the XML constructed by StreamingMarkupBuilder:

Expected Output and Results

The XML returned after a successful POST of the XML built by StreamingMarkupBuilder is the same as the XML representation of the project:

Attachments

PostProject.groovy:

The following example shows you how to remove information from a project using Clarity LIMS and API (compatible with v2 r21 and later).

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.

Prerequisites

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

• A user-defined field (UDF) / custom field named Objective is defined for projects.

• A project name that is unique and does not exist in the system.

Code Example

This example does the following actions:

1. POST a new project to the LIMS, with a UDF / custom field value for Objective.

2. Remove a child XML node from the parent XML representing the project resource.

3. Update the project resource.

Step 1. POST a New Project with a UDF Value for Objective

First, set up the information required to perform a successful project POST. The project name must be unique.

The projectNode should contain the response XML from the POST and resemble the following output:

Step 2. Remove Child XML Node from Parent XML Node

The following code removes the child XML node <udf:field> from the parent XML node <prj:project>:

If multiple nodes of the same type exist, [0] is the first item in this list of same typed nodes (eg, 0 contains 1st item, 1 contains 2nd item, 2 contains 3rd item, and so on).

To remove the 14th udf:field, you would use projectNode?.children()?.remove(projectNode.'udf:field'[13])

Attachments

RemoveChildNode.groovy:

Lab scientists must understand the priority of the samples they are working with. To help them prioritize their work, you can rename the derived samples generated by a step so that they include the priority assigned to the original submitted sample.

If you would like to rename a batch of derived samples, you can increase the script execution speed by using batch operations. You can also use a script to rename a derived sample after a step completes.

Prerequisites

If you are using Clarity LIMS v5 and later, make sure that you have done the following actions:

• Added samples to the system.

• Defined a global custom field named Priority on the Submitted Sample object. The field should have default values sp1, sp2, and sp3, and it should be enabled on a step.

• Run samples through the step with the Priority of each sample set to sp1, sp2, or sp3.

Code example

In this example, six samples have been added to a project in Clarity LIMS. The submitted samples names are Heart-1 through Heart-6. The samples are run through a step that generates derived samples, and the priority of each sample is set.

By default, the name of the derived samples generated by the step would follow the name of the original submitted samples as shown in the Assign Next Steps screen of the step.

This example appends the priority of the submitted sample to the name of the derived sample output. The priority is defined by the Priority sample UDF (in Clarity LIMS v4.2 or earlier) or the Priority submitted sample custom field (in Clarity LIMS v5 or later).

Renaming the derived sample consists of the following steps:

• Request the step information (process resource) for the step that generated the derived sample (analyte resource).

• Request the individual analyte resource for the derived sample to be renamed.

• Request the sample resource linked from the analyte resource to get the submitted sample UDF/custom field value to use for the update.

• Update the individual analyte output resource with the new name.

Step 1. Request the Step Information (Process Resource) for the Step that Generated the Derived Sample (Analyte Resource)

When using the REST API, you will often start with the LIMS ID for the step that generated a derived sample. The key API concepts are as follows.

• Information about a step is stored in the process resource.

• In general, automation scripts access information about a step using the processURI, which links to the individual process resource. The input-output-map in the XML returned by the individual process resource gives the script access to the artifacts that were inputs and outputs to the process.

• Information about a derived sample is stored in the analyte resource. This is used as the input and output of a step.

• Analytes are also used to record specific details from lab processing.

• The XML representation for an individual analyte contains a link to the URI of its submitted sample, and to the URI of the process that generated it (parent process).

The following GET method returns the full XML structure for the step.

// Retrieve the 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 process GET request, as shown in the following example. The URI for each analyte generated is given in the output node in each input-output-map element. For more information on the input-output-map, see View the Inputs and Outputs of a Process/Step.

<prc:process uri="http://yourIPaddress/api/v2/processes/A13-BMJ-100830-24-1475" limsid="A13-BMJ-100830-24-1475">
    <type>API Cookbook Example 1.3</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/HAM754A3PA1?state=15657" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A3PA1?state=15678" limsid="HAM754A3PA1"/>
        <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A3AP10?state=15683" output-type="Analyte" limsid="HAM754A3AP10"/>
    </input-output-map>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/HAM754A1PA1?state=15651" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A1PA1?state=15685" limsid="HAM754A1PA1"/>
        <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A1AP10?state=15680" output-type="Analyte" limsid="HAM754A1AP10"/>
    </input-output-map>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/HAM754A2PA1?state=15656" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A2PA1?state=15686" limsid="HAM754A2PA1"/>
        <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A2AP10?state=15681" output-type="Analyte" limsid="HAM754A2AP10"/>
    </input-output-map>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/HAM754A6PA1?state=15659" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A6PA1?state=15679" limsid="HAM754A6PA1"/>
        <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A6AP10?state=15677" output-type="Analyte" limsid="HAM754A6AP10"/>
    </input-output-map>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/HAM754A4PA1?state=15655" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A4PA1?state=15682" limsid="HAM754A4PA1"/>
        <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A4AP10?state=15687" output-type="Analyte" limsid="HAM754A4AP10"/>
    </input-output-map>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/HAM754A5PA1?state=15652" post-process-uri="http://yourIPaddress/api/v2/artifacts/HAM754A5PA1?state=15684" limsid="HAM754A5PA1"/>
        <output uri="http://yourIPaddress/api/v2/artifacts/HAM754A5AP10?state=15688" output-type="Analyte" limsid="HAM754A5AP10"/>
    </input-output-map>
</prc:process>

Step 2. Request the Individual Resource for the Derived Sample to be Renamed (Analyte Resource)

Each output node has an output-type attribute that is the user-defined type name of the output. You can iterate through each input-output-map and request the output artifact resource for each output of a particular output-type.

In the code example shown below, we filter on output-type = Analyte

// For each input-output-map process.'input-output-map'.each { if (it.output.@'output-type'[0] == "Analyte") { // Retrieve the analyte analyteURI = it.output.@uri[0] analyte = GLSRestApiUtils.httpGET(analyteURI, username, password) // Retrieve the analyte's sample and get its Priority UDF's value sampleURI = analyte.sample.@uri[0] sample = GLSRestApiUtils.httpGET(sampleURI, username, password) samplePriority = sample.'udf:field'.find { it.@name== 'Priority' }?.text() // Rename the analyte nameNode = analyte.name[0]

The output-type attribute is the user-defined name for each of the output types generated by a process. 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 need to GET each artifact in question to discover its type.

Step 3. Request the Sample Resource to Get the Field Value to Use for the Update

From the analyte XML, you can use the submitted sample URI to return the sample that maps to that analyte.

Updating Sample Information shows how to set a sample UDF/global field. To get the value of a sample UDF/global field, use the same method to find the field, and then use the .text() method to get the field value.

The value of the UDF is stored in the variable samplePriority so that it is then available for the renaming step described below.

// For each input-output-map
process.'input-output-map'.each {
    if (it.output.@'output-type'[0] == "Analyte") {
        // Retrieve the analyte
        analyteURI = it.output.@uri[0]
        analyte = GLSRestApiUtils.httpGET(analyteURI, username, password)
 
        // Retrieve the analyte's sample and get its Priority UDF's value
        sampleURI = analyte.sample.@uri[0]
        sample = GLSRestApiUtils.httpGET(sampleURI, username, password)
        samplePriority = sample.'udf:field'.find { it.@name== 'Priority' }?.text()
 
        // Rename the analyte
        nameNode = analyte.name[0]

The variable analyte holds the complete XML structure returned from a GET on the URI in the output node. The variable nameNode references the XML element in that structure that contains the artifact's name. The XML for the analyte named Heart-1.

<art:artifact uri="http://yourIPaddress/api/v2/artifacts/AFF853A43AP2?state=20985" limsid="AFF853A43AP2">
    <name>Heart-1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <parent-process uri="http://yourIPaddress/api/v2/processes/A13-BMJ-100923-24-2182" limsid="A13-BMJ-100923-24-2182"/>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://yourIPaddress/api/v2/containers/27-303" limsid="27-303"/>
        <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/AFF853A43" limsid="AFF853A43"/>
</art:artifact>

Step 4. Update the Analyte Resource with the Name Change

Renaming the derived sample consists of two steps:

1. The name change in the XML.

2. The PUT call to update the analyte resource.

The name change can be performed with the nameNode XML element node defined. The following example shows this element defined.

newName = nameNode.text() + " " + samplePriority
        nameNode.setValue(newName)
        returnNode = GLSRestApiUtils.httpPUT(analyte, analyte.@uri, username, password)
    }
} 

The http PUT command updates the artifact resource using the complete XML representation, including the new name.

Expected Output and Results

After a successful PUT, the results can be reviewed in a web browser at http://yourIPaddress/api/v2/artifacts/TST110A291AP45.

The following XML resource is returned from the PUT command and is stored in returnNode.

<art:artifact uri="http://yourIPaddress/api/v2/artifacts/AFF853A43AP2?state=20985" limsid="AFF853A43AP2">
    <name>Heart-1 sp1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <parent-process uri="http://yourIPaddress/api/v2/processes/A13-BMJ-100923-24-2182" limsid="A13-BMJ-100923-24-2182"/>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://yourIPaddress:/api/v2/containers/27-303" limsid="27-303"/>
        <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/AFF853A43" limsid="AFF853A43"/>
</art:artifact> 

In Clarity LIMS, the Assign Next Steps screen shows the new names for the generated derived samples.

This example shows simple renaming of derived samples based on a submitted sample UDF/global field. However, you can use step names, step UDFs (known as master step fields in Clarity LIMS v5 or later), project information, and so on, to rename derived samples and provide critical information to scientists working in the lab.

Attachments

UpdateAnalyteName.groovy:

The researcher resource holds the personal details for users and clients in Clarity LIMS.

Suppose that you have a separate system that maintains the contact details for your customers and collaborators. You could use this system to synchronize the details for researchers with the details in Clarity LIMS. This example shows how to update the phone number of a researcher using a PUT to the individual researcher resource.

In the Clarity LIMS user interface, the term Labs has been replaced with Accounts. However, the API resource is still called labs and the Collaborations Interface still refers to Labs rather than Accounts. The term Contact has been replaced with Client. The API resource is still called contact.

The LabLink Collaborations Interface is not supported in Clarity LIMS v5 and later. However, because support for this interface is planned for a future release, the Collaborator user role has not been removed.

Prerequisites

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

• A defined client in Clarity LIMS.

• A compatible version of API (v2 r21 or later).

Code Example

For Clarity LIMS v5 and later, in the web interface, the User and Clients screen lists all users and clients in the system.

Step 1. Retrieve the Researcher Resource

In the API, information for a particular researcher can be retrieved within a script using a GET call:

// Retrieve the researcher
Node researcher = GLSRestApiUtils.httpGET(researcherURI, username, password)

In this case, the URI represents the individual researcher resource for the researcher named Sue Erikson. The GET returns an XML representation of the researcher, which populates the groovy node researcher.

The XML representation 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 may inadvertently change data.

The following example shows the XML returned for the Sue Erikson researcher:

<res:researcher uri="http://yourIPaddress/api/v2/researchers/103">
    <first-name>Sue</first-name>
    <last-name>Eriksond</last-name>
    <phone>212-212-2130</phone>
    <fax>212-212-2131</fax>
    <email>serikson@eriksonlabsny.com</email>
    <lab uri="http://yourIPaddress/api/v2/labs/102"/>
    <credentials>
        <username>serikson</username>
        <account-locked>false</account-locked>
        <role roleName="webclient"/>
        <role roleName="administrator"/>
        <role roleName="labtech"/>
    </credentials>
    <initials>SEK</initials>
</res:researcher>

Step 2. Update the Researcher Information

Updating the telephone number requires the following steps:

1. Changing the telephone value in the XML.

2. Using a PUT call to update the the researcher resource.

The new telephone number for Sue Erikson can be set with the phone value within the Groovy researcher node:

newPhoneNumber = '212-212-2133' // Set the new phone number researcher.'phone'[0].setValue(newPhoneNumber) Node returnNode = GLSRestApiUtils.httpPUT(researcher, researcher.@uri, username, password) println GLSRestApiUtils.nodeToXmlString(returnNode)

The PUT command updates the research resource at the specified URI using the complete XML representation, including the new phone number. A successful PUT returns the new XML in the returnNode. An unsuccessful PUT returns the http response code and error message in XML in the returnNode.

Expected Output and Results

For a successful update, the resulting XML can also be reviewed in a web browser via the URI:

http://yourIPaddress/api/researchers/103

<res:researcher uri="http://yourIPaddress/api/v2/researchers/103">
    <first-name>Sue</first-name>
    <last-name>Eriksond</last-name>
    <phone>212-212-2133</phone>
    <fax>212-212-2131</fax>
    <email>serikson@eriksonlabsny.com</email>
    <lab uri="http://yourIPaddress/api/v2/labs/102"/>
    <credentials>
        <username>serikson</username>
        <account-locked>false</account-locked>
        <role roleName="webclient"/>
        <role roleName="administrator"/>
        <role roleName="labtech"/>
    </credentials>
    <initials>SEK</initials>
</res:researcher>

In the LIMS, the updated user list should show the new phone number.

Attachments

UpdateContactInfo.groovy:

Projects contain a collection of samples submitted to the lab for a specific goal or purpose. Often, a script needs information recorded at the project level to do its task. In this simple example, an HTTP GET against a project is shown to obtain information on the project in XML.

Prerequisites

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

• A project exists with name "HTTP Get Project Name with GLS Utils".

• The LIMS ID of the project above, referred to as <project limsid>.

• A compatible version of API (v2 r21 or later).

Code Example

The easiest way to find a project in the system is with its LIMS ID.

• If the project was created in the script (with an HTTP POST) then the LIMS ID is returned as part of the 201 response in the XML.

• If the LIMS ID is not available, but other information uniquely identifies it, you can use the project (list) resource to GET the projects and select the right LIMS ID from the collection.

Working with list resources generally requires the same script logic, so if you need the list of projects to find a specific project then review example. This example demonstrates listing and finding resources for labs, but the same logic applies.

Step 1. Determine the Project's URI

The first step is to determine the URI of the project:

Step 2. Retrieve the Project Resource

Next, use the project LIMS ID to perform an HTTP GET on the resource, and store the response XML in the variable named projectNode:

The projectNode variable can now be used to access XML elements and/or attributes.

Step 3. Obtain the Project Name

To obtain the project's name ask the projectNode for the text representation of the name element:

Expected Output and Results

Attachments

GetProjectName.groovy:

When importing sample data into Clarity LIMS using a spreadsheet, you can specify the reagent labels to be applied during the import process. To do this, you must include the reagent label names in the spreadsheet, in a column named Sample/Reagent Label.

Prerequisites

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

• Reagent types that are configured in Clarity LIMS and are named index 1 through index 6.

• Reagents of type index 1 through index 6 that have been added to Clarity LIMS.

• A compatible version of API (v2 r14 to v2 r24).

Code Example

The following example spreadsheet would import six samples into the system. These samples are Sample-1 through Sample-6 with reagent labels Index 1 through Index 6:

Although not mandatory, it is recommended that you name reagent labels after reagent types using the Index special type. This allows you to relate the reagent label back to its sequence.

Verify with the REST API

If you examine the REST API representation of the samples imported, you are able to verify the following:

• The sample representation shows no indication that reagent labels were applied.

• The sample artifact (the analyte artifact linked from the sample representation) will indicate the label applied via the <reagent-label> element.

The following example shows how an imported sample artifact (Sample-1), with reagent label name applied (Index 1), appears when verified via the REST API:

Imagine that each month the new external accounts with which your facility works are contacted with a Welcome package. In this scenario, it would be helpful to obtain a list of accounts that have been modified in the past month.

NOTE: In Clarity LIMS v2.1 and later, the term Labs was replaced with Accounts. However, the API resource is still called labs.

Prerequisites

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

• Several accounts exist in the system.

• At least one of the accounts was modified after a specific date.

• A compatible version of API (v2 r21 or later).

Code Example

In LIMS v6.2 and later, in the Configuration > User Management page, the Accounts view lists the account resources available.

To obtain a list of all accounts modified after a specific date, you can use a GET request on the accounts list resource and include the ?last-modified filter.

To specify the last month, a Calendar object is instantiated. This Calendar object is initially set to the date and time of the call, rolled back one month, and then passed as a query parameter to the GET call.

The first GET call returns a list of the first 500 labs that meet the date modified criterion specified. The script iterates through each lab element to look at individual lab details. For each lab, a second GET method populates a lab resource XML node with address information.

The REST list resources are paged. Only the first 500 items are returned when you query for a list of items, (eg, http://youripaddress/api/v2/artifacts).

If you cannot filter the list, it is likely that you must iterate through the pages of a list resource to find the items that you are looking for. The URI for the next page of resources is always the last element on the page of a list resource.

Expected Output and Results

In the following example, the XML returned lists three out of the four labs, excluding one due to the date filter:

One of the labs has 'WA' recorded as the state, adding a second printed line to the output:

Attachments

GetLab.groovy:

Demultiplexing is the last step in an indexed sequencing workflow. While the specifics depend on the sequencing instrument and analysis software used, taking pooled samples through sequencing and analysis produces result files/metrics per lane/identifier tag.

These results will likely be in the form of multiple files that you can import back into Clarity LIMS. To do this, you need to set up a configured process that generates process outputs that apply to inputs per reagent label, usually in the form of ResultFile artifacts.

Prerequisites

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

• Configured reagent types named Index 1 through Index 6 in Clarity LIMS.

• Reagents of type Index 1 through Index 6 in Clarity LIMS.

• A compatible version of API (v2 r14 to v2 r24).

Code Example

Create a Demultiplexing Process in the Clarity LIMS Operations Interface

Configure a process that generates ResultFile with process outputs that apply to inputs per reagent label. It is recommended to name your outputs in a way that clearly identifies the samples to which they correspond (eg, Results for {SubmittedSampleName}-{AppliedReagentLabels}).

Demultiplexing in the User Interface

Running the demultiplexing process on a labeled pooled input produces a process run in the Operations Interface, similar to the one illustrated below.

Note the following:

• There were three reagent labels in the input analyte (sample) artifact. As a result, three outputs were generated (the process was configured to produce one output result file per label per input).

• The names of the outputs of the demultiplexing process expose the original sample name and label.

• The Operations Interface shows details of the genealogy from the downstream result file all the way back to the original sample.

While reagent labels are not explicitly exposed in the Clarity LIMS client user interface, genealogy views in the Operations Interface are aware of reagent labels and will show the true sample inheritance. As noted above, you can use the {AppliedReagentLabels} output naming variable to show the reagent labels applied to each artifact in the user interface.

Demultiplexing in the API with a Process POST

The key difference is that when executing a demultiplexing process through the REST API, outputs per reagent label are automatically generated from the inputs provided. You do not need to explicitly specify them.

For example, when running the demultiplexing process configured against a single (pooled) sample, you could post a process execution representation like this:

The input-output-map only refers to inputs, not outputs, because the demultiplexing process is configured to exclusively produce outputs per reagent label.

If your process produces other outputs, such as shared or per-input outputs, you must explicitly specify input-output-maps for them.

Verify with the REST API

Irrespective of whether you use the user interface or the REST API to run the demultiplexing process, the REST API representation for the process looks something like this:

For each input with reagent labels, one output was created per reagent label.

In the example, the process ran on one pooled input, and produced three outputs (the pooled input included three reagent labels). The following example shows one of the demultiplexed result file outputs:

The output contains only one reagent label, and relates only to the sample that was tagged with the same reagent label. Compare this to the case of a pooled artifact, which has several labels and relates to several samples. This level of traceability (from a demultiplexed output back to its specific original sample) is only possible because the artifacts were labeled before they were pooled.

The artifact name generated by the demultiplexing process output name pattern is ("Results for SAM-3 - Index 3"). You can use the {SubmittedSampleName} naming variable to show true ancestors, and the {AppliedReagentLabels} to show any reagent labels applied to an output.

• About UDFs/Custom Fields and UDTs

• Performing Post-Step Calculations with Custom Fields/UDFs

Reagent labels are artifact resource elements and can be applied using a PUT. To apply a reagent label to an artifact using REST, the following steps are required:

1. GET the artifact representation.

2. Insert a reagent-label element with the intended label name.

3. PUT the modified artifact representation back.

You can apply the reagent label to the original analyte (sample) artifact or to a downstream sample or result file.

Prerequisites

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

• Reagent types that are configured in Clarity LIMS and are named index 1 through index 6.

• Reagents of type index 1 through index 6 that have been added to Clarity LIMS.

• A compatible version of API (v2 r14 to v2 r24).

Code Example

In this example, you can adjust the following code:

def toLabel = GLSRestApiUtils.httpGET(artifactToLabelURI, username, password)
println '*** Before labeling'
println GLSRestApiUtils.nodeToXmlString(toLabel)
println
 
new Node(toLabel, 'reagent-label', [name: 'Index 1'])
println '*** After labeling'
println GLSRestApiUtils.nodeToXmlString(toLabel)
println
 
GLSRestApiUtils.httpPUT(toLabel, toLabel.@uri, username, password)

By inserting the reagent-label element, you end up with the following code.

*** Before labeling
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<art:artifact xmlns:udf="http://genologics.com/ri/userdefined"
    xmlns:file="http://genologics.com/ri/file" xmlns:art="http://genologics.com/ri/artifact"
    uri="http://yourIPaddress/api/v2/artifacts/RCY1A97PA1?state=301" limsid="RCY1A97PA1">
    <name>Sample-1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://yourIPaddress/api/v2/containers/27-12" limsid="27-12" />
        <value>A:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/RCY1A97" limsid="RCY1A97" />
</art:artifact>
 
*** After labeling
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<art:artifact xmlns:udf="http://genologics.com/ri/userdefined"
    xmlns:file="http://genologics.com/ri/file" xmlns:art="http://genologics.com/ri/artifact"
    uri="http://yourIPaddress/api/v2/artifacts/RCY1A97PA1?state=301" limsid="RCY1A97PA1">
    <name>Sample-1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://yourIPaddress/api/v2/containers/27-12" limsid="27-12" />
        <value>A:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/RCY1A97" limsid="RCY1A97" />
    <reagent-label name="Index 1" />
</art:artifact>

Although it is not mandatory, it is recommended that you name reagent labels after reagent types using the Index special type. This allows you to relate the reagent label back to its sequence.

In the BaseSpace Clarity LIMS web interface, in the Custom Fields configuration screen, administrators can add user-defined information by adding custom fields (global fields or master step fields). At this time, user-defined types (UDTs) are only supported in the API.

Use these custom fields to configure storage locations for data that annotates project, submitted sample, step, derived sample, measurement, and file information recorded in a workflow.

All XML element attributes and values are text. Before using the value in a script, you may want to convert to a strongly-typed variable such as a number or date type.

For details on the formats used in XML, see Working with User-Defined Fields (UDF) and Types (UDT).

When working with multiplexing, you can do the following:

• Filter Processes by Date and Type

• Find Terminal Processes/Steps

• Run a Process/Step

• Update UDF/Custom Field Information for a Process/Step

• Work with the Steps Pooling Endpoint

The powerful batch resources included in the Clarity LIMS Rapid Scripting API significantly increase the speed of script execution by allowing batch operations on samples and containers. These resources are useful when working with multiple samples and containers in high throughput labs.

The following simple example uses batch resources to move samples from one workflow queue into another queue.

It is useful to review the Work with Batch Resources.

Use a batch retrieve request to find all the artifacts in an artifact group, and then use a batch update request to move those artifacts into another artifact group.

The following steps are required:

1. Find all the artifacts that are in a particular artifact group.

2. Use the artifacts.batch.retrieve (list) resource to retrieve the details for all the artifacts.

3. Use the artifacts.batch.update (list) resource to update the artifacts and move them into a different artifact group, posting them back as a batch.

NOTE: The only HTTP method for batch resources is POST.

Prerequisites

Before you follow the steps, make sure that you have the following items:

• Clarity LIMS contains a collection of samples (artifacts) residing in the same workflow queue (artifact group)

• A second queue exists into which you can move the collection of samples

• A compatible version of API (v2 r21 and later).

Step 1. Find All of the Samples in a Workflow Queue

To find the samples (artifacts) in a workflow queue (artifact group), use the following request, editing the server details and artifact group name to match those in your system:

http://your-server-ip/api/v2/artifacts?artifactgroup=my_queue

This request returns a list of URI links for all artifacts in the artifact group specified. In our example, the my_queue queue contains three artifacts:

<art:artifacts xmlns:art="http://genologics.com/ri/artifact">
  <artifact limsid="ADM1A1PA1" uri="http://your-server-ip/api/v2/artifacts/ADM1A1PA1"/>
  <artifact limsid="ADM1A2PA1" uri="http://your-server-ip/api/v2/artifacts/ADM1A2PA1"/>
  <artifact limsid="ADM1A3PA1" uri="http://your-server-ip/api/v2/artifacts/ADM1A3PA1"/>
</art:artifacts>

Step 2. Retrieve Sample Details

To retrieve the detailed XML for all of the artifacts, use a <links> tag to post the set of URI links to the server using a batch retrieve request:

<ri:links xmlns:ri="http://genologics.com/ri">
  <link uri="http://your-server-ip/api/v2/artifacts/ADM1A1PA1" rel="artifacts"/>
  <link uri="http://your-server-ip/api/v2/artifacts/ADM1A2PA1" rel="artifacts"/>
  <link uri="http://your-server-ip/api/v2/artifacts/ADM1A3PA1" rel="artifacts"/>
</ri:links>

http://your-server-ip/api/v2/artifacts/batch/retrieve

This returns the detailed XML for each of the artifacts in the batch:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<art:details xmlns:udf="http://genologics.com/ri/userdefined" 
xmlns:file="http://genologics.com/ri/file" xmlns:art="http://genologics.com/ri/artifact">
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A1PA1?state=21" limsid="ADM1A1PA1">
    <name>base-1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-10" limsid="27-10"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A1" limsid="ADM1A1"/>
    <artifact-group name="my_queue" uri="http://your-server-ip/api/v2/artifactgroups/1"/>
  </art:artifact>
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A2PA1?state=42" limsid="ADM1A2PA1">
    <name>base-2</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-11" limsid="27-11"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A2" limsid="ADM1A2"/>
    <artifact-group name="my_queue" uri="http://your-server-ip/api/v2/artifactgroups/1"/>
  </art:artifact>
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A3PA1?state=12" limsid="ADM1A3PA1">
    <name>base-3</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-12" limsid="27-12"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A3" limsid="ADM1A3"/>
    <artifact-group name="my_queue" uri="http://your-server-ip/api/v2/artifactgroups/1"/>
  </art:artifact>
</art:details>

The XML returned includes the artifact group name and URI:

<artifact-group name="my_queue" uri="http://your-server-ip/api/v2/artifactgroups/1"/>

Step 3. Move All Samples into a Different Queue

To move the artifacts into another queue, simply update the artifact-group name and URI values:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<art:details xmlns:udf="http://genologics.com/ri/userdefined" xmlns:file="http://genologics.com/ri/file" xmlns:art="http://genologics.com/ri/artifact">
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A1PA1?state=21" limsid="ADM1A1PA1">
    <name>base-1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-10" limsid="27-10"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A1" limsid="ADM1A1"/>
    <artifact-group name="new_queue"  uri="http://your-server-ip/api/v2/artifactgroups/2"/>
  </art:artifact>
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A2PA1?state=42" limsid="ADM1A2PA1">
    <name>base-2</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-11" limsid="27-11"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A2" limsid="ADM1A2"/>
    <artifact-group name="new_queue"  uri="http://your-server-ip/api/v2/artifactgroups/2"/>
  </art:artifact>
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A3PA1?state=12" limsid="ADM1A3PA1">
    <name>base-3</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-12" limsid="27-12"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A3" limsid="ADM1A3"/>
    <artifact-group name="new_queue"  uri="http://your-server-ip/api/v2/artifactgroups/2"/>
  </art:artifact>
</art:details>

Finally, post the XML back to the server using a batch update request:

http://your-server-ip/api/v2/artifacts/batch/update

For a general overview of batch resources, refer to Introduction to Batch Resources.

When working with batch resources, you can do the following:

• Introduction to Batch Resources

• Update UDF/Custom Field Information with Batch Operations

• Retrieve Multiple Entities with a Single API Interaction

• Select the Optimal Batch Size

Compatibility: API version 2 revision 21 and later

Important measurements and values are often calculated from other values. Instead of performing these calculations by hand, and then manually entering them into the LIMS (thereby increasing the probability of error), you can develop scripts to perform these calculations and update the data accordingly.

This example demonstrates the use of scripts and user-defined fields (UDFs) / custom fields for information retrieval and recording of calculation results in the LIMS.

NOTE:

• Information about a step is stored in the process resource in the API.

• Information about a derived sample is stored in the analyte resource in the API. This resource is used as the input and output of a step, and also used to record specific details from lab processing.

• As of BaseSpace Clarity LIMS v5.0, the term user-defined field (UDF) has been replaced with custom field in the user interface. However, the API resource is still called udf.

Prerequisites

Clarity LIMS v5 and later:

1. You have defined the following custom global fields on the Derived Sample object:

   • Concentration

   • Size (bp)

   • Conc. nM

2. You have set the three fields configured in step 1 to display in the Sample table of the Record Details screen.

3. You have configured a Calc. Prep step to apply Concentration, Size (bp) to generated derived samples.

   • You have run the Calc. Prep step and it has generated derived samples.

   • You have input values for the Calculation and Size (bp) fields.

4. You have configured a Calculation step to apply Conc. nM to generated derived samples.

   • You have run the Calculation step - with the derived samples generated by the Calc. Prep step as inputs, and it has generated derived samples.