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

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.

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

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

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

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:

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:

Expected Output and Results

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.