Determining the Workflow(s) to Which a Sample is Assigned

Within a script, you may sometimes need to know to which workflow the current sample is assigned.

However, in Clarity LIMS, the XML payload that relates to the sample does not provide information about the workflow associations of the sample.

For example, consider a sample (artifact), picked at random, from a demo system:

<art:artifact uri="http://192.168.8.10:8080/api/v2/artifacts/2-42201?state=25871" limsid="2-42201">
    <name>Sanger Sample 49</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <parent-process uri="http://192.168.8.10:8080/api/v2/processes/24-13704" limsid="24-13704"/>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://192.168.8.10:8080/api/v2/containers/27-6899" limsid="27-6899"/>
        <value>E:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://192.168.8.10:8080/api/v2/samples/KUZ407A145" limsid="KUZ407A145"/>
</art:artifact>

It is evident that this XML payload does not provide the workflow information.

This following solution shows how to use the Clarity LIMS API to determine the association of a sample to one or more workflows.

Solution

The XML payload that corresponds to each sample artifact contains a link to the related submitted sample (or samples, if it is a pooled artifact).

Follow that link to see what it yields:

<smp:sample uri="http://192.168.8.10:8080/api/v2/samples/KUZ407A145" limsid="KUZ407A145">
    <name>Sanger Sample 49</name>
    <date-received>2013-07-15</date-received>
    <project limsid="KUZ407" uri="http://192.168.8.10:8080/api/v2/projects/KUZ407"/>
    <submitter uri="http://192.168.8.10:8080/api/v2/researchers/4">
        <first-name>Jill</first-name>
        <last-name>Hesse</last-name>
    </submitter>
    <artifact limsid="KUZ407A145PA1" uri="http://192.168.8.10:8080/api/v2/artifacts/KUZ407A145PA1?state=25080"/>
    <udf:field type="String" name="Progress">Initial sample QC complete</udf:field>
    <udf:field type="String" name="Sanger Primer">ITS1</udf:field>
    <udf:field type="String" name="Template (uL)">6.9</udf:field>
</smp:sample>

The XML corresponding to the submitted sample has a link to an artifact. This artifact is special for several reasons:

• It is known as the 'root artifact'.

• It has an unusual LIMS ID for an artifact. LIMS IDs start with '2-' for Analytes, and '92-' for ResultFiles. This one appears to be derived from the LIMS ID of the sample: KUZ407A145PA1

• A root artifact is created 'behind the scenes' whenever a submitted sample is created in the system.

• The sample history in Clarity LIMS makes it appear as if the first step in the workflow is run on the submitted sample. However, it is actually the root artifact that is the input to the first process.

• When a submitted sample is assigned to the workflow, it is the root artifact that is assigned to that workflow.

Therefore, if gathering the XML payload corresponding to the root artifact, you should see the workflow assignment:

<art:artifact uri="http://192.168.8.10:8080/api/v2/artifacts/KUZ407A145PA1?state=25080" limsid="KUZ407A145PA1">
    <name>Sanger Sample 49</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://192.168.8.10:8080/api/v2/containers/27-6754" limsid="27-6754"/>
        <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://192.168.8.10:8080/api/v2/samples/KUZ407A145" limsid="KUZ407A145"/>
    <udf:field type="String" name="Conc. Units">ng/uL</udf:field>
    <udf:field type="Numeric" name="Concentration">100</udf:field>
    <artifact-group name="Sanger Sequencing" uri="http://192.168.8.10:8080/api/v2/artifactgroups/851"/>
</art:artifact>

The key element is as follows.

<artifact-group name="Sanger Sequencing" uri="http://192.168.8.10:8080/api/v2/artifactgroups/851"/>

The name of the artifact-group (Sanger Sequencing) should match the name of the workflow in which the root artifact (and by inference, artifacts derived from the root artifact) is assigned.

Troubleshooting

If you find that the artifact-group node is missing from some of the root artifacts, there are several potential reasons:

• The workflow has been completed, causing the root artifact to be unassigned from the workflow.

• The derived samples / artifacts have been removed from the workflow intentionally, because of a sample processing issue.

• An API script has intentionally removed the derived samples / artifacts from the workflow.

• The assigned workflow has been marked as 'Archived'.