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:

• Automation Trigger Configuration

• Process Execution with EPP/Automation Support

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

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.

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.

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.

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:

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

• Adding Samples to the System

• Renaming Samples

• Assigning Samples to Workflows

• Updating Sample Information

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

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:

// Retrieve the sample
sampleURI = "http://${hostname}/api/v2/samples/${sampleID}"
sample = GLSRestApiUtils.httpGET(sampleURI, username, password) 

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.

<smp:sample uri="http://yourIPaddress/api/v2/samples/ADM201A1" limsid="ADM201A1">
    <name>DNA sample-1</name>
    <date-received>2017-04-18</date-received>
    <project uri="http://yourIPaddress/api/v2/projects/ADM201" limsid="ADM201"/>
    <artifact uri="http://yourIPaddress/api/v2/artifacts/ADM201A1PA1?state=2995" limsid="ADM201A1PA1"/>
    <udf:field type="String" name="Sample Type">DNA</udf:field>
    <udf:field type="String" name="Phenotypic Information">Human</udf:field>
    <udf:field type="String" name="Priority">High</udf:field>
</smp:sample>

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.

// Update the sample's Priority UDF value
sample = GLSRestApiUtils.setUdfValue(sample, 'Priority', 'Critical')
returnNode = GLSRestApiUtils.httpPUT(sample, sample.@uri, username, password)
println GLSRestApiUtils.nodeToXmlString(returnNode)

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:

<smp:sample uri="http://yourIPaddress/api/v2/samples/ADM201A1" limsid="ADM201A1">
    <name>DNA sample-1</name>
    <date-received>2017-04-18</date-received>
    <project uri="http://yourIPaddress/api/v2/projects/ADM201" limsid="ADM201"/>
    <artifact uri="http://yourIPaddress/api/v2/artifacts/ADM503A1PA1?state=2995" limsid="ADM201A1PA1"/>
    <udf:field type="String" name="Sample Type">DNA</udf:field>
    <udf:field type="String" name="Phenotypic Information">Human</udf:field>
    <udf:field type="String" name="Priority">Critical</udf:field>
</smp:sample>

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

Attachments

UpdateSampleUDF.groovy:

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

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

The example Work with Processes/Steps is similar to this example. The differences are that this example has minimal input/output and posts a reference to a pre-defined EPP process-parameter.

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

In addition, this example requires a container in which to store the results of the process execution. An example of how to do this is included in the Groovy script under Process Execution with EPP/Automation Support.

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

// Create a new container using the StreamingMarkupBuilder
def containerDoc = builder.bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(con: 'http://genologics.com/ri/container')
    mkp.declareNamespace(udf: 'http://genologics.com/ri/userdefined')
    'con:container'{
        'name'("HiSEQ POST${randomNumGen.nextInt()}")
        'type'(uri:"http://${hostname}/api/v2/containertypes/1", name:"96 well plate")
    }
}
// Post the new container to the API
containerNode = GLSRestApiUtils.xmlStringToNode(containerDoc.toString())
returnNode = GLSRestApiUtils.httpPOST(containerNode, containersListURI, username, password)
container96WellsURI = returnNode.@uri

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.

// Create the required URIs
processListURI = "http://${hostname}/api/v2/processes"
researcherURI = "http://${hostname}/api/v2/researchers/1"
analyteURI = "http://${hostname}/api/v2/artifacts/${inputAnalyeLIMSID}"
 
// Retrieve the Process-Type
processParamName = 'TestProcessParam'
processTypeNode = GLSRestApiUtils.httpGET(processTypeURI, username, password)
 
// Create a new process using the StreamingMarkupBuilder
def processDoc = new StreamingMarkupBuilder().bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(prx:'http://genologics.com/ri/processexecution')
    'prx:process'{
        'type'(processTypeNode.'@name')
        'technician'(uri:researcherURI)
        'input-output-map' {
            'input'(uri:analyteURI)
            'output'(type:'Analyte') {
                'location' {
                    'container'(uri:container96WellsURI)
                    'value'("A:1")
                }
            }
        }
        'input-output-map'(shared:'true') {
            'input'(uri:analyteURI)
            'output'(type:'ResultFile')
        }
        'process-parameter'(name:processParamName)
    }
}
// Post the process to the API
unresolvedProcessNode = GLSRestApiUtils.xmlStringToNode(processDoc.toString())
returnNode = GLSRestApiUtils.httpPOST(unresolvedProcessNode, "${processListURI}", username, password)
println GLSRestApiUtils.nodeToXmlString(returnNode)

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.

<prc:process uri="http://localhost/api/v2/processes/ROB-QSK-110525-24-109084" limsid="ROB-QSK-110525-24-109084">
  <type uri="http://localhost/api/v2/processtypes/1979">robtype1</type>
  <date-run>2014-11-14</date-run>
  <technician uri="http://localhost/api/v2/researchers/11651">
    <first-name>John-Luck</first-name>
    <last-name> Pikkard </last-name>
  </technician>
  <input-output-map>
    <input post-process-uri="http://localhost/api/v2/artifacts/LIT2693A1SAM1?state=8564" uri="http://localhost/api/v2/artifacts/LIT2693A1SAM1?state=8562" limsid="LIT2693A1SAM1"/>
    <output uri="http://localhost/api/v2/artifacts/LIT2693A1RO10?state=8563" output-type="Analyte" limsid="LIT2693A1RO10"/>
  </input-output-map>
  <input-output-map>
    <input post-process-uri="http://localhost/api/v2/artifacts/ADM793A1PA1?state=3896" uri="http://localhost/api/v2/artifacts/ADM793A1PA1?state=3893" limsid="ADM793A1PA1"/>
    <output uri="http://localhost/api/v2/artifacts/ADM793A1RO2?state=3894" output-generation-type="PerAllInputs" output-type="ResultFile" limsid="ADM793A1RO2"/>
  </input-output-map>
  <process-parameter name="TestProcessParam"/>
</prc:process> 

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:

<exc:exception xmlns:exc="http://genologics.com/ri/exception">
  <message>The process type named 'HiSEQ POST' cannot produce the following types of shared outputs: 'ResultFile'.</message>
</exc:exception>

Attachments

ExecuteProcessWithEPP.groovy:

autocomplete-process.py:

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

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:

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:

// Determine the specified container's URI and retrieve it
containerURI = "http://${hostname}/api/v2/containers/${containerLIMSID}"
container = GLSRestApiUtils.httpGET(containerURI, username, password)

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.

<con:container uri="http://yourIPaddress/api/v2/containers/27-1259" limsid="27-1259">
    <name>PC0006</name>
    <type uri="http://yourIPaddress/api/v2/containertypes/1" name="96 well plate"/>
    <occupied-wells>96</occupied-wells>
    <placement uri="http://yourIPaddress/api/v2/artifacts/HAM751A495PA1" limsid="HAM751A495PA1">
        <value>B:3</value>
    </placement>
    <placement uri="http://yourIPaddress/api/v2/artifacts/HAM751A496PA1" limsid="HAM751A496PA1">
        <value>B:4</value>
    </placement>
    <placement uri="http://yourIPaddress/api/v2/artifacts/HAM751A493PA1" limsid="HAM751A493PA1">
        <value>B:1</value>
    </placement>
    <placement uri="http://yourIPaddress/api/v2/artifacts/HAM751A497PA1" limsid="HAM751A497PA1">
        <value>B:5</value>
    </placement>
</con: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:

// Print the artifact that is located at the specified placement
contents = container.placement.find { it.value.text() == targetPlacement }
artifactURI = contents?.@uri
println artifactURI 

Expected Output and Results

Running the script in a console produces the artifact at

http://yourIPaddress/api/v2/artifacts/HAM751A496PA1

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.

// Determine the containers list URI
String containersListURI = "http://${hostname}/api/v2/containers"
def builder = new StreamingMarkupBuilder()
builder.encoding = "UTF-8"
 
// Create a new container using the Markup Builder
def containerDoc = builder.bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(con: 'http://genologics.com/ri/container')
    mkp.declareNamespace(udf: 'http://genologics.com/ri/userdefined')
    'con:container'{
        'name'(containerName)
        'type'(uri:"http://${hostname}/api/v2/containertypes/1", name:"96 well plate")
    }
    }

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.

// Post the new container to the API
def containerNode = GLSRestApiUtils.xmlStringToNode(containerDoc.toString())
containerNode = GLSRestApiUtils.httpPOST(containerNode, containersListURI, username, password)
println GLSRestApiUtils.nodeToXmlString(containerNode)

Expected Output and Results

The XML for the new container is as follows.

<con:container xmlns:con="http://genologics.com/ri/container">
  <name>containerPOSTScript</name>
  <type uri="http://yourIPaddress/api/v2/containertypes/1" name="96 well plate"/>
</con:container> 

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

<con:containers>
    <container uri="http://yourIPaddress/api/v2/containers/27-1858" limsid="27-1858">
        <name>27-1858</name>
    </container>
    <container uri="http://yourIPaddress/api/v2/containers/27-2182" limsid="27-2182">
        <name>27-2182-1</name>
    </container>
    <container uri="http://yourIPaddress/api/v2/containers/27-2202" limsid="27-2202">
        <name>testingContainerPOST</name>
    </container>
</con:containers> 

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:

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:

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:

// Retrieve the sample
sampleURI = "http://${hostname}/api/v2/samples/${sampleLIMSID}"
sample = GLSRestApiUtils.httpGET(sampleURI, username, password)

The variable sample now holds the complete XML structure returned from the sampleURI.

The following example shows the XML for the sample, with the name element on the second line. In this particular case, the Clarity LIMS configuration has expanded the sample with 18 custom fields that provide sample information.

<smp:sample uri="http://yourIPaddress/api/v2/samples/HAM754A1" limsid="HAM754A1">
<name>Colon-1</name>
<date-received>2010-03-25</date-received>
<project uri="http://yourIPaddress/api/v2/projects/HAM754" limsid="HAM754"/>
<artifact uri="http://yourIPaddress/api/v2/artifacts/HAM754A1PA1?state=11822" limsid="HAM754A1PA1"/>
<udf:field type="String" name="Organism">Homo sapiens</udf:field>
<udf:field type="String" name="Gender">Unknown</udf:field>
<udf:field type="Numeric" name="Concentration (ng/uL)">200.0</udf:field>
<udf:field type="Numeric" name="Total Volume (uL)">50</udf:field>
<udf:field type="String" name="Investigator Sample Name">F3_5016</udf:field>
<udf:field type="String" name="Sample Group Phase">Pick Plate</udf:field>
<udf:field type="String" name="Date of Sample Group Phase">2010-05-19</udf:field>
<udf:field type="String" name="Sample QC">FAILED</udf:field>
<udf:field type="String" name="Sample QC Date">2010-04-12</udf:field>
<udf:field type="String" name="Sample Picked">Yes</udf:field>
<udf:field type="String" name="Sample Latest Pick Date">2010-05-19</udf:field>
<udf:field type="Numeric" name="Sample Picked Iteration">3</udf:field>
<udf:field type="String" name="Sample Library Requeue Status"/>
<udf:field type="String" name="Sample Library Requeue Date">2010-05-19</udf:field>
<udf:field type="Numeric" name="Paired End Read Sequencing Lane Iteration">2</udf:field>
<udf:field type="String" name="Paired End Read Sequencing Last Date">2010-01-15</udf:field>
<udf:field type="String" name="Investigator Last Name">Hershberger</udf:field>
<udf:field type="String" name="Cohort">Not Applicable</udf:field>
</smp:sample>

Step 2. Rename the Sample

Renaming the sample consists of the following:

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.

// Rename the sample
nameNode = sample.name[0]
nameNode.setValue(newName)
returnNode = GLSRestApiUtils.httpPUT(sample, sample.@uri, username, password)

The PUT method updates the individual sample resource using the complete XML representation, which includes the new name. Such complete updates provide a simple interaction between client and server.

Expected Output and Results

The updated sample view displays the new name. You can also view the results in a web browser via the URI at

http://<YourIPaddress>/api/v2/samples/<SampleLIMSID>

<smp:sample uri="http://yourIPaddress/api/v2/samples/HAM754A1" limsid="HAM754A1">
<name>Colon-1 Updated</name>
<date-received>2010-03-25</date-received>
<project uri="http://yourIPaddress/api/v2/projects/HAM754" limsid="HAM754"/>
<artifact uri="http://yourIPaddress/api/v2/artifacts/HAM754A1PA1?state=11822" limsid="HAM754A1PA1"/>
<udf:field type="String" name="Organism">Homo sapiens</udf:field>
<udf:field type="String" name="Gender">Unknown</udf:field>
<udf:field type="Numeric" name="Concentration (ng/uL)">200.0</udf:field>
<udf:field type="Numeric" name="Total Volume (uL)">50</udf:field>
<udf:field type="String" name="Investigator Sample Name">F3_5016</udf:field>
<udf:field type="String" name="Sample Group Phase">Pick Plate</udf:field>
<udf:field type="String" name="Date of Sample Group Phase">2010-05-19</udf:field>
<udf:field type="String" name="Sample QC">FAILED</udf:field>
<udf:field type="String" name="Sample QC Date">2010-04-12</udf:field>
<udf:field type="String" name="Sample Picked">Yes</udf:field>
<udf:field type="String" name="Sample Latest Pick Date">2010-05-19</udf:field>
<udf:field type="Numeric" name="Sample Picked Iteration">3</udf:field>
<udf:field type="String" name="Sample Library Requeue Status"/>
<udf:field type="String" name="Sample Library Requeue Date">2010-05-19</udf:field>
<udf:field type="Numeric" name="Paired End Read Sequencing Lane Iteration">2</udf:field>
<udf:field type="String" name="Paired End Read Sequencing Last Date">2010-01-15</udf:field>
<udf:field type="String" name="Investigator Last Name">Hershberger</udf:field>
<udf:field type="String" name="Cohort">Not Applicable</udf:field>
</smp:sample>

Attachments

RenamingSample.groovy:

When working with containers, you can do the following:

• Remove Samples from Workflows

• Requeue Samples

• Rearray Samples

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

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:

def getSampleNodes(sampleList, hostname, username, password){
    sampleURIList = sampleList.collect{"${hostname}v2/artifacts/${it}"}
    return sampleNodeList = GLSRestApiUtils.batchGET(sampleURIList, username, password)
} 

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

A sample can be associated with one or many workflows, and each derived sample has a list of the workflow-stages to which it is assigned. Making a GET call on each workflow-stage URI retrieves its XML representation, from which the workflow URI can be acquired and added to a list. The getWorkflowURIs function calls for each sample node included in the list (eg, sampleURIList, username, and password from #step1).

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.

def getWorkflowURIs(sampleNode, username, password){
    return sampleNode.'workflow-stages'?.'workflow-stage'.collect\
          {GLSRestApiUtils.httpGET(it.@uri, username, password).workflow.@uri}
} 

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.

def unassignSamplesFromWorkflows(sampleNodeList, username, password){
    def builder = new StreamingMarkupBuilder()
    builder.encoding = "UTF-8"
    def unassignSamplesXML = builder.bind{
        mkp.xmlDeclaration()
        mkp.declareNamespace(rt: 'http://genologics.com/ri/routing')
         'rt:routing' {
             //Dynamically build XML using a for loop for each sampleNode
             sampleNodeList.each{ sampleNode ->
                 //Generates the URI list for each sample
                 workflowUriList = getWorkflowURIs(sampleNode, username, password)
                 workflowUriList?.each{
                     'unassign'('workflow-uri': it){
                         'artifact'(uri: sampleNode.@uri)
                     }
                 }
             }
         }
     }
     return GLSRestApiUtils.xmlStringToNode(unassignSamplesXML.toString())
}

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:

unassignSampleNode = unassignSamplesFromWorkflows(sampleNodeList, username, password)
//Try the post
try{
    unassignSampleNode = GLSRestApiUtils.httpPOST(unassignSampleNode, unassignmentURI, username, password)
} 

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:

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:

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:

def getSampleNodes(sampleList, hostname, username, password){
    sampleURIList = sampleList.collect{"${hostname}v2/artifacts/${it}"}
    return GLSRestApiUtils.batchGET(sampleURIList, username, password)
}

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:

encodedWorkflowName = java.net.URLEncoder.encode(workflowName, "UTF-8")
try {
    workflowURI = GLSRestApiUtils.httpGET\
        ("${hostname}v2/configuration/workflows?name=${encodedWorkflowName}", username, password).workflow.@uri[0]
if (!workflowURI) {
        throw new Exception()
    }
} catch (Exception e) {
    println "Unable to find workflow: " + workflowName
    System.exit(-1)
}

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.

def getStageURI (workflowURI, stageName, username, password) {
    def stageURI
    GLSRestApiUtils.httpGET(workflowURI, username, password).stages.stage.find {
        if (it.@name.toString().equals(stageName)) {
            stageURI = it.@uri
            return true
        }
    }
    if (stageURI) {
        return stageURI
    } 

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.

def canRequeue(nodeList, stageURI){
    def Set conditions = ["REMOVED", "FAILED", "COMPLETE", "SKIPPED"]
    def requeueList = []
    def lastStageRun
    nodeList.each{ sampleNode ->
        sampleNode.'workflow-stages'?.'workflow-stage'.each {
            if (it.@uri.toString().equals(stageURI)) {
                lastStageRun = it
            }
        }
        if (conditions.contains(lastStageRun?.@status.toString())) {
            requeueList.add(sampleNode)
        } else {
            println "Sample: " + sampleNode.@limsid.toString() + " cannot be queued to stage " +  stageName
            System.exit(-1)
        }
    }
    return requeueList
}

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.

def getCurrentStageURI(sampleNode, workflowURI) {
    def lastStageRun
    sampleNode.'workflow-stages'?.'workflow-stage'.each {
        stageWorkflowURI = GLSRestApiUtils.httpGET(it.@uri, username, password).'workflow'.@uri[0]
        if (stageWorkflowURI.toString().equals(workflowURI.toString())) {
            lastStageRun = it
        }
    }
    return (lastStageRun.@status.toString().equals('QUEUED')) ? lastStageRun.@uri.toString() : null
} 

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:

def assignmentXML =  builder.bind {
        mkp.xmlDeclaration()
        mkp.declareNamespace(rt: 'http://genologics.com/ri/routing')
        'rt:routing' {
            requeueList.each { sampleNode ->
                currentURI = getCurrentStageURI(sampleNode, workflowURI)
                if (currentURI) {
                    'unassign'('stage-uri': currentURI) {
                        'artifact'(uri: sampleNode.@uri)
                    }
                }
                'assign'('stage-uri': stageURI) {
                    'artifact'(uri: sampleNode.@uri)
                }
            }
        }
    }
    return GLSRestApiUtils.xmlStringToNode(assignmentXML.toString())
}

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:

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:

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:

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

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

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:

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.

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:

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.

Attachments

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

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.

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.

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:

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

Attachments

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

// Determine project list's URI
String projectsListURI = "http://${hostname}/api/v2/projects"
 
def builder = new StreamingMarkupBuilder()
builder.encoding = "UTF-8"
openDate = "2017-08-24"
 
// Build a new project using Markup Builder
def projectDoc = builder.bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(prj: 'http://genologics.com/ri/project')
    mkp.declareNamespace(udf: 'http://genologics.com/ri/userdefined')
    'prj:project'{
        'name'(projectName)
        'open-date'(openDate)
        'researcher'(uri:"http://${hostname}/api/v2/researchers/1")
        'udf:field'(name:"Objective","To test httpPOST")
    }
}
// Post the new project
def projectNode = GLSRestApiUtils.xmlStringToNode(projectDoc.toString())
projectNode = GLSRestApiUtils.httpPOST(projectNode, projectsListURI, username, password)
println GLSRestApiUtils.nodeToXmlString(projectNode)

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

<prj:project xmlns:prj="http://genologics.com/ri/project" uri="http://yourIPaddress/api/v2/projects/WOR512" limsid="WOR512">
  <name>httpPOST Project then remove nodes</name>
  <open-date>2017-08-24</open-date>
  <researcher uri="http://yourIPaddress/api/v2/researchers/1"/>
  <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="String" name="Objective">To test httpPOST</udf:field>
  <permissions uri="http://yourIPaddress/api/v2/permissions/projects/WOR512"/>
</prj:project>

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 projectNode is parentNode, remove the child udf:field
projectNode?.children()?.remove(projectNode.'udf:field'[0])
 
// Print the node that will be updated
println GLSRestApiUtils.nodeToXmlString(projectNode)

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:

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.

// Determine project list's URI
String projectsListURI = "http://${hostname}/api/v2/projects"
 
def builder = new StreamingMarkupBuilder()
builder.encoding = "UTF-8"
openDate = "2017-08-22"
 
// Build a new project using Markup Builder
def projectDoc = builder.bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(prj: 'http://genologics.com/ri/project')
    mkp.declareNamespace(udf: 'http://genologics.com/ri/userdefined')
    'prj:project'{
        'name'(projectName)
        'open-date'(openDate)
        'researcher'(uri:"http://${hostname}/api/v2/researchers/1")
        'udf:field'(name:"Objective", "To test httpPOST")
    }
}

• UDFs / custom fields must be configured in the Clarity LIMS before they can be set or updated using the API. You can find a list of the fields defined for a project in your system by using the resource: http://youripaddress/api/v2/configuration/udfs and looking for those with an attach-to-name of '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:

// Turn the markup into a node and post it to the API
def projectNode = GLSRestApiUtils.xmlStringToNode(projectDoc.toString())
projectNode = GLSRestApiUtils.httpPOST(projectNode, projectsListURI, username, password)
println GLSRestApiUtils.nodeToXmlString(projectNode)

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:

<prj:project uri="http://yourIPaddress/api/v2/projects/ADM1101" limsid="ADM1101">
    <name>httpPOST Project</name>
    <open-date>2017-08-22</open-date>
    <researcher uri="http://yourIPaddress/api/v2/researchers/1"/>
    <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="String" name="Objective">To test httpPOST</udf:field>
        <permissions uri="http://yourIPaddress/api/v2/permissions/projects/ADM1101"/>
</prj:project>

Attachments

PostProject.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 Find an Account Registered in the System 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:

// Determine the project's URI
URI projectURI = new URI("http://${hostname}/api/v2/projects/${projectID}")

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:

// Get a single Project by limsid
projectNode = GLSRestApiUtils.httpGET(projectURI.toString(), username, password)
println GLSRestApiUtils.nodeToXmlString(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:

// Obtain the name
println("Project ID : ${projectNode.name.text()}")

Expected Output and Results

<prj:project xmlns:prj="http://genologics.com/ri/project" uri="http://yourIpAddress/api/v2/projects/LUN3" limsid="LUN3">
  <name>HTTP Get Project Name with GLS Utils</name>
  <open-date>2017-05-31</open-date>
  <researcher uri="http://yourIpAddress/api/v2/researchers/1"/>
  <permissions uri="http://yourIpAddress/api/v2/permissions/projects/LUN3"/>
</prj:project>

Attachments

GetProjectName.groovy:

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:

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:

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:

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:

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

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

Attachments

UpdateContactInfo.groovy:

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

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

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

Attachments

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

Executing a demultiplexing process by issuing a process POST via the REST API is similar to the typical process execution found in Run a Process/Step.

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:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<prx:process xmlns:prx="http://genologics.com/ri/processexecution">
    <type>Demultiplex</type>
    <technician uri="http://yourIPaddress/api/v2/researchers/4"/>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/2-424"/>
    </input-output-map>
</prx:process>

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:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<prc:process xmlns:udf="http://genologics.com/ri/userdefined"
    xmlns:file="http://genologics.com/ri/file" xmlns:prc="http://genologics.com/ri/process"
    uri="http://yourIPaddress/api/v2/processes/DMX-RCX-110816-24-95"
    limsid="DMX-RCX-110816-24-95">
    <type uri="http://yourIPaddress/api/v2/processtypes/38">Demultiplex</type>
    <date-run>2011-08-12</date-run>
    <technician uri="http://yourIPaddress/api/v2/researchers/4">
        <first-name>RC</first-name>
        <last-name>RC</last-name>
    </technician>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/2-424?state=335"
            uri="http://yourIPaddress/api/v2/artifacts/2-424?state=324" limsid="2-424">
            <parent-process
                uri="http://yourIPaddress/api/v2/processes/PSA-RCX-110812-122-221"
                limsid="PSA-RCX-110812-122-221" />
        </input>
        <output uri="http://yourIPaddress/api/v2/artifacts/92-163?state=339"
            output-generation-type="PerReagentLabel" output-type="ResultFile"
            limsid="92-163" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/2-424?state=335"
            uri="http://yourIPaddress/api/v2/artifacts/2-424?state=324" limsid="2-424">
            <parent-process
                uri="http://yourIPaddress/api/v2/processes/PSA-RCX-110812-122-221"
                limsid="PSA-RCX-110812-122-221" />
        </input>
        <output uri="http://yourIPaddress/api/v2/artifacts/92-164?state=336"
            output-generation-type="PerReagentLabel" output-type="ResultFile"
            limsid="92-164" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/2-424?state=335"
            uri="http://yourIPaddres/api/v2/artifacts/2-424?state=324" limsid="2-424">
            <parent-process
                uri="http://yourIPaddress/api/v2/processes/PSA-RCX-110812-122-221"
                limsid="PSA-RCX-110812-122-221" />
        </input>
        <output uri="http://yourIPaddress/api/v2/artifacts/92-162?state=338"
            output-generation-type="PerReagentLabel" output-type="ResultFile"
            limsid="92-162" />
    </input-output-map>
</prc:process> 

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:

<?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/92-163?state=339" limsid="92-163">
    <name>Results for SAM-3 - Index 3</name>
    <type>ResultFile</type>
    <output-type>ResultFile</output-type>
    <parent-process
        uri="http://yourIPaddress/api/v2/processes/DMX-RCX-110816-24-95"
        limsid="DMX-RCX-110816-24-95" />
    <qc-flag>UNKNOWN</qc-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/RCY1A104"
        limsid="RCY1A104" />
    <reagent-label name="Index 3" />
</art:artifact> 

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.

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.

Before pooling samples in a multiplexed workflow, apply reagent labels using one of the methods described in Work with Multiplexing. After the analyte (derived sample) artifacts are labeled, they can be pooled together without loss of traceability.

Pooling samples is accomplished either by running a pooling step in the user interface, or by using the process resource in the REST API.

For an overview of how REST resources are structured, and to learn how the process resource is used to track workflow in Clarity LIMS, see REST General Concepts and Structure of REST Resources.

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 r21 or later).

Code Example

Pooling in the User Interface

The following screenshot shows a pooling step run from Clarity LIMS.

Pooling in the API with a Process POST

Pooling samples in the API is accomplished with a process resource. Information about a step is also stored in the process resource. Such a process has many input samples that map to a shared output sample, such that the shared output is a pool of those inputs. This is achieved with Run a Process/Step, where a single input-output-map element in the XML defines the shared output and all its related inputs.

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, and 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 example pools all samples found in a given container into a tube it creates.

NOTE: No special code is required to handle reagent labels. As processes execute, reagent labels automatically flow from inputs to outputs.

// Create the required URIs
containerToPoolUri = "http://${hostname}/api/v2/containers/${containerLIMSID}"
researcherURI = "http://${hostname}/api/v2/researchers/1"
 
// Find the artifacts to pool in the given container
containerToPool = GLSRestApiUtils.httpGET(containerToPoolUri, username, password)
artifactURIsToPool = containerToPool.'placement'.@uri
 
def builder = new StreamingMarkupBuilder()
builder.encoding = "UTF-8"
 
// Create a new container using the Markup Builder
def containerDoc = builder.bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(con: 'http://genologics.com/ri/container')
    mkp.declareNamespace(udf: 'http://genologics.com/ri/userdefined')
    'con:container'{
        'name'("Pooled contents from ${containerToPool.name.text()}")
        'type'(uri:"http://${hostname}/api/v2/containertypes/2", name:"Tube")
    }
}
// Post the new container to the API
containerNode = GLSRestApiUtils.xmlStringToNode(containerDoc.toString())
container = GLSRestApiUtils.httpPOST(containerNode, "http://${hostname}/api/v2/containers", username, password)
 
 
// Create a new Pool Samples process using the StreamingMarkupBuilder
processDoc = new StreamingMarkupBuilder().bind {
    mkp.declareNamespace(prx: 'http://genologics.com/ri/processexecution')
    'prx:process'{
        'type'('Pool Samples')
        'technician'(uri:researcherURI)
        'input-output-map'(shared:'true') {
            artifactURIsToPool.each { 'input'(uri:it) }
            'output'(type:'Analyte') {
                'location' {
                    'container'(uri:container.@uri)
                    'value'('1:1')
                }
            }
        }
    }
}
// Post the Pool Samples process to the API
processNode = GLSRestApiUtils.xmlStringToNode(processDoc.toString())
returnNode = GLSRestApiUtils.httpPOST(processNode, "http://${hostname}/api/v2/processes", username, password)
println GLSRestApiUtils.nodeToXmlString(returnNode)

Verify with the REST API

Irrespective of whether you use the user interface or the REST API to pool samples, the pooled sample is available via process GET requests.

The following example shows one pooled output (LIMS ID 2-424) created from three inputs - LIMS IDs RCY1A103PA1, RCY1A104PA1, and RCY1A105PA1:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<prc:process xmlns:udf="http://genologics.com/ri/userdefined"
    xmlns:file="http://genologics.com/ri/file" xmlns:prc="http://genologics.com/ri/process"
    uri="http://yourIPaddress/api/v2/processes/PSA-RCX-110812-122-221"
    limsid="PSA-RCX-110812-122-221">
    <type uri="http://yourIPaddress/api/v2/processtypes/37">Pool Samples</type>
    <date-run>2011-08-12</date-run>
    <technician uri="http://yourIPaddress/api/v2/researchers/4">
        <first-name>RC</first-name>
        <last-name>RC</last-name>
    </technician>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/RCY1A104PA1?state=319"
            uri="http://yourIPaddress/api/v2/artifacts/RCY1A104PA1?state=315"
            limsid="RCY1A104PA1" />
        <output uri="http://yourIPaddress/api/v2/artifacts/2-424?state=316"
            output-generation-type="PerAllInputs" output-type="Sample" limsid="2-424" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/RCY1A105PA1?state=317"
            uri="http://yourIPaddress/api/v2/artifacts/RCY1A105PA1?state=314"
            limsid="RCY1A105PA1" />
        <output uri="http://yourIPaddress/api/v2/artifacts/2-424?state=316"
            output-generation-type="PerAllInputs" output-type="Sample" limsid="2-424" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/RCY1A103PA1?state=318"
            uri="http://yourIPaddress/api/v2/artifacts/RCY1A103PA1?state=310"
            limsid="RCY1A103PA1" />
        <output uri="http://yourIPaddress/api/v2/artifacts/2-424?state=316"
            output-generation-type="PerAllInputs" output-type="Sample" limsid="2-424" />
    </input-output-map>
</prc:process>
 

Besides deriving from the ancestral sample artifacts, the resulting pooled sample artifact inherits the reagent labels from all inputs. The pooled output produced by the pooling step appears as follows. The pooled artifact shows multiple reagent labels, and multiple ancestor samples.

<?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/2-424?state=316" limsid="2-424">
    <name>Pool of SAM-1 - Index 1 + SAM-2 - Index 2 + SAM-3 - Index 3</name>
    <type>Analyte</type>
    <output-type>Sample</output-type>
    <parent-process
        uri="http://yourIPaddress/api/v2/processes/PSA-RCX-110812-122-221"
        limsid="PSA-RCX-110812-122-221" />
    <volume unit="uL">0.0</volume>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://yourIPaddress/api/v2/containers/27-16"
            limsid="27-16" />
        <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/RCY1A104"
        limsid="RCY1A104" />
    <sample uri="http://yourIPaddress/api/v2/samples/RCY1A105"
        limsid="RCY1A105" />
    <sample uri="http://yourIPaddress/api/v2/samples/RCY1A103"
        limsid="RCY1A103" />
    <reagent-label name="Index 1" />
    <reagent-label name="Index 2" />
    <reagent-label name="Index 3" />
</art:artifact> 

As processes are executed, reagent labels flow from inputs to outputs.

Attachments

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

def getArtifactNodes(artifactList, hostname, username, password) {
    artifactURIList = artifactList.collect{"${hostname}v2/artifacts/${it}"}
    return GLSRestApiUtils.batchGET(artifactURIList, username, password)
} 

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.

encodedWorkflowName = URLEncoder.encode(workflowName, "UTF-8")
workflowURI = GLSRestApiUtils.httpGET("${hostname}v2/configuration/workflows?name=${encodedWorkflowName}", username, password)?.workflow?.getAt(0)?.@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.

def checkMatch (artifactNodeList, workflowURI, username, password) {
    def lastWfStageURI
    def valid = false
    firstArtifactStageList = artifactNodeList[0].'workflow-stages'.'workflow-stage'
    for (i = 0; i < firstArtifactStageList.size(); i++) {
        if (firstArtifactStageList[i].@status.toString().equals('QUEUED')) {
            stageWfURI = GLSRestApiUtils.httpGET(firstArtifactStageList[i].@uri, username, password)?.workflow?.@uri[0].toString()
            if (stageWfURI.equals(workflowURI.toString())) {
                valid = true
                lastWfStageURI = firstArtifactStageList[i].@uri
                if (firstArtifactStageList[i+1]?.@status.toString().equals('REMOVED')) {
                    valid = false
                }
            }
        }
    }
    if (!valid) {
        println "artifact " + artifactNodeList[0].name.text() + " is not currently queued to this workflow"
        System.exit(-1)
    }
    for (i = 1; i < artifactNodeList.size(); i++) {
        valid = false
        artifactNodeList[i].'workflow-stages'.'workflow-stage'.each {
            if (it.@uri.toString().equals(lastWfStageURI.toString())) {
                if (it.@status.toString().equals('QUEUED')) {
                    valid = true
                } else {
                    valid = false
                }
            }
        }
        if (!valid) {
            println "Artifact " + artifactNodeList[i].name.text() + " is not currently queued to this workflow"
            System.exit(-1)
        }
    }  

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.

def queuePlacementStep (artifactNodeList, unassignStageURI, workflowToAssign) {
    def builder = new StreamingMarkupBuilder()
    builder.encoding = "UTF-8"
    def placementStepAssignment = builder.bind {
        mkp.xmlDeclaration()
        mkp.declareNamespace(rt: 'http://genologics.com/ri/routing')
        'rt:routing' {
            'unassign'('stage-uri': unassignStageURI) {
                artifactNodeList.each { artifactNode ->
                    'artifact'(uri: artifactNode.@uri)
                }
            }
            'assign'('workflow-uri': workflowToAssign) {
                artifactNodeList.each { artifactNode ->
                    'artifact'(uri: artifactNode.@uri)
                }
            }
        }
    }
    return GLSRestApiUtils.xmlStringToNode(placementStepAssignment.toString())
}

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.

def getArtifactNodes (stepDetails, username, password) {
    artifactURIList = GLSRestApiUtils.httpGET(stepDetails, username, password)\
        .'input-output-maps'.'input-output-map'.collect{it.input.@uri[0]}.toSet()
    return GLSRestApiUtils.batchGET(artifactURIList, username, password)
} 

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:

def getLastRemoved (artifactNodeList) {
    def stageList = artifactNodeList[0].'workflow-stages'.'workflow-stage'
    stageToQueue = (stageList[(stageList.size()) - 2].@status.toString().equals('REMOVED')) ? stageList[(stageList.size()) - 2].@uri : null 

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.

if (!stageToQueue) {
        println "Failed to requeue, ${artifactNodeList[0].name.text()} may have been assigned to a new workflow"
        System.exit(-1)
    } else {
        artifactNodeList.each {
            nodeStageList = it.'workflow-stages'.'workflow-stage'
            lastRemoved = nodeStageList[(nodeStageList.size() -2)].@status.toString().equals('REMOVED') ? nodeStageList[(nodeStageList.size()) -2].@uri : null
            if (!lastRemoved.toString().equals(stageToQueue.toString())) {
                println "Sample ${it.name.text()} started in a separate stage, verify all samples are being arrayed for the same workflow"
                System.exit(-1)
            }
        }
    } 

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.

def assignStage (artifactNodeList, assignStageURI) {
    def builder = new StreamingMarkupBuilder()
    builder.encoding = "UTF-8"
    def assignmentXML = builder.bind {
        mkp.xmlDeclaration()
        mkp.declareNamespace(rt: 'http://genologics.com/ri/routing')
        'rt:routing' {
            'assign'('stage-uri': assignStageURI) {
                artifactNodeList.each { artifactNode ->
                    'artifact'(uri: artifactNode.@uri)
                }
            }
        }
    }
    return GLSRestApiUtils.xmlStringToNode(assignmentXML.toString())

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. In Clarity LIMS, under Lab View, select the protocol you created in #configure2.

   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:

If your samples are already in Clarity LIMS, you can assign reagent labels by running the Add Multiple Reagents process/protocol step from the Clarity LIMS user interface. Adding a reagent implicitly assigns a reagent label to every sample artifact. The reagent label applied is derived from the reagent type used.

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

For more information on indexes with reagent labels, see .

Code Example

The following illustrations show the Add Multiple Reagents process, as run from the Operations Interface.

Run the Add Multiple Reagents process

In the Add Multiple Reagents wizard panel, reagents (Indexes 1 to 3) are selected and then assigned to the samples (SAM-1 to 3) in the Sample Workspace, using a click and drag process.

The cells of the Sample Workspace represent the wells of the container used for this process.

When the wizard completes, the Add Multiple Reagents process replaces the input sample artifacts with output analyte artifacts.

In the following illustration, the Name column shows the reagent labels applied to the outputs. These are generated by the default output naming pattern for the Add Multiple Reagents process: {InputItemName}-{AppliedReagentLabels}.

Verify with the REST API

When running the Add Multiple Reagents process, the output analyte artifact names show the reagent label applied, as the output naming pattern in the process configuration uses the {AppliedReagentLabels} variable.

By examining the REST API representation of the Add Multiple Reagents process, you can verify the following information:

• The output analyte artifacts show a reagent-label element matching the name of the reagent type used.

• The input analyte artifacts are not modified and do not have reagent labels added.

• The input analyte artifacts do not have a location element, as they were displaced by the outputs.

• You can only determine that reagent labels were applied. You cannot determine which reagent was applied.

The following shows an example of an output from an Add Multiple Reagents process when viewed with the REST API:

Although adding a reagent to a sample automatically assigns a reagent label, reagents and reagent labels are independent concepts in Clarity LIMS. There are ways to add reagent labels that do not involve reagents, and that even when using reagents, it is not possible to accurately determine the reagent used based on the reagent label attached to an artifact.

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: