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.
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).
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.
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:
GetLab.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.
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).
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.
The first step is to determine the URI of the project:
Next, use the project LIMS ID to perform an HTTP GET on the resource, and store the response XML in the variable named projectNode:
The projectNode variable can now be used to access XML elements and/or attributes.
To obtain the project's name ask the projectNode for the text representation of the name element:
GetProjectName.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.
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).
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.
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.
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.
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:
The XML returned after a successful POST of the XML built by StreamingMarkupBuilder is the same as the XML representation of the project:
PostProject.groovy:
When working with projects and accounts, you can do the following:
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.
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.
This example does the following actions:
POST a new project to the LIMS, with a UDF / custom field value for Objective.
Remove a child XML node from the parent XML representing the project resource.
Update the project resource.
First, set up the information required to perform a successful project POST. The project name must be unique.
The projectNode should contain the response XML from the POST and resemble the following output:
The following code removes the child XML node <udf:field> from the parent XML node <prj:project>:
If multiple nodes of the same type exist, [0] is the first item in this list of same typed nodes (eg, 0 contains 1st item, 1 contains 2nd item, 2 contains 3rd item, and so on).
To remove the 14th udf:field, you would use projectNode?.children()?.remove(projectNode.'udf:field'[13])
RemoveChildNode.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.
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).
For Clarity LIMS v5 and later, in the web interface, the User and Clients screen lists all users and clients in the system.
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:
Updating the telephone number requires the following steps:
Changing the telephone value in the XML.
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.
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.
UpdateContactInfo.groovy: