In some circumstances, it can be desirable to automate the initiation of a step in Clarity LIMS. In this scenario, the step is thus executed without any user interaction, ie, a liquid-handling robot drives the step to completion. This example provides a solution that allows for automatic invocation of steps via the API.
Solution
Querying the Queues Endpoint
Before we can invoke a step, we must first employ the queues endpoint.
Every step displayed in the Clarity LIMS web interface has as associated queue, the contents of which can be queried. This image of the Nextera XT Library Prep shows the samples queued for each step in the Nextera XT Library Prep protocol.
Starting_a_protocol_step_via_API_1.png For this example, we investigate the queue for the Step 1 - Tagment DNA (Nextera XT DNA) step.
Step 1: Find Step ID
First, we must find the LIMS ID of the step. We query the configuration/workflows resource and hone in on the Nextera XT for MiSeq protocol:
Copy <wkfcnf:workflow status="ACTIVE" uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309" name="Nextera XT for MiSeq">
<protocols>
<protocol uri="http://192.168.8.10:8080/api/v2/configuration/protocols/3" name="DNA Initial QC"/>
<protocol uri="http://192.168.8.10:8080/api/v2/configuration/protocols/302" name="Nextera XT Library Prep"/>
<protocol uri="http://192.168.8.10:8080/api/v2/configuration/protocols/10" name="Illumina SBS (MiSeq)"/>
</protocols>
<stages>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/690" name="DNA Initial QC"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/691" name="Tagment DNA (Nextera XT DNA)"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/692" name="PCR Amplification (Nextera DNA) 4.0"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/693" name="PCR Clean-up (Nextera DNA) 4.0"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/694" name="Bead Based Library Normalization"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/695" name="Library Pooling (Nextera XT)"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/696" name="Sort MiSeq Samples (MiSeq) 4.0"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/697" name="Library Normalization (MiSeq) 4.0"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/698" name="Library Pooling (MiSeq) 4.0"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/699" name="Denature, Dilute and Load Sample (MiSeq) 4.0"/>
<stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/700" name="MiSeq Run (MiSeq) 4.0"/>
</stages>
</wkfcnf:workflow> From the XML returned, we can see that the Tagment DNA (Nextera XT DNA) step has an associated stage, with an ID of 691:
Copy <stage uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/691" name="Tagment DNA (Nextera XT DNA)"/> Step 2: Find Stage ID
If we now query this stage ID, we see something similar to the following:
Copy <stg:stage index="0" name="Tagment DNA (Nextera XT DNA)" uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309/stages/691">
<workflow uri="http://192.168.8.10:8080/api/v2/configuration/workflows/309"/>
<protocol uri="http://192.168.8.10:8080/api/v2/configuration/protocols/302"/>
<step uri="http://192.168.8.10:8080/api/v2/configuration/protocols/302/steps/567"/>
</stg:stage> We now have the piece of information we need: namely the ID 567 that is associated with this step.
Step 3: Query the Queues Resource
We can use this ID to query the queues resource, which provide us with something similar to the following:
Copy <que:queue name="Tagment DNA (Nextera XT DNA)" protocol-step-uri="http://192.168.8.10:8080/api/v2/configuration/protocols/302/steps/567" uri="http://192.168.8.10:8080/api/v2/queues/567">
<artifacts>
<artifact limsid="HES208A1PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A1PA1">
<queue-time>2013-04-07T17:01:00.636-07:00</queue-time>
<location>
<container uri="http://192.168.8.10:8080/api/v2/containers/27-2654" limsid="27-2654"/>
<value>1:1</value>
</location>
</artifact>
<artifact limsid="HES208A2PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A2PA1"></artifact>
<artifact limsid="HES208A3PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A3PA1"></artifact>
<artifact limsid="HES208A4PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A4PA1"></artifact>
<artifact limsid="HES208A5PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A5PA1"></artifact>
<artifact limsid="HES208A6PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A6PA1"></artifact>
<artifact limsid="HES208A7PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A7PA1"></artifact>
<artifact limsid="HES208A8PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A8PA1"></artifact>
<artifact limsid="HES208A9PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A9PA1"></artifact>
<artifact limsid="HES208A10PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A10PA1"></artifact>
</artifacts>
</que:queue> This result matches the information displayed in the Clarity LIMS web interface. In the next image, we can see the derived samples awaiting the step.
Initiating the Step
Now that we have the contents of the queue, starting the step programmatically is quite simple.
All that is required is a POST to the steps API endpoint. The XML input payload to the POST request will take the following form:
Copy <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tmp:step-creation xmlns:tmp="http://genologics.com/ri/step">
<configuration uri="http://192.168.8.10:8080/api/v2/configuration/protocols/302/steps/567"/>
<container-type>96 well plate</container-type>
<inputs>
<input uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A1PA1" replicates="1"/>
</inputs>
</tmp:step-creation> If the POST operation was successful, the API will return XML of the following form (for details, see About the Code section):
Copy <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<stp:step xmlns:stp="http://genologics.com/ri/step" current-state="Placement" limsid="24-19301" uri="http://192.168.8.10:8080/api/v2/steps/24-19301">
<configuration uri="http://192.168.8.10:8080/api/v2/configuration/protocols/302/steps/567">Tagment DNA (Nextera XT DNA)</configuration>
<actions uri="http://192.168.8.10:8080/api/v2/steps/24-19301/actions"/>
<placements uri="http://192.168.8.10:8080/api/v2/steps/24-19301/placements"/>
<details uri="http://192.168.8.10:8080/api/v2/steps/24-19301/details"/>
<available-programs/>
</stp:step> User Interaction
In the Clarity LIMS web interface, two pieces of evidence indicate that the step has been initiated:
The partially completed step is displayed in the Work in Progress area.
The Recent Activities area shows that the protocol step was started.
About the Code
The XML payload POSTed to the steps resource is quite simple in nature. In fact there are only three variables within the payload:
1. The step to be initiated:
Copy <configuration uri="http://192.168.8.10:8080/api/v2/configuration/protocols/302/steps/567"/> 2. The type of output container to be used (if appropriate):
Copy <container-type>96 well plate</container-type> 3. The URI(s) of the artifact(s) on which the step should be run, along with the number of replicates the step needs to create (if appropriate):
Copy <input uri="http://192.168.8.10:8080/api/v2/artifacts/HES208A1PA1" replicates=" 
