Remove Samples from Workflows

In Clarity LIMS, derived sample automations are automations that users can run on derived samples directly from the Projects Dashboard.

The following example uses an automation to initiate a script that removes multiple derived samples from workflows. The example also describes the main functions included in the script, and shows how to configure the automation in Clarity LIMS and run it from the Projects Dashboard.

For more information on creating automations, 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.

Before removing samples from the workflows, make sure you have the following items:

• A project containing at least one sample assigned to a workflow.
• A step has been run on a sample, resulting in a derived sample.
• The derived sample is associated with one or more workflows.

The attached UnassignSamplesFromWorkflows.groovy script uses the derived sample automations feature to remove selected derived samples from their associated workflows. The following actions must be done when removing samples from these workflows.

This 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. A for-each loop on the derived sample list makes a GET call for each sample and creates the sample node list. The following command-line example shows how the getSampleNodes function works:

def getSampleNodes(sampleList, hostname, username, password){

sampleURIList = sampleList.collect{"${hostname}v2/artifacts/${it}"}

return sampleNodeList = GLSRestApiUtils.batchGET(sampleURIList, username, password)

}

This list is used to retrieve the sample URIs and the workflow-stage URIs. These URIs are required to build the unassignment XML.

A sample can be associated with one or many workflows, and each derived sample has a list of the workflow-stages to which it is assigned. Making a GET call on each workflow-stage URI retrieves its XML representation, from which the workflow URI can be acquired and added to a list. The getWorkflowURIs function calls for each sample node included in the list (eg, sampleURIList, username, and password from Step 1: Create Sample Node List).

The for loop does the following actions:

1. Makes a GET call for each workflow-stage to which the passed sample is assigned.
2. Retrieves the associated workflow URIs.
3. Returns a list containing all URIs for the workflows with which the sample is associated.

def getWorkflowURIs(sampleNode, username, password){

return sampleNode.'workflow-stages'?.'workflow-stage'.collect\

{GLSRestApiUtils.httpGET(it.@uri, username, password).workflow.@uri}

}

Now that the functions used to retrieve both the derived sample URIs and the workflow URIs have been built, you can use StreamingMarkupBuilder to create the XML and then POST to the unassignment URI. This process can be done with the unassignSamplesFromWorkflows and unassignSamplesXML functions.

To unassign the derived samples, you can POST to the artifacts URI at ${hostname}v2/route/artifacts. Nested loops create the declaration for each sample and their associated workflows. The following example shows the declaration built in the format of the workflow URI, with the unassign flag followed by the URI of the sample being unassigned.

def unassignSamplesFromWorkflows(sampleNodeList, username, password) {

def builder = new StreamingMarkupBuilder()

builder.encoding = "UTF-8"

def unassignSamplesXML = builder.bind{

mkp.xmlDeclaration()

mkp.declareNamespace(rt: 'http://genologics.com/ri/routing')

'rt:routing' {

//Dynamically build XML using a for loop for each sampleNode

sampleNodeList.each{ sampleNode ->

//Generates the URI list for each sample

workflowUriList = getWorkflowURIs(sampleNode, username, password)

workflowUriList?.each{

'unassign'('workflow-uri': it){

'artifact'(uri: sampleNode.@uri)

}

}

}

}

}

return GLSRestApiUtils.xmlStringToNode(unassignSamplesXML.toString())

}

Now that the XML is built, convert the XML to a node and post it as follows.

1. Use GLSRestApiUtils to convert the XML to a node.
2. POST the node using the following command:

unassignSampleNode = unassignSamplesFromWorkflows(sampleNodeList, username, password)

//Try the post

try {

unassignSampleNode = GLSRestApiUtils.httpPOST(unassignSampleNode, unassignmentURI, username, password)

}

Automations can be configured and run using Clarity LIMS (v4.x and earlier to v5 and later).

For Clarity LIMS v4.2 or earlier, add and configure the automation as follows.

1. In the Clarity LIMS Web Interface, select Configure.
2. Select Automation.
3. 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, Remove From Workflows).
• 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 Action.

For Clarity LIMS v5 or 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, Remove from Workflows).
• 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 Remove From Workflows automation created in the previous step.

The API of the selected samples now shows an additional workflow stage with a status of REMOVED.

UnassignSamplesFromWorkflows.groovy.txt