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.

Prerequisites

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.

Code example

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.

Step 1. Create Sample Node List

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.

Step 2. Retrieve Workflow URIs

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}
} 

Step 3. Build and POST the Unassignment XML

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)
} 

Configuring and Running the Automation

Automations can be configured and run using Clarity LIMS

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.

   • 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 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.

   

Expected Output and Results

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

Attachments

UnassignSamplesFromWorkflows.groovy:

4KB

UnassignSamplesFromWorkflows.groovy