Add a New Project to the System with UDF/Custom Field Value

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.

Prerequisites

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).

Code Example

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.

Step 1. Define the Project

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.

// Determine project list's URI
String projectsListURI = "http://${hostname}/api/v2/projects"
 
def builder = new StreamingMarkupBuilder()
builder.encoding = "UTF-8"
openDate = "2017-08-22"
 
// Build a new project using Markup Builder
def projectDoc = builder.bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(prj: 'http://genologics.com/ri/project')
    mkp.declareNamespace(udf: 'http://genologics.com/ri/userdefined')
    'prj:project'{
        'name'(projectName)
        'open-date'(openDate)
        'researcher'(uri:"http://${hostname}/api/v2/researchers/1")
        'udf:field'(name:"Objective", "To test httpPOST")
    }
}

• 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.

Step 2. Post the project

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:

// Turn the markup into a node and post it to the API
def projectNode = GLSRestApiUtils.xmlStringToNode(projectDoc.toString())
projectNode = GLSRestApiUtils.httpPOST(projectNode, projectsListURI, username, password)
println GLSRestApiUtils.nodeToXmlString(projectNode)

Expected Output and Results

The XML returned after a successful POST of the XML built by StreamingMarkupBuilder is the same as the XML representation of the project:

<prj:project uri="http://yourIPaddress/api/v2/projects/ADM1101" limsid="ADM1101">
    <name>httpPOST Project</name>
    <open-date>2017-08-22</open-date>
    <researcher uri="http://yourIPaddress/api/v2/researchers/1"/>
    <udf:field xmlns:udf="http://genologics.com/ri/userdefined" type="String" name="Objective">To test httpPOST</udf:field>
        <permissions uri="http://yourIPaddress/api/v2/permissions/projects/ADM1101"/>
</prj:project>

Attachments

PostProject.groovy:

2KB

PostProject.groovy