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:

autocomplete-process.py:

Automations (formerly referred to as EPP triggers or automation actions) allow lab scientists to invoke scripts as part of their workflow. These scripts must successfully complete for the lab scientist to proceed to the next step of the workflow.

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.

Automations have various uses, including the following:

• Workflow enforcement—Makes sure that samples only enter valid protocol steps.

• Business logic enforcement—Validates that samples are approved by accounting before work is done on them. This automation can also make sure that selected samples are worked on together.

• Automatic file generation—Automates the creation of driver files, sample sheets, or other files specific to your protocol and instrumentation.

• Notification—Notifies external systems of lab progress. For example, you can notify Accounting of completed projects so that they can then bill for services rendered.

Configuration

You can enable automations on master steps in two configuration areas of Clarity LIMS:

• On the Automations tab, when adding/configuring an automation. See the Adding and Configuring Automations article in the Automations section of the Clarity LIMS documentation.

• On the Lab Work tab, on the master step configuration form. See the _Adding & Configuring Master Steps and Step_s article in the Steps and Master Steps section of the Clarity LIMS documentation.

After it is enabled on a master step, the automation becomes available for use on all steps derived from that master step.

You can configure the automation trigger on the master step, or on the steps derived from that master step.

Script messages

Progress message

While executing a script, if more than one script would be triggered for a single user action, they are reported in sequence. This reporting continues until all scripts complete, or one of them fails.

An example scenario would be a step that is configured to execute the following:

• One script upon exit of the Placement screen.

• A second script upon entry of the Record Details screen.

In this scenario, when the lab scientist advances their protocol step from the Placement screen to the Record Details screen, the scripts are executed in sequence.

The parameter string/automation name configured on the master step is displayed in a progress message. You can use this feature by giving your parameter strings/automations meaningful names that provide you with context about what the script is doing. The following is an example of a progress message.


You cannot proceed until the script completes successfully.

Non-responsive scripts

You can request to cancel a script that is not responsive. While canceling abandons the monitoring of script execution, it does not stop the execution of the script.

After canceling a script, follow up with the Clarity LIMS administrator to determine if the AI node/automation worker must be restarted.

Non-Blocking Success and Warning Message

The scientific programmers in your facility can provide you with a message upon successful execution of a script. There are two possible non-fatal messages: OK and WARNING. These messages can be set using the step program status REST API endpoint.

Message boxes display the script name, followed by a message that is set by the script using the step program status REST API endpoint. Line breaks are permitted in the custom message. The following is an example of a success message:

After you select OK, you are permitted to proceed in the workflow.

Blocking Script Failure Message

When a script fails, a message box displays. There are two ways to produce fatal messages:

• By using the step program status REST API endpoint (informing FAILURE as the status)

• By generating output to the console and returning a non-zero exit code.

For example, when beginning a step, if the script does not allow you to work on the samples together in Ice Bucket, the samples will be returned to Ice Bucket after acknowledging the error message. In this case, the step is prevented from being tracked. The following is an example of a failure message:

If you attempt to advance a step from the Pooling screen, but an error is detected, the error state prevents you from continuing. The following is an example of this type of message:

After you select OK, you are prevented from proceeding in the workflow. Instead, you must return to the Pooling screen and address the problem before proceeding.

You can configure the automation trigger and use automation to invoke any external program that runs from a command line. Refer to the following for details:

• Automation Trigger Configuration

• Process Execution with EPP/Automation Support

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.