Completing a Step Programmatically

This method supersedes the use of the processes API endpoint.

The capacity for completing a step programmatically, without having to open the BaseSpace Clarity LIMS web interface, allows for rapid validation of protocols. This method results in streamlined workflows for highly structured lab environments dealing with high throughput.

This example uses the /api/v2/steps endpoint, which allows for more controlled execution of steps. In contrast, a process can be executed using the api/v2/processes endpoint with only one POST. This ability is demonstrated in the Process Execution with EPP/Automation Support example.

Solution

The Clarity LIMS API allows for each aspect of a step to be completed programatically. Combining the capabilities of the API into one script allows for the completion of a step with one click.

Step Configuration

This example was created for non-pooling, non-indexing process types.

Parameters

The script accepts the following parameters:

-u	The username of the current user (Required)
-p	The password of the current user (Required)
-s	The URI of the step that launches the script - the {stepURI:v2:http} token (Required)

An example of the full syntax to invoke the script is as follows:

/usr/bin/python /opt/gls/clarity/customextensions/autocomplete-wholestep.py -p apipassword -u apiuser -s https://demo-4-1.claritylims.com/api/v2/

User Interaction

The script contains several hard coded variables, as shown in the following example.

step_config_uri = "https://demo-4-1.claritylims.com/api/v2/configuration/protocols/551/steps/1003"
step_config = "simple step"
queue = '1003'

containerType = "96 well plate"
reagentCat = ""
replicates = 40

nextAction = 'nextstep'
nextStepURI = 'https://demo-4-1.claritylims.com/api/v2/configuration/protocols/551/steps/1004'

reagent_lot_limsid = ""

step_config_uri Is the stage that is automatically completed. Because this script is starting the step, there is no step limsid needed as input parameter to the script. After the script begins the step, it gathers the step limsid from the APIs response to the step-creation post.

queue = '1003'

About the Code

The main() method in the script carries out the following operations:

• startStep()

• addLot()

• addAction()

• addPlacement()

• advanceStep()

Each of these functions creates an XML payload and interacts with the Clarity LIMS API to complete an activity that a lab user would be doing in the Clarity LIMS interface.

startStep()

This function creates a 'stp:step-creation' payload.

As written, the script includes all the analytes in the queue for the specified stage.

addLot()

This function creates a 'stp:lots' payload. This may be skipped if the process does not require reagent lot selection.

addAction()

This function creates a 'stp:actions' payload. As written, all output analytes are assigned to the same 'next-action'. To see the options available as next actions, see the REST API documentation: Type action-type:

NOTE: This example only supports the following next-actions: 'nextstep', 'remove', 'repeat'.

addPlacement()

This function creates a 'stp:placements' payload.

In this example, it is not important where the artifacts are placed, so the analytes are assigned randomly to a well location.

This function relies on the createContainer function, since a step producing replicate analytes may not create enough on-the-fly containers to place all out the output artifacts.

advanceStep()

This function advances the current-state for a step. The current-state is an attribute that is found at the /api/v2/steps/{limsid} endpoint. It is a representation of the page that you see in the user interface. For more information, see API Portal and search for the REST API documentation relating to the /{version}/steps/{limsid}/advance endpoint.

This function creates a 'stp:placements' payload. POSTing this payload to steps/{limsid}/advance is the API equivalent of moving to the next page of the GUI, with the final advance post completing the step.

Known Issues

• There is a known bug with advance endpoint that prevents a complete end-to-end programatic progression through a pooling step.

Assumptions and Notes

• You are running a version of Python that is supported by Clarity LIMS, as documented in the Clarity LIMS Technical Requirements.

• The attached file is placed on the LIMS server, in the /opt/gls/clarity/customextensions folder.

• The Python API Library (glsapiutil.py) is placed on the Clarity LIMS server, in the /opt/gls/clarity/customextensions folder. You can download the latest glsapiutil library from our GitHub page.

• The HOSTNAME global variable must be updated so that it points to your Clarity LIMS server.

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

Attachments

autocomplete-wholestep.py:

8KB

autocomplete-wholestep.py