Skip to main content

Extending the functionality of Protocols (Steps) using Protocol Actions

Goals

  • Know what Protocol Actions are and when to use them.

  • Know how to add an action to a Protocol.

  • Know what conditions and actions are available in L7|ESP.

Key Terms

Table 43. 

Term

Definition

Protocol Action

Custom behavior triggered when a condition is satisfied while processing a Protocol.



Introduction

Protocol Actions extend the functionality of Protocols (Steps) by adding custom behaviors that are triggered when the Protocol is saved. While onChange is similar, these events are triggered on the front-end without saving the Protocol. onChange is often used for UI-based calculations and validations. Protocol Actions should be used when conditions trigger logic on the back-end. Data is pushed to the back-end when the Protocol is saved.

Protocol Actions

Add an action by navigating to the Actions tab and selecting + Add Action.

master_add_protocol_action_3_4.png

Note

Protocol Actions are supported in L7 LIMS, L7 MES, and L7 Notebooks.

Each action has a name and description – these fields are used in error reporting and logging, and are useful for documenting the intent of the action.

The condition is defined in the if section and the action to perform if the condition is satisfied is defined in the then section.

More than one (1) condition can be added to an action, especially if the action should only be triggered once. In this event, use the + icon to the right of the conditions picklist to add only once.

More than one (1) action can also be added, assuming they are satisfied by the same condition(s). If not, add a separate action by selecting + Add Action.

Available Conditions in L7|ESP

Table 44. 

Condition

Definition

All rows completed

The action is triggered if all Entities are completed during the save.

All rows rejected

The action is triggered if all Entities are rejected in a Signature Flow.

N/A to L7 MES. Signatures denote approval.

All rows match an expression

The action is triggered if all Entities evaluate True for the supplied expression.

Any row completed

The action is triggered if any Entity is completed during the save.

Any row rejected

The action is triggered if any Entity is rejected in a Signature Flow.

N/A to L7 MES. Signatures denote approval.

Any rows match an expression

The action is triggered if any Entity evaluates True for the supplied expression.

Entity added to worksheet

The action is triggered if one (1) or more Entities are added to the Worksheet.

N/A to L7 MES. Additional Entities cannot be added to the Batch Record.

Entity removed from worksheet

The action is triggered if one (1) or more Entities are failed in the Worksheet.

N/A to L7 MES. This is synonymous with failing the Batch.

Only once

The action is only triggered once for a satisfied condition.



Available Actions in L7|ESP

The available out-of-box actions are listed below. "EE" means the value can contain expressions. These expressions are evaluated in the Protocol Action expression context (see the parameters table below).

Note

Developers can create custom Protocol Actions, which is a topic of Server-Side Development.

To register, please visit L7 University.

Table 45. 

Action

Description

Archive Objects (remove from UI)

Archives the matching objects (e.g., consumed Entity or Item, multi-well plate).

  • The expression must resolve to a:

    • UUID.

    • Dictionary with a UUID key.

    • List of UUIDs or dictionaries with UUID keys.

  • For example, using {{ cell('Field ID') }}

    • Archive Entities in the Protocol based on the value of a field in the Protocol.

    • Archive an object selected in a resource link field.

  • To archive objects, the Role the user is assigned to must have permission to delete that object:

    • Inventory & Billing → Container → Delete

    • Inventory & Billing → Item → Delete

    • LIMS → Sample → Delete

* If an Expression is not provided, Entities that match the condition in the Protocol (including Containers and Items if they are submitted to Experiments) will be archived.

Create MES Batch

Creates a new Batch in L7 MES.

The Protocol that this action is added to should have the following fields:

  • Free-form text entry to enter a Batch name.

    • The Batch name must be unique in L7 MES.

  • Resource link of type "MESProduct" to select the Product for the Batch.

  • Resource link of type "Workflow Chain Version" to select the Recipe for the Product.

    • The Product must be linked to the Recipe in L7 Entities.

master_batch_action_fields_3_4.png

In the action itself, these fields are referenced using the following expressions:

  • Batch name – {{ cell('Field ID') }}

  • MES Product – {{ json_loads(cell('Field ID'))['displayText'] }}

  • Workflow Chain Version – {{ resource_link_uuid(cell('Field ID')) }}

master_batch_action_3_4.png

DEPs can be selected in the Protocol with additional resource link fields, and referenced in the action using {{ resource_link_uuid(cell('Field ID')) }}

Fail Samples

Removes the matching Entities from the current Experiment.

* This action should not be used in L7 MES. Batches are failed from the Quality Review tab.

Notify Roles

Sends an L7|ESP notification to users in the specified Role(s).

It accepts the following parameters:

  • Roles – case-sensitive list of roles.

  • Title – notification title (EE).

  • Message – notification message (EE).

Notify Users

Sends an L7|ESP notification to the specified User(s).

It accepts the following parameters:

  • Users – case-sensitive list of users.

  • Title – notification title (EE).

  • Message – notification message (EE).

Notify Workgroups

Sends an L7|ESP notification to users in the specified Workgroup(s).

It accepts the following parameters:

  • Workgroups – case-sensitive list of workgroups.

  • Title – notification title (EE).

  • Message – notification message (EE).

Start Workflow

Creates an Experiment using the specified Workflow for the matching Entities.

It accepts the following parameters:

  • Workflow – name of the Workflow to start (EE).

  • Project – name of the existing Project to add the Experiment to (EE).

  • Experiment Name – name of the Experiment to create (EE).

  • Tags – list of tags to add to the Experiment (optional).

  • Worksheet Name – name of the Worksheet to create (EE). All Entities from the newly-created Experiment will be added to the Worksheet.

* If no Worksheet name is provided, the Entities will remain in the LIMS backlog.

Start Workflow Chain

Creates an Experiment using the specified Workflow Chain for the matching Entities.

It accepts the following parameters:

  • Workflow Chain – name of the Workflow Chain to start (EE).

  • Project – name of the existing Project to add the Experiment to (EE).

  • Experiment Name – name of the Experiment to create (EE).

  • Tags – list of tags to add to the Experiment (optional).

  • Worksheet Name – name of the Worksheet to create (EE). All Entities from the newly-created Experiment will be added to the Worksheet.

* If no Worksheet name is provided, the Entities will remain in the LIMS backlog.

Start MES Workflow Chain

Submits the current Batch to a downstream Recipe.

* This action should only be used in L7 MES.

The Protocol that this action is added to should have a resource link field of type "Workflow Chain Version" to select the downstream Recipe to submit the Batch to.

master_recipe_action_fields_3_4.png

In the action itself, this field is referenced using the following expression:

  • Workflow Chain Version – {{ resource_link_uuid(cell('Field ID')) }}

master_recipe_action_3_4.png

DEPs can be selected in the Protocol with additional resource link fields, and referenced in the action using {{ resource_link_uuid(cell('Field ID')) }}

Synchronize Field Value To Entity

Copies a value from a LIMS field to an Entity custom field for the current Entities in the Protocol.

It accepts the following parameters:

  • Source Field – ID of the LIMS field to copy the value from.

  • Target Field – ID of the Entity field to copy the value to.

Tag Row Samples

Adds the specified tag(s) to the matching Entities.

* If the Entity is already tagged, no change occurs.

Untag Row Samples

Removes the specified tag(s) from the matching Entities.

* If the Entity does not have the tag, no change occurs.



Protocol Action Expression Parameters

Table 46. 

Parameter

Description

affected_samples

A list of Entity names that "match" the condition(s).

For the condition "All Row Completed" and action "Notify Users", the message might say:

{{ ", ".join(affected_samples) }} have completed {{ workflow }}

affected_rows

Like affected_samples, but a list of LIMS row objects instead of Entity names. This is for advanced use-cases where you need to access specific Protocol field data, such as: {{ ",".join([x.get_value('My Field ID') for x in affected_rows]) }}

* For efficiency, only values in the active Protocol can be referenced.

tab_rows

All rows in the active Protocol.

tab_samples

List of Entity names for all Entities in the active Protocol.

completed_samples

List of Entity names for all rows that were completed during this Worksheet save.

uncompleted_samples

List of Entity names for all rows that were uncompleted during this Worksheet save.

failed_samples

List of Entity names for all rows that were failed in this request.

unfailed_samples

List of Entity names for all rows that were un-failed in this request.

approved_samples

List of Entity names for all rows that were approved in this request.

unapproved_samples

List of Entity names for all rows that were unapproved in this request.

* Rows are unapproved if data is modified post-approval.

added_samples

List of Entity names for rows that were added to the Worksheet in this request.

removed_samples

List of Entity names for rows that were removed from the Worksheet in this request.

sheet

Worksheet name.

workflow

Workflow name.

protocol

Active Protocol name.

active_user

Name of the user who initiated the request.



In this section: