Introduction to Batch Resources

The powerful batch resources included in the Clarity LIMS Rapid Scripting API significantly increase the speed of script execution by allowing batch operations on samples and containers. These resources are useful when working with multiple samples and containers in high throughput labs.

The following simple example uses batch resources to move samples from one workflow queue into another queue.

It is useful to review the Work with Batch Resources.

Use a batch retrieve request to find all the artifacts in an artifact group, and then use a batch update request to move those artifacts into another artifact group.

The following steps are required:

Find all the artifacts that are in a particular artifact group.
Use the artifacts.batch.retrieve (list) resource to retrieve the details for all the artifacts.
Use the artifacts.batch.update (list) resource to update the artifacts and move them into a different artifact group, posting them back as a batch.

NOTE: The only HTTP method for batch resources is POST.

Prerequisites

Before you follow the steps, make sure that you have the following items:

Clarity LIMS contains a collection of samples (artifacts) residing in the same workflow queue (artifact group)
A second queue exists into which you can move the collection of samples
A compatible version of API (v2 r21 and later).

In the REST API, artifacts are grouped with the artifact group resource. In Clarity LIMS, an artifact group is displayed as a workflow. Workflows are configured as queues, allowing lab scientists to locate samples to work with on the bench quickly.

Step 1. Find All of the Samples in a Workflow Queue

To find the samples (artifacts) in a workflow queue (artifact group), use the following request, editing the server details and artifact group name to match those in your system:

http://your-server-ip/api/v2/artifacts?artifactgroup=my_queue

This request returns a list of URI links for all artifacts in the artifact group specified. In our example, the my_queue queue contains three artifacts:

<art:artifacts xmlns:art="http://genologics.com/ri/artifact">
  <artifact limsid="ADM1A1PA1" uri="http://your-server-ip/api/v2/artifacts/ADM1A1PA1"/>
  <artifact limsid="ADM1A2PA1" uri="http://your-server-ip/api/v2/artifacts/ADM1A2PA1"/>
  <artifact limsid="ADM1A3PA1" uri="http://your-server-ip/api/v2/artifacts/ADM1A3PA1"/>
</art:artifacts>

Step 2. Retrieve Sample Details

To retrieve the detailed XML for all of the artifacts, use a <links> tag to post the set of URI links to the server using a batch retrieve request:

<ri:links xmlns:ri="http://genologics.com/ri">
  <link uri="http://your-server-ip/api/v2/artifacts/ADM1A1PA1" rel="artifacts"/>
  <link uri="http://your-server-ip/api/v2/artifacts/ADM1A2PA1" rel="artifacts"/>
  <link uri="http://your-server-ip/api/v2/artifacts/ADM1A3PA1" rel="artifacts"/>
</ri:links>

http://your-server-ip/api/v2/artifacts/batch/retrieve

This returns the detailed XML for each of the artifacts in the batch:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<art:details xmlns:udf="http://genologics.com/ri/userdefined" 
xmlns:file="http://genologics.com/ri/file" xmlns:art="http://genologics.com/ri/artifact">
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A1PA1?state=21" limsid="ADM1A1PA1">
    <name>base-1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-10" limsid="27-10"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A1" limsid="ADM1A1"/>
    <artifact-group name="my_queue" uri="http://your-server-ip/api/v2/artifactgroups/1"/>
  </art:artifact>
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A2PA1?state=42" limsid="ADM1A2PA1">
    <name>base-2</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-11" limsid="27-11"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A2" limsid="ADM1A2"/>
    <artifact-group name="my_queue" uri="http://your-server-ip/api/v2/artifactgroups/1"/>
  </art:artifact>
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A3PA1?state=12" limsid="ADM1A3PA1">
    <name>base-3</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-12" limsid="27-12"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A3" limsid="ADM1A3"/>
    <artifact-group name="my_queue" uri="http://your-server-ip/api/v2/artifactgroups/1"/>
  </art:artifact>
</art:details>

The XML returned includes the artifact group name and URI:

<artifact-group name="my_queue" uri="http://your-server-ip/api/v2/artifactgroups/1"/>

Step 3. Move All Samples into a Different Queue

To move the artifacts into another queue, simply update the artifact-group name and URI values:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<art:details xmlns:udf="http://genologics.com/ri/userdefined" xmlns:file="http://genologics.com/ri/file" xmlns:art="http://genologics.com/ri/artifact">
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A1PA1?state=21" limsid="ADM1A1PA1">
    <name>base-1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-10" limsid="27-10"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A1" limsid="ADM1A1"/>
    <artifact-group name="new_queue"  uri="http://your-server-ip/api/v2/artifactgroups/2"/>
  </art:artifact>
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A2PA1?state=42" limsid="ADM1A2PA1">
    <name>base-2</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-11" limsid="27-11"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A2" limsid="ADM1A2"/>
    <artifact-group name="new_queue"  uri="http://your-server-ip/api/v2/artifactgroups/2"/>
  </art:artifact>
  <art:artifact uri="http://your-server-ip/api/v2/artifacts/ADM1A3PA1?state=12" limsid="ADM1A3PA1">
    <name>base-3</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
      <container uri="http://your-server-ip/api/v2/containers/27-12" limsid="27-12"/>
      <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://your-server-ip/api/v2/samples/ADM1A3" limsid="ADM1A3"/>
    <artifact-group name="new_queue"  uri="http://your-server-ip/api/v2/artifactgroups/2"/>
  </art:artifact>
</art:details>

Finally, post the XML back to the server using a batch update request:

http://your-server-ip/api/v2/artifacts/batch/update

PreviousWork with Batch Resources NextUpdate UDF/Custom Field Information with Batch Operations

Last updated 5 months ago