1 of 1

Starting a Protocol Step via the API

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.

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:

From the XML returned, we can see that the Tagment DNA (Nextera XT DNA) step has an associated stage, with an ID of 691:

Step 2: Find Stage ID

If we now query this stage ID, we see something similar to the following:

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:

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:

If the POST operation was successful, the API will return XML of the following form (for details, see section):

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:

2. The type of output container to be used (if appropriate):

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

Starting a Protocol Step via the API

Solution

Querying the Queues Endpoint

Before we can invoke a step, we must first employ the queues endpoint.

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:

From the XML returned, we can see that the Tagment DNA (Nextera XT DNA) step has an associated stage, with an ID of 691:

Step 2: Find Stage ID

If we now query this stage ID, we see something similar to the following:

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:

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:

If the POST operation was successful, the API will return XML of the following form (for details, see section):

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:

2. The type of output container to be used (if appropriate):

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

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

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

<?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>

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

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

<?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>

Starting a Protocol Step via the API

hashtagSolution

hashtagQuerying the Queues Endpoint

hashtagInitiating the Step

hashtagUser Interaction

hashtagAbout the Code

Starting a Protocol Step via the API

hashtagSolution

hashtagQuerying the Queues Endpoint

hashtagInitiating the Step

hashtagUser Interaction

hashtagAbout the Code

Solution

Querying the Queues Endpoint

Initiating the Step

User Interaction

About the Code

Solution

Querying the Queues Endpoint

Initiating the Step

User Interaction

About the Code