File attachments

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

Working with the attached scripts

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

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

/opt/gls/clarity/customextensions/ 

Using Full Production Scripts

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

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

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

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

Version Compatibility

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

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

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

Path to Groovy

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

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

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

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

Compare this command to the full logon shell, which is

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

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

References

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

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

• Automation Tokens

Browser Plug-Ins

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

The following plug-ins are available with Firefox:

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

• Linkificator—Converts text links into selectable links.

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

The following plug-ins are available with Chrome:

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

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

Before downloading your first script, do the following actions:

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

• Use a non-production server for script development.

• Familiarize yourself with the coding language.

• Use the GLSRestApiUtils file to assist with recipe development.

• Review Tips and Troubleshooting.

Script Development with a Non-Production Server

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

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

Script Types

Groovy

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

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

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

  Copy

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

Python

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

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

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

Use GLSRestApiUtils

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

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

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: