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.

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 ([e-mail]().equals(stageName)) {
            stageURI = it.@uri
            return true
        }
    }
    if (stageURI) {
        return stageURI
    } 

Step 3. Verify Each Sample Meets the 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 ([e-mail]().equals(stageURI)) {
                lastStageRun = it
            }
        }
        if (conditions.contains(lastStageRun?[e-mail]())) {
            requeueList.add(sampleNode)
        } else {
            println "Sample: " + [e-mail]() + " 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 ([e-mail]().equals('QUEUED')) ? [e-mail]() : 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.

Configuring and Running the Automation

Add and configure the automation

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.

   • Command Line—Enter the command line required to invoke the script.

   
4. Select Save.

Run the automation as follows.

1. Open the Projects Dashboard.

2. Select a project containing in-progress samples. Select In-progress samples.

   

   In the sample list, you will see all of 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.

Attachments

RequeueSamples.groovy:

1KB

RenamingSample.groovy