Update Contact (User and Client) Information

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.

Prerequisites

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

Code Example

For Clarity LIMS v5 and later, in the web interface, the User and Clients screen lists all users and clients in the system.

Step 1. Retrieve the Researcher Resource

In the API, information for a particular researcher can be retrieved within a script using a GET call:

// Retrieve the researcher
Node researcher = GLSRestApiUtils.httpGET(researcherURI, username, password)

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:

<res:researcher uri="http://yourIPaddress/api/v2/researchers/103">
    <first-name>Sue</first-name>
    <last-name>Eriksond</last-name>
    <phone>212-212-2130</phone>
    <fax>212-212-2131</fax>
    <email>serikson@eriksonlabsny.com</email>
    <lab uri="http://yourIPaddress/api/v2/labs/102"/>
    <credentials>
        <username>serikson</username>
        <account-locked>false</account-locked>
        <role roleName="webclient"/>
        <role roleName="administrator"/>
        <role roleName="labtech"/>
    </credentials>
    <initials>SEK</initials>
</res:researcher>

Step 2. Update the Researcher Information

Updating the telephone number requires the following steps:

1. Changing the telephone value in the XML.

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

newPhoneNumber = '212-212-2133' // Set the new phone number researcher.'phone'[0].setValue(newPhoneNumber) Node returnNode = GLSRestApiUtils.httpPUT(researcher, researcher.@uri, username, password) println GLSRestApiUtils.nodeToXmlString(returnNode)

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.

Expected Output and Results

For a successful update, the resulting XML can also be reviewed in a web browser via the URI:

http://yourIPaddress/api/researchers/103

<res:researcher uri="http://yourIPaddress/api/v2/researchers/103">
    <first-name>Sue</first-name>
    <last-name>Eriksond</last-name>
    <phone>212-212-2133</phone>
    <fax>212-212-2131</fax>
    <email>serikson@eriksonlabsny.com</email>
    <lab uri="http://yourIPaddress/api/v2/labs/102"/>
    <credentials>
        <username>serikson</username>
        <account-locked>false</account-locked>
        <role roleName="webclient"/>
        <role roleName="administrator"/>
        <role roleName="labtech"/>
    </credentials>
    <initials>SEK</initials>
</res:researcher>

In the LIMS, the updated user list should show the new phone number.

Attachments

UpdateContactInfo.groovy: