Creating Notifications When Files are Added via LabLink

This topic explains how to:

1. Detect when files have have been uploaded.

2. Extract the key information that might comprise a notification.

The Files API Resource

The key resource to investigate is the files resource, which provides a listing of files within the system.

Step 1. Access the Files Resource

On a test system accessing the files resource as follows:

http://192.168.9.123:8080/api/v2/files

produces the following output:

<file:files>
    <file limsid="92-932-40-16" uri="http://192.168.9.123:8080/api/v2/files/92-932-40-16"/>
    <file limsid="92-944-40-18" uri="http://192.168.9.123:8080/api/v2/files/92-944-40-18"/>
    <file limsid="92-943-40-20" uri="http://192.168.9.123:8080/api/v2/files/92-943-40-20"/>
    <file limsid="92-945-40-22" uri="http://192.168.9.123:8080/api/v2/files/92-945-40-22"/>
    <file limsid="92-942-40-24" uri="http://192.168.9.123:8080/api/v2/files/92-942-40-24"/>
    <file limsid="92-941-40-26" uri="http://192.168.9.123:8080/api/v2/files/92-941-40-26"/>
    <file limsid="ADM102A1DN3-40-28" uri="http://192.168.9.123:8080/api/v2/files/ADM102A1DN3-40-28"/>
    ...
    <file limsid="92-2587-40-459" uri="http://192.168.9.123:8080/api/v2/files/92-2587-40-459"/>
    <file limsid="92-2590-40-460" uri="http://192.168.9.123:8080/api/v2/files/92-2590-40-460"/>
    <file limsid="92-2594-40-462" uri="http://192.168.9.123:8080/api/v2/files/92-2594-40-462"/>
    <file limsid="92-2595-40-463" uri="http://192.168.9.123:8080/api/v2/files/92-2595-40-463"/>
    <file limsid="92-2596-40-465" uri="http://192.168.9.123:8080/api/v2/files/92-2596-40-465"/>
    <file limsid="92-2597-40-466" uri="http://192.168.9.123:8080/api/v2/files/92-2597-40-466"/>
    <file limsid="40-501" uri="http://192.168.9.123:8080/api/v2/files/40-501"/>
    <file limsid="40-558" uri="http://192.168.9.123:8080/api/v2/files/40-558"/>
    <file limsid="92-4555-40-609" uri="http://192.168.9.123:8080/api/v2/files/92-4555-40-609"/>
    <file limsid="92-4554-40-610" uri="http://192.168.9.123:8080/api/v2/files/92-4554-40-610"/>
    <file limsid="92-4556-40-611" uri="http://192.168.9.123:8080/api/v2/files/92-4556-40-611"/>
    <file limsid="92-4564-40-612" uri="http://192.168.9.123:8080/api/v2/files/92-4564-40-612"/>
    <file limsid="92-4563-40-613" uri="http://192.168.9.123:8080/api/v2/files/92-4563-40-613"/>
    <file limsid="92-4562-40-614" uri="http://192.168.9.123:8080/api/v2/files/92-4562-40-614"/>
    <file limsid="ACC151-40-651" uri="http://192.168.9.123:8080/api/v2/files/ACC151-40-651"/>
    <file limsid="ACC151A1-40-652" uri="http://192.168.9.123:8080/api/v2/files/ACC151A1-40-652"/>
</files>

Step 2. Filter the Files URI

Although not particularly useful in itself, the files URI becomes more interesting when we filter it to only include files uploaded after a specified date-time, and also only those files that have a published status of 'true'.

For example, the following URI:

http://192.168.9.123:8080/api/v2/files?last-modified=2013-09-10T00:00:00-08:00&published=true

produces this output on a test system:

<file:files>

<file limsid="ACC151-40-651" uri="http://192.168.9.123:8080/api/v2/files/ACC151-40-651"/>

<file limsid="ACC151A1-40-652" uri="http://192.168.9.123:8080/api/v2/files/ACC151A1-40-652"/>

</file:files>

This outcome is much more manageable. Because they are uploaded via the Collaborations Interface, they inherently have a published status of 'true'. We use this status to exclude regular files uploaded to the LIMS via other methods and interfaces.

Step 3. Retrieve the XML Representations of the Files

By following the URIs to retrieve the full XML representations of these files, the output is similar to the following:

<file:file uri="http://192.168.9.123:8080/api/v2/files/ACC151-40-651" limsid="ACC151-40-651">

<attached-to>http://192.168.9.123:8080/api/v2/projects/ACC151</attached-to>

<content-location> sftp://192.168.9.123/home/glsftp/ACC151/ACC151-40-651.csv </content-location>

<original-location>GLims.csv</original-location>

<is-published>true</is-published>

</file:file>

and:

<file:file uri="http://192.168.9.123:8080/api/v2/files/ACC151A1-40-652" limsid="ACC151A1-40-652">

<attached-to>http://192.168.9.123:8080/api/v2/samples/ACC151A1</attached-to>

<content-location> sftp://192.168.9.123/home/glsftp/ACC151/ACC151A1/ACC151A1-40-652.png </content-location>

<original-location>image001.png</original-location>

<is-published>true</is-published>

</file:file>

Step 4. Retrieve Project/Sample Information

Retrieve the associated project/sample, and extract the names and/or IDs to embed into the notification, by following the URI in the 'attached-to' elements.

In this case, the following result is produced:

<prj:project uri="http://192.168.9.123:8080/api/v2/projects/ACC151" limsid="ACC151">

<name>Scaffold POC</name>

<open-date>2013-04-18</open-date>

<researcher uri="http://192.168.9.123:8080/api/v2/researchers/3" />

<file:file limsid="ACC151-40-651" uri="http://192.168.9.123:8080/api/v2/files/ACC151-40-651" />

</prj:project>

and:

<smp:sample uri="http://192.168.9.123:8080/api/v2/samples/ACC151A1" limsid="ACC151A1">

<name>SG-5926 -1</name>

<date-received>2013-04-18</date-received>

<project limsid="ACC151" uri="http://192.168.9.123:8080/api/v2/projects/ACC151"/ >

<submitter uri="http://192.168.9.123:8080/api/v2/researchers/1">

<first-name>System</first-name>

<last-name>Administrator</last-name>

</submitter>

<artifact limsid="ACC151A1PA1" uri="http://192.168.9.123:8080/api/v2/artifacts/ACC151A1PA1?state=451" />

<udf:field type="Boolean" name="Control?">false</udf:field>

<udf:field type="String" name="Category">treated</udf:field>

<file:file limsid="ACC151A1-40-652" uri="http://192.168.9.123:8080/api/v2/files/ACC151A1-40-652"/>

</smp:sample>

Proposed Solution

A script must be run periodically (hourly/daily) that queries the files resource for files that have a published status of true, and are last modified in the period of interest.

After this list of files is retrieved, the following pseudocode can be applied:

For each URI in files list:
  Retrieve the file object
    STORE the contents of the 'original-location' element
    IF the contents of the 'attached-to' element contains EITHER 'projects' OR 'samples':
      Retrieve the object pointed to by the 'attached-to' element
      STORE the contents of the 'name' element
      Compile the stored elements into a notification
Publish all notifications produced in an atomic or molecular fashion, as required

An example derived from the above XML could lead to the following notifications:

FILE: GLims.csv was recently uploaded to PROJECT: Scaffold POC

FILE: image001.png was recently uploaded to SAMPLE: -1