Displaying Files From an Earlier Step

This article explains how to make files that were produced by / attached to the LIMS in an earlier step, visible in a subsequent step.

Solution

Consider a simplified workflow / protocol containing just two steps: Produce Files and Display Files.

• The first step, Produce Files, will take in analytes (derived samples), and generate individual result files (one per input).

• The subsequent Display Files step will allow us to view the files associated with the analytes from the previous step.

After the files have been generated by and attached to the Produce Files step, the Record Details screen of the step displays the files.

The key to displaying these files in any subsequent step involves producing a hyperlink to the file and displaying it as a user-defined field (UDF)/custom field in subsequent steps.

You may be familiar with creating and using text, numeric, and checkbox UDFs/custom fields. However, you may be less familiar with the hyperlink option. Fields of this type are used less frequently, but they are perfect for this solution.

NOTE: As of Clarity LIMS v5.0, the term user-defined field (UDF) has been replaced with custom field in the user interface. However, the API resource is still called UDF.

This solution involves a script that runs on the Record Details screen on the subsequent Display Files step and populates the fields. See the following figure.

As you can see, the structure of the hyperlink is straightforward and includes:

• The IP address / hostname of the server.

• The port.

• A link to the LIMS ID of the file to be linked to.

The Script

To populate these fields, there are numerous methods available within an API-based script. The method discussed here works for the two-step protocol described earlier (namely that we want the files displayed in the next step of the protocol). It also works when the steps in which the files are uploaded and displayed are separated by several intermediate steps.

Assuming that the script will run just as the Record Details screen of the Display Files step is being displayed, use pseudocode to produce the hyperlinks.

For each output:

1. Determine the LIMS Unique ID (LUID) of the output artifact.

2. Determine the LUID of the submitted sample associated with the output artifact.

3. Determine the LUID of the resultfile artifact produced by the earlier process, derived from the common submitted sample.

4. Determine the LUID of the file associated with the resultfile artifact.

5. Update the hyperlink UDF / custom field on the output artifact (from step 1) with the specific hyperlink value.

To illustrate these pseudocode steps, XML from a demo system is provided.

1. Gather the LIMS Unique ID (LUID) of the Output Artifact

<prc:process uri="http://192.168.8.10:8080/api/v2/processes/24-24452" limsid="24-24452">
    <type uri="http://192.168.8.10:8080/api/v2/processtypes/1555">display files</type>
    <technician uri="http://192.168.8.10:8080/api/v2/researchers/1">
    <first-name>System</first-name>
    <last-name>Administrator</last-name>
    </technician>
    <input-output-map>
        <input post-process-uri="http://192.168.8.10:8080/api/v2/artifacts/ADM1301A2PA1?state=48636" 
            uri="http://192.168.8.10:8080/api/v2/artifacts/ADM1301A2PA1?state=48636" 
            limsid="ADM1301A2PA1"/>
        <output uri="http://192.168.8.10:8080/api/v2/artifacts/2-81806?state=49106" 
            output-generation-type="PerInput" output-type="Analyte" 
            limsid="2-81806"/>
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://192.168.8.10:8080/api/v2/artifacts/ADM1301A3PA1?state=48632" 
            uri="http://192.168.8.10:8080/api/v2/artifacts/ADM1301A3PA1?state=48632" 
            limsid="ADM1301A3PA1"/>
        <output uri="http://192.168.8.10:8080/api/v2/artifacts/2-81805?state=49105" 
            output-generation-type="PerInput" output-type="Analyte" 
            limsid="2-81805"/>
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://192.168.8.10:8080/api/v2/artifacts/ADM1301A1PA1?state=48650" 
            uri="http://192.168.8.10:8080/api/v2/artifacts/ADM1301A1PA1?state=48650" 
            limsid="ADM1301A1PA1"/>
        <output uri="http://192.168.8.10:8080/api/v2/artifacts/2-81804?state=49104" 
            output-generation-type="PerInput" output-type="Analyte" 
            limsid="2-81804"/>
    </input-output-map>
</prc:process>

From the XML representation of the Display Files process/step. we see that we have three output artifact LUIDS: 2-81806, 2-81805 and 2-81804.

2. Determine the LUID of the Submitted Sample Associated with the Output Artifact

By examining the XML representation of the first output artifact (2-81806), we see the LUID of the associated submitted sample is ADM1301A2:

<art:artifact uri="http://192.168.8.10:8080/api/v2/artifacts/2-81806?state=49106" limsid="2-81806">
    <name>WG-23476-2</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <parent-process uri="http://192.168.8.10:8080/api/v2/processes/24-24452" limsid="24-24452"/>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://192.168.8.10:8080/api/v2/containers/27-11353" limsid="27-11353"/>
        <value>1:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://192.168.8.10:8080/api/v2/samples/ADM1301A2" limsid="ADM1301A2"/>
</art:artifact> 

3. Determine the LUID of the resultfile Artifact Produced by the Earlier Process/Step, Derived from the Common Submitted Sample

After the common ancestor is found, ask Clarity LIMS for the output artifacts produced by our step of interest (Produce Files) directly.

For example:

http://192.168.8.10:8080/api/v2/artifacts?samplelimsid=ADM1301A2&process-type=Produce%20Files&type=ResultFile

Yields the following XML:

<art:artifacts>
    <artifact limsid="92-81803" uri="http://192.168.8.10:8080/api/v2/artifacts/92-81803"/>
</art:artifacts> 

The resultfile with LUID 92-81803 is associated with the current output artifact (2-81806), even though these entities may be separated by several steps.

If the process/step produces multiple resultfiles, you may need to further constrain the search using the name= parameter. For example:

http://192.168.8.10:8080/api/v2/artifacts?samplelimsid=ADM1301A2&process-type=Produce%20Files&type=ResultFile&name=<name of ResultFile>

4. Determine the LUID of the File Associated with the resultfile Artifact

By gathering the XML representation of artifact 92-81803, the associated file has LUID 40-3652:

<art:artifact uri="http://192.168.8.10:8080/api/v2/artifacts/92-81803?state=49103" limsid="92-81803">
    <name>WG-23476-2</name>
    <type>ResultFile</type>
    <output-type>ResultFile</output-type>
    <parent-process uri="http://192.168.8.10:8080/api/v2/processes/24-24451" limsid="24-24451"/>
    <qc-flag>UNKNOWN</qc-flag>
    <sample uri="http://192.168.8.10:8080/api/v2/samples/ADM1301A2" limsid="ADM1301A2"/>
    <file:file limsid="40-3652" uri="http://192.168.8.10:8080/api/v2/files/40-3652"/>
</art:artifact> 

5. Update the Hyperlink UDF/Custom Field on the Output Artifact (from Step 1) with the Specific Hyperlink Value

Now that you know the LUID of the file associated with output artifact 2-81803, set the value of its hyperlink field in the following form:

http://192.168.8.10:8080/clarity/api/files/3652

When constructing the value for the hyperlink, the 40- prefix should be removed from the LUID of the file.