Process Execution with EPP/Automation Support

At the completion of a process (using API v2 r21 or later), EPP can invoke any external program that runs from a command line. In this example, a process with a reference to a declared EPP program is configured and executed entirely via the API.

EPP automation/support is compatible with API v2 r21 and later.

The API documentation includes the terms External Program Integration Plug-in (EPP) and EPP node.

As of Clarity LIMS v5.0, these terms are deprecated.

• EPP has been replaced with automation.

• EPP node is referred to as the Automation Worker or Automation Worker node. These components are used to trigger and run scripts, typically after lab activities are recorded in the LIMS.

Prerequisites

1. You have defined a process that has:

   • An input of type analyte.

   • A single output per input.

   • A single shared result file.

2. The process type is associated with an external program that has the following requirements:

   • At least one process-parameter defined - named TestProcessParam.

   • A parameter string of: bash -c "echo HelloWorld > {compoundOutputFileLuid0}.txt"

3. Samples have been added to the LIMS.

Code example

The example Work with Processes/Steps is similar to this example. The differences are that this example has minimal input/output and posts a reference to a pre-defined EPP process-parameter.

Step 1. Identify the Sample

To run a process on a sample, you must first identify the sample to be used as the input to the process.

For this example, run the process on the first highlighted sample.

After you have identified the sample, you can use its LIMS ID to as a parameter for the script. The artifact URI is then used as the input in constructing the XML to POST and executing a process.

Step 2. Identify the Container

In addition, this example requires a container in which to store the results of the process execution. An example of how to do this is included in the Groovy script under Process Execution with EPP/Automation Support.

The following code block outlines this action and obtains the URI of the container for the process execution POST.

// Create a new container using the StreamingMarkupBuilder
def containerDoc = builder.bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(con: 'http://genologics.com/ri/container')
    mkp.declareNamespace(udf: 'http://genologics.com/ri/userdefined')
    'con:container'{
        'name'("HiSEQ POST${randomNumGen.nextInt()}")
        'type'(uri:"http://${hostname}/api/v2/containertypes/1", name:"96 well plate")
    }
}
// Post the new container to the API
containerNode = GLSRestApiUtils.xmlStringToNode(containerDoc.toString())
returnNode = GLSRestApiUtils.httpPOST(containerNode, containersListURI, username, password)
container96WellsURI = returnNode.@uri

NOTE: As shown in other examples, you can use StreamingMarkupBuilder to construct the XML needed for the POST.

Step 3. Construct and POST the XML to Execute the Process

You now have all the pieces of data to construct the XML for the process execution. The following is an example of what this XML looks like.

// Create the required URIs
processListURI = "http://${hostname}/api/v2/processes"
researcherURI = "http://${hostname}/api/v2/researchers/1"
analyteURI = "http://${hostname}/api/v2/artifacts/${inputAnalyeLIMSID}"
 
// Retrieve the Process-Type
processParamName = 'TestProcessParam'
processTypeNode = GLSRestApiUtils.httpGET(processTypeURI, username, password)
 
// Create a new process using the StreamingMarkupBuilder
def processDoc = new StreamingMarkupBuilder().bind {
    mkp.xmlDeclaration()
    mkp.declareNamespace(prx:'http://genologics.com/ri/processexecution')
    'prx:process'{
        'type'(processTypeNode.'@name')
        'technician'(uri:researcherURI)
        'input-output-map' {
            'input'(uri:analyteURI)
            'output'(type:'Analyte') {
                'location' {
                    'container'(uri:container96WellsURI)
                    'value'("A:1")
                }
            }
        }
        'input-output-map'(shared:'true') {
            'input'(uri:analyteURI)
            'output'(type:'ResultFile')
        }
        'process-parameter'(name:processParamName)
    }
}
// Post the process to the API
unresolvedProcessNode = GLSRestApiUtils.xmlStringToNode(processDoc.toString())
returnNode = GLSRestApiUtils.httpPOST(unresolvedProcessNode, "${processListURI}", username, password)
println GLSRestApiUtils.nodeToXmlString(returnNode)

Elements

Executing a process uses the processexecution (prx) namespace. The following elements are required for a successful POST:

• type - the name of the process being run

• technician uri - the URI for the technician that will be listed as running the process

• input-output-map - one input-output-map element for each pair of inputs and outputs

• input uri - the URI for the input artifact

• output type - the type of artifact of the output

If the outputs of the process are analytes, then the following elements are also required:

• container uri - the URI for the container the output will be placed in

• value - the well placement for the output

To use the configured EPP process, the process-parameter element is required. This element is the name of the configured EPP that is executed when this process is posted.

Requirements

The following elements that match the processParamName variable must exist in the system before the process can be executed:

• Process type

• Technician

• Input artifact

• Container

• EPP parameter

With analyte outputs, if there are no containers with empty wells in the system, you must create one before running the process.

The XML constructed must match the configuration of the process type. For example, if the process is configured to have both analytes and a shared result file as outputs, you must have the following:

• An input-output-map for each pair of analyte inputs and outputs.

• An additional input-output-map for the shared result file.

The name on the process execution XML must match one of the possibly declared EPP parameter names. This requirement is true for any EPP parameters.

Expected Output and Results

If the POST is Successful, then the process XML is returned.

In the following example, there are two <input-output-map> elements. The second instance has the output-generation-type of PerAllInputs. This element indicates that the result file is shared and only one is produced, regardless of the number of inputs.

<prc:process uri="http://localhost/api/v2/processes/ROB-QSK-110525-24-109084" limsid="ROB-QSK-110525-24-109084">
  <type uri="http://localhost/api/v2/processtypes/1979">robtype1</type>
  <date-run>2014-11-14</date-run>
  <technician uri="http://localhost/api/v2/researchers/11651">
    <first-name>John-Luck</first-name>
    <last-name> Pikkard </last-name>
  </technician>
  <input-output-map>
    <input post-process-uri="http://localhost/api/v2/artifacts/LIT2693A1SAM1?state=8564" uri="http://localhost/api/v2/artifacts/LIT2693A1SAM1?state=8562" limsid="LIT2693A1SAM1"/>
    <output uri="http://localhost/api/v2/artifacts/LIT2693A1RO10?state=8563" output-type="Analyte" limsid="LIT2693A1RO10"/>
  </input-output-map>
  <input-output-map>
    <input post-process-uri="http://localhost/api/v2/artifacts/ADM793A1PA1?state=3896" uri="http://localhost/api/v2/artifacts/ADM793A1PA1?state=3893" limsid="ADM793A1PA1"/>
    <output uri="http://localhost/api/v2/artifacts/ADM793A1RO2?state=3894" output-generation-type="PerAllInputs" output-type="ResultFile" limsid="ADM793A1RO2"/>
  </input-output-map>
  <process-parameter name="TestProcessParam"/>
</prc:process> 

If the POST is Not Successful, then the XML that is returned contains the error that occurred when the POST completed. The following example shows this error:

<exc:exception xmlns:exc="http://genologics.com/ri/exception">
  <message>The process type named 'HiSEQ POST' cannot produce the following types of shared outputs: 'ResultFile'.</message>
</exc:exception>

Attachments

ExecuteProcessWithEPP.groovy:

3KB

ExecuteProcessWithEPP.groovy

autocomplete-process.py:

3KB

autocomplete-process.py