Advancing/Completing a Protocol Step via the API

This topic forms a natural partner to the https://github.com/illumina-swi/clarity-int-docs/blob/main/docs/api-docs/application-examples/page-15/starting-a-protocol-step-via-the-api.md application example. When protocol steps are being initiated programmatically, we must know how to advance the step through the various states to completion.

Solution

Advancing a step is actually quite a simple task. It requires the use of the steps/advance API endpoint - in fact, little else is needed.

Let us consider a partially completed step with ID 24-1234. To advance the step to the next state, the following is required:

1. Perform a GET to the resource .../api/v2/steps/24-1234, saving the XML response.

2. POST the XML from step 1 to .../api/v2/steps/24-1234/advance, and monitor the returned XML for success.

3. If successful, the protocol step advances to its next state, just as if the lab scientist had advanced it via the Clarity LIMS interface.

4. Advancing a protocol step that is in its final state completes the step.

The Python advanceStep (STEP_URI) method shown below advances a step through its various states. To achieve this, the URI of the step is passed to the method to be advanced/completed.

def advanceStep( STEP_URI ):

    response = False

    stXML = API.getResourceByURI( STEP_URI )
    rXML = API.createObject( stXML, STEP_URI + "/advance" )
    rDOM = parseString( rXML )
    nodes = rDOM.getElementsByTagName( "configuration" )
    if len( nodes ) > 0:
        response = True

    return response

Assumptions and Notes

• The glsapiutil.py file is placed on the Clarity LIMS server, in the /opt/gls/clarity/customextensions folder. You will find the latest glsapiutil (and glsapiutil3) Python libraries on our GitHub page.

• The example code is provided for illustrative purposes only. It does not contain sufficient exception handling for use 'as is' in a production environment.