Currently, the REST API does not support the following process types:

• Batch Gel Image Analysis Run (known at Gel Analysis Experiment in the client)

• Batch Gel Run (multiple 1D Gel Run or 2D Gel Run processes run at the same time)

• Ettan Spot Handling

• Gel 1D Run (known at 1D Gel Run in the client)

• Gel 2D Run (known at 2D Gel Run in the client)

• Gel Image Analysis Run (known as Image Annotation in the client)

• Gel Imaging Run

• Sample*

  *When adding a sample to Clarity LIMS, the system actually sees the action of add sample as a process. No information pertaining to this process is made available to the user through the client. As a result, it is not supported through the REST API.

Some of the more common LIMS ID prefixes are listed in the following table.

NOTE: QC steps do not have a special LIMS ID prefix.

In addition, there are also some esoteric and deprecated LIMS ID prefixes. The complete list of prefixes can be found in the classindex database table.

Translating a Step in the Web Interface to a Step URI in the API

Assuming you have a started a step, your browser address will look something like this:

https://demo.claritylims.com/clarity/work-placement/ 21816

The important piece is the suffix - 21816.

To convert to a step URI:

1. Note the type of step you are running. Is it a Standard step, an Indexing (Add Labels) step, or a Pooling step?

2. Add the corresponding hyphenated prefix using the previous list, to construct the step ID. For example, if it is an Indexing step, 21816 becomes 151-21816.

3. Build the step URI: https://hostname/api/version/steps/151-21816.

Translating a Step URI in the API to a Step in the Web Interface

To perform the reverse action and find a step in the web interface for a given a step URI (or a process URI):

1. Get the step ID. Using the example above, the step ID would be 151-21816.

2. Strip out the hyphenated prefix to give: '21816'.

3. Build the web address: https://hostname/clarity/work/21816.

Clarity LIMS will translate the word 'work' to the correct address for the screen the step is currently on. For example, if the step is completed, 'work' will become 'work-complete'.

The Container database table includes the stateid column. Unlike the states of artifacts, container stateids can be easily deciphered. (In Clarity LIMS, the stateids correspond to the states displayed in the BaseSpace Clarity LIMS Operations Interface).

As there is no table in the database that defines these stateid values, you will need to hard code the values in your queries based on the information provided in the following table:

*Since the concept of arrays does not apply to the BaseSpace Clarity LIMS Web Interface, only states 1-5 apply.

Example 1

To search for discarded and depleted containers, use the following example:

Example 2

To see all the arrays in the system that are new and still need to be scanned, use the following example:

An artifact is defined as something that is produced by a process or protocol step. It is the output of a process/protocol step run in Clarity LIMS. For example, analytes and result files are all artifacts.

Currently, the REST API does not support the following artifacts:

• Reagents—While reagents are produced by some processes in the Clarity LIMS client, they are not exposed as artifacts in the REST API. Reagents are an entity type of their own available through the list and single reagents resources.

• Subartifacts—When a process produces shared outputs, the system creates subartifacts to support the REST data model. While they exist as entities in the system, subartifacts are transparent and meaningless to a user and are therefore not supported.

Additional reference information for Clarity LIMS.

To help with learning, BaseSpace Clarity LIMS documentation includes:

• An introduction to the API architecture (see ).

• Details of the methods and interfaces (see REST API documentation and ).

• Example code (see ).

However, there is more to the Clarity LIMS Rapid Scripting™ API package than these resources.

Details on tools, training, and best practices are covered in the following sections and in .

Non-production Scripting Sandbox Server

Nonproduction server licenses and training are essential. A nonproduction scripting sandbox server is set up with Groovy, BaseSpace Clarity LIMS, and automation ready to be used with the scripts provided in the and with the .

• Have the nonproduction servers set up before learning to script (see ).

• All the examples in the Cookbook are intended to be used with the nonproduction scripting sandbox server. This server has all the software packaged up to start scripting with the API.

• The Cookbook examples do not explain how to configure the servers for process configuration. Server installation and server-side configuration instructions are covered during implementation, as part of the installation and training services.

• For more information and to understand the importance of a dedicated scripting server, see .

Cookbook Examples for Learning the API on Nonproduction Servers

The nonproduction server license and the Cookbook examples are not for production use. It is not practical to integrate actual instruments to this server permanently, but it does provide a great way to learn to script.

The nonproduction scripting sandbox server provides a safe place to learn the API, using the Cookbook example scripts as a guide. The typical installation includes the Clarity LIMS software, the Automation Informatics node (referred to as the automation worker in Clarity LIMS v5), and Groovy.

Installation and Administration Training

IInstallation and administration training enables IT administrators to support multiple script writers with multiple nonproduction servers for development and testing. Administrators learn about server-side tools and procedures, such as the backup and restore procedure. This procedure moves scripts between systems.

• The production and nonproduction server installation training is provided to IT administrators at the start of each implementation or when the Rapid Scripting API package is purchased.

• Automation Worker (AW) node training is also included. This component can be installed on multiple computers using the Automation Worker software package.

• Explore other training, consulting, and issue management services available from Illumina in case the packaged services are exceeded.

Contact Illumina if you need additional training or support for installing and maintaining servers and AW nodes.

API Training and Consulting

The script training includes instructor-led, hands-on sessions and the training included on this site.

Instructors start from a basic Hello World script kicked off from within Clarity LIMS using automation, then progress to more in-depth concepts.

Also provided in the package is on-demand consulting. For quality service, all requests are handled via the Support team. However, expert script writers are available in technical services to consult by email, phone, or web-based sessions.

Script Deployment

Illumina recommends placing scripts in sub-directories starting from a common root, namely /opt/gls/clarity/customextensions/.

This makes moving scripts between development, test, and production systems much easier and less error-prone. This directory is assumed by the backup and restore process.

Use a directory structure beneath this root to expand your deployed scripts over time. This customextensions folder is reserved exclusively for your custom scripts.

At Illumina, this practice is called deploying on the rails. The following directories illustrate how this method is used to deploy multiple instrument integrations.

Putting all the scripts into a common root directory also allows multiple teams to work on the implementation independently. For example, when Illumina provides custom integrations and you are scripting at the same time. The backup and restore process allows you to transfer all files in the root directory between systems. It is important to not place server-specific settings, such as IP addresses or login details, in these directories.

To learn more about the backup and restore process, talk to the IT Administrator (who attended the installation and administration training) and refer to the Clarity LIMS Installation Procedure documentation (accessible from the Installation section of the Clarity LIMS documentation).

Groovy

The Cookbook how-to examples and the nonproduction server use scripts written in Groovy, a Java-based scripting language.

You can use other languages with the API. However, Groovy is easy to understand. Groovy scripts look similar to pseudocode.

In addition, Groovy is particularly suited to real scripting because it handles and manipulates the major inputs, outputs, and interfaces within Clarity LIMS well.

Related resources

To help those who prefer learning at their own pace, we have created video materials that supplement our API training materials. These videos correlate directly to the materials covered in the slides for each module, and in most cases we have also provided videos that illustrate the solution to the exercises.

These videos refer to resource definitions and the API Cookbook:

• Resource Definitions can be accessed through the API Portal.

• The cookbook is a set of example scripts intended to help you learn how to work with REST and EPP (automation) scripts.

Module 1: Overview of the API

This module outlines the course structure of the API Training Series of modules and provides a general strategy for being successful using the API.

Module 2: General Concepts of the API

This module explores the basic principles of interacting with the API. A browser plugin such as XHR for Chrome or Poster for Firefox is used and illustrates where specific LIMS data are accessible via the API. The PUT, POST, GET,and DELETE actions are explained as to how these operations are supported through the API.

Understanding the concept of a genealogy and how user defined fields are configured and used in the system is uncovered. Completing the exercises for this module is critical before proceeding to Module 3.

Module 2: Example Exercise 1

Module 2: Example Exercise 2

Module 2: Example Exercise 3

Module 3: Groovy

This module explores setting up Groovy and interacting with data in the Clarity LIMS database via the API. Common script examples from the Cookbook section are used to show how to use a scripting language to interact with the API. API example videos are also provided as part of module 3.

Module 3: Example Exercise 1

Module 3: Example Exercise 2

Module 4: Process Inputs and Outputs

This module focuses on how the data for processes that have been carried out in the LIMS are represented in XML format.

Module 4: Example Exercises

The following resources provide additional information on the tools and technologies used in the API and in the examples.

REST

The Clarity LIMS Rapid Scripting API uses a RESTful web service with XML over HTTP. For more information about REST, see the following:

Linux and Common File Formats

Many of the scripts used in the Cookbook examples assume a knowledge of Linux and text file formats.

Review bash shell execution command syntax and file formats such as comma-separated values (CSV) and Extensible Markup Language (XML):

Groovy

For its clarity and readability, we have used Groovy for the Cookbook examples. The website provides useful resources for learning and working with Groovy:

Additional Resources