Requeue Samples
Derived sample automations are automations that users can run on derived samples directly from the Projects Dashboard in Clarity LIMS.
The following example uses an automation to initiate a script that requeues samples to an earlier step in the workflow. The example also describes the main functions included in the script and demonstrates the configuration options that prompt the user for input. These options allow for greater flexibility during script runs. Before you follow the example, make sure that you have the following items:
| • | A project containing samples assigned to a multi-stage workflow. |
| • | Samples that must be requeued. These samples must have completed at least one step in the workflow and must be available for requeue. |
For more on creating automations in Clarity LIMS, refer to the following documents:
| • | For Clarity LIMS v4.1 or v4.2, refer to the Samples section of Adding Automation Actions for Derived Samples. |
| • | For Clarity LIMS v5 and later, refer to the Clarity LIMS Core Functionality documentation. |
Code Example
The purpose of the attached RequeueSamples.groovy script is to requeue selected derived samples to a previous step in the workflow with the derived sample automations feature.
Step 1: Get Sample Nodes
The getSampleNodes function is passed a list of derived sample LIMS IDs (as a command-line argument) to build a list containing the XML representations of the samples. The resulting sample URI list can then be used with a batchGET to return the sample nodes:
def getSampleNodes(sampleList, hostname, username, password){
sampleURIList = sampleList.collect{"${hostname}v2/artifacts/${it}"}
return GLSRestApiUtils.batchGET(sampleURIList, username, password)
}
Step 2: Retrieve Workflow and Stage URIs
To retrieve the workflow name, you can URL encode the workflow name and use the result to query and retrieve the workflow URI:
encodedWorkflowName = java.net.URLEncoder.encode(workflowName, "UTF-8")
try {
workflowURI = GLSRestApiUtils.httpGET\
("${hostname}v2/configuration/workflows?name=${encodedWorkflowName}", username, password).workflow.@uri[0]
if (!workflowURI) {
throw new Exception()
}
} catch (Exception e) {
println "Unable to find workflow: " + workflowName
System.exit(-1)
}
The stage names are guaranteed to be unique for each workflow. However, they may not be unique in the Clarity LIMS system. As a result, the stage URI cannot be queried for in the same way as the workflow URI.
Instead, you can navigate through the workflow node to find the stage that matches the stage name specified using the getStageURI function. If a match is found, return the stage URI.
def getStageURI (workflowURI, stageName, username, password) {
def stageURI
GLSRestApiUtils.httpGET(workflowURI, username, password).stages.stage.find {
if (it.@name.toString().equals(stageName)) {
stageURI = it.@uri
return true
}
}
if (stageURI) {
return stageURI
}
Step 3: Verify Each Sample Meets Requeue Criteria
Next, you must make sure that each sample meets the criteria to be requeued using the canRequeue function. The following method checks all workflow stages for the samples:
| • | If a match is found between a workflow stage URI and the stage URI specified, the sample node is added to a list of samples that can be requeued using the requeueList function. |
| • | If all the samples have this match and a status that allows for requeue, the list is returned. Otherwise, the script exits with an error message that states the first sample to cause failure. |
def canRequeue(nodeList, stageURI){
def Set conditions = ["REMOVED", "FAILED", "COMPLETE", "SKIPPED"]
def requeueList = []
def lastStageRun
nodeList.each{ sampleNode ->
sampleNode.'workflow-stages'?.'workflow-stage'.each {
if (it.@uri.toString().equals(stageURI)) {
lastStageRun = it
}
}
if (conditions.contains(lastStageRun?.@status.toString())) {
requeueList.add(sampleNode)
} else {
println "Sample: " + sampleNode.@limsid.toString() + " cannot be queued to stage " + stageName
System.exit(-1)
}
}
return requeueList
}
Step 4: Check and Retrieve Workflow Stage for Sample Node
In this example, both unassignment from and assignment to a workflow stage must occur to complete the requeue. As the samples are requeuing to a previous stage in the workflow and can currently be queued for another stage, you must remove them from these queues.
The getCurrentStageURI and lastStageRun functions check the sample node for its most recent workflow stage. If the node is in a queued status, it returns that stage URI to be unassigned.
def getCurrentStageURI(sampleNode, workflowURI) {
def lastStageRun
sampleNode.'workflow-stages'?.'workflow-stage'.each {
stageWorkflowURI = GLSRestApiUtils.httpGET(it.@uri, username, password).'workflow'.@uri[0]
if (stageWorkflowURI.toString().equals(workflowURI.toString())) {
lastStageRun = it
}
}
return (lastStageRun.@status.toString().equals('QUEUED')) ? lastStageRun.@uri.toString() : null
}
Step 5: Build the XML Assignment
Using the previous methods and their results, the following code uses Streaming Markup Builder and the assignmentXML function to build the XML to be posted:
def assignmentXML = builder.bind {
mkp.xmlDeclaration()
mkp.declareNamespace(rt: 'http://genologics.com/ri/routing')
'rt:routing' {
requeueList.each { sampleNode ->
currentURI = getCurrentStageURI(sampleNode, workflowURI)
if (currentURI) {
'unassign'('stage-uri': currentURI) {
'artifact'(uri: sampleNode.@uri)
}
}
'assign'('stage-uri': stageURI) {
'artifact'(uri: sampleNode.@uri)
}
}
}
return GLSRestApiUtils.xmlStringToNode(assignmentXML.toString())
}
The returned XML node is then posted using httpPOST.
Configure and Run the Automation
Automations can be configured using Clarity LIMS v4.1, v4.2, or v5 and later.
For Clarity LIMS v4.1 or v4.2, add and configure the automation as follows.
| 1. | In the Clarity LIMS Web Interface, select Configure. |
| 2. | Select Add Action and enter the following information: |
| • | Action Name—This is the name that displays to the user running the automation from the Projects Dashboard. Choose a descriptive name that reflects the functionality/purpose (eg, Requeue Samples). |
| • | Channel Name—Enter the channel name. For more information, refer to Automation Channels. |
| • | Command Line—Enter the command line required to invoke the script. |
In the example Command Line, note the –w and -t {userinput} options. The derived sample automation allows for user input as a command-line variable.
| 3. | Select Save Action. |
For Clarity LIMS v5 and later, add and configure the automation as follows.
| 1. | In Clarity LIMS, under Configuration, select the Automation tab. |
| 2. | Select the Derived Sample Automation tab. |
| 3. | Select New Automation and enter the following information: |
| • | Automation Name—This is the name that displays to the user running the automation from the Projects Dashboard. Choose a descriptive name that reflects the functionality/purpose (eg, Requeue Samples). |
| • | Channel Name—Enter the channel name. For more information, refer to Automation Channels. |
| • | Command Line—Enter the command line required to invoke the script. |
| 4. | Select Save. |
Run the automation as follows.
These steps are applicable to Clarity LIMS v4.x or earlier and v5 or later.
| 1. | Open the Projects Dashboard. |
| 2. | Select a project containing in-progress samples. Select In-progress samples. |
In the sample list, you see the submitted and derived samples that are currently in progress for this project.
| 3. | Select one or more derived samples. |
Selecting samples activates the Action button and drop-down list.
| 4. | In the Action drop-down list, select the Requeue Samples automation. |
In this example, the –w and -t {userinput} options invoke a dialog box on automation trigger. The user is required to enter two parameters: the full name of the stage and the workflow for which selected samples are to be requeued. The names must be enclosed in quotation marks.
Expected Output and Results
If the requeue is successful, each requeued sample is marked with a complete tag. Hovering over a sample shows a more detailed message.
