API-Based URIs (LIMS v4 and later)
Clarity LIMS version 4.0 introduced architectural changes that enforce SSL-based security. As a result, the structure of the URIs that reference the Clarity LIMS API was modified, and scripts written before Clarity LIMS v4.0 may require updating.
Details
Scripts that use the API do so by using RESTful methods on specific URIs. The base portion of the URI references the server on which the Clarity LIMS application is running.
Before Clarity LIMS v4.0 the base portion of the URI took the following form:
http[s]://<your_server_name>:<your_port_number>/api
Where:
The protocol could either be HTTP or HTTPS, depending on whether the application was SSL-enabled or not.
<your_server_name> represented the fully qualified domain name (or IP address) relating to the server on which the Clarity LIMS application was running.
<your_port_number> represented the port number (typically 8080) on which the Clarity LIMS application was listening.
In Clarity LIMS v4.0 and later, the base portion of the URI is in the following form:
https://<your_server_name>/api
Where:
The protocol must be HTTPS, because the Clarity LIMS application is now installed with SSL enabled.
The server name must match the certificate that was purchased and installed into Clarity LIMS.
The port number (and the colon) is no longer required. Do not provide it.
When to Update Existing Scripts
The following information should help determine if updates to the scripts are needed.
Scripts generally determine the API URI in one of the following ways:
The URI is passed to the script by the automation or External Program Plugin (EPP) component, as a parameter or command-line argument.
The URI is passed to the script by another script or a command line embedded in a crontab file.
The script contains the URI as a hard-coded string literal.
The script determines the fully qualified domain name of the server and adds the prefix (http://) and suffix (:8080) accordingly.
The script imports, or includes a file that contains, the URI.
Most scripting uses methods one or three. However, other methods may be used in the facility.
If method one is used, it is not necessary to update the scripts because Clarity LIMS passes in the new form of the URI.
If other methods are used, you likely need to update the scripts to convert the URI to the new format. Often, a search and replace tool is able to make these changes.
To make sure that the correct locations are searched, keep in mind that scripts are often stored in the following locations:
In the /opt/gls/clarity/customextensions folder (and subfolders) on the server where Clarity LIMS is running. This location is the domain of the default Automation Worker (AW)/Automated Informatics (AI) node, which listens on the channel name of limsserver.
If there are additional AW/AI nodes on the server, in the folders used by these nodes.
If there are additional AW/AI nodes external to the Clarity LIMS server, within the folders used by these nodes.
If scripts are launched by cron, or other mechanisms, they could be stored anywhere and may not even be on the Clarity LIMS server itself.
For points 1–3, query Clarity LIMS (via either the API or the database) to produce a listing of all the scripts it is configured to use. As a result, determine on which node they run and their location.
For point 4, there is no easy answer. Hopefully, if the script is important, the location has been documented.
As of Clarity LIMS v5.0, the terms External Program Integration Plug-in (EPP), EPP node, and AI node are deprecated.
The term EPP has been replaced with automation, while the Automated Informatics (AI) node is referred to as the Automation Worker (AW) node.
Last updated