Skip to main content

Modeling Sample and Pipeline Protocols

In this section

This section will help you:

  • Know what Sample and Pipeline Protocols are and when to use them.

  • Know what Sample Points and Pipeline buttons are and when to use them.

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

  • Know how to create new Protocol Actions.

Key Terms

Table 8. 

Term

Definition

Protocol

Sequence of steps performed on an Entity. Protocols define the data to collect while performing the Experiment.

Sample Protocol

Creates a child Entity or Item.

Pipeline Protocol

Launches a Pipeline.

Pipeline

Collection of Tasks (shell scripts) run on compute resources (cluster, cloud, or directly in L7|ESP).

Protocol Action

Behavior that is triggered when a Protocol is saved and at other key points in the life cycle of a Worksheet.



Sample Protocols

Sample Protocols have two (2) key components:

7.1.png

  1. The Entity Type must be selected and represents the child Entity that will be created. Only one (1) Entity Type can be selected for each Sample Protocol.

  2. The Parent-Child Relationship must be defined, there are three (3) options:

3112175552.png

  • 1-to-1 - each Entity in the upstream Protocol creates one (1) child Entity.

  • fan-in - multiple Entities in the upstream Protocol create one (1) child Entity.

  • fan-out - each Entity in the upstream Protocol creates multiple child Entities.

Warning

Sample Protocols can have shared (Protocol) fields, but they cannot be grouped.

The default fields Sample ID Sequence, Parent ID, Sample ID, and Note appear at the beginning of Sample Protocols.

Note

Parent ID is replaced with the Group field in fan-in Sample Protocols, covered in more detail below.

7.2.png

L7|ESP sets the Parent ID, User-provided Notes become the description of the newly created Entity.

The Sample ID Sequence field defines the ID Sequence that will be assigned to the child Entity or Item being created in the Sample Protocol.

Note

Sample ID Sequence and Sample ID are hidden by default in the LIMS Worksheet.

When an Item is created in a Sample Protocol, the following default fields are added to the Protocol: Initial Quantity, Lot ID, Serial ID, Status, Vendor, and Expiration.

7.4.png

The custom fields attributed to the newly created Entity or Item will be added after these default fields.

7.3.png

Note

These custom fields are managed in the Entity Types and Item Types builders, respectively.

Fan-in and fan-out Sample Protocols need additional data to create child Entities or Items.

Fan-in relationships have a Group field that is used to define how parent Entities or Items in the upstream Protocol are pooled together to create a new child Entity or Item.

7.6.png

Fan-out relationships have a Number of Children field that is used to define the number of child Entities or Items to create for each parent Entity or Item in the upstream Protocol.

7.5.png

Note

The values for Group and Number of Children can be specified via a data link or default value.

Sample Points

Sample Points are an alternate way to create child Entities that will not be used in the current Experiment.

Entities created in a Sample Point are not accessible in the current Worksheet.

This includes instances where the number of derived Entities may be zero (0), which cannot be achieved with a Sample Protocol. Sample Points also allow for child Entities to be created from more than one (1) Entity Type, and can be added to both Standard and Pipeline Protocols.

Warning

Sample Points cannot create Items.

To add a new Sample Point field:

  1. Select + Add Field

  2. Select Sample Point as the field type.

Under parameters:

7.7.png

  • Provide a button label for the Sample Point in the Worksheet.

  • Add the Sample Type(s) and the min and max number of Samples that should be created.

Note

Any number of Samples can be created, including zero (0). No action, by default, is taken for out-of-range values.

  • Optionally add an Additional Parents Expression to make Samples created in an upstream Sample Point parents of the Entities created in the current Sample Point. This can be accomplished with the cell expression: {{ cell('Upstream Sample Point Field ID', 'Protocol ID') }}

Pipeline Protocols

Pipeline Protocols have two (2) key components:

7.8.png

  1. The Pipeline. Only one (1) Pipeline can be selected in each Pipeline Protocol.

  2. The default Start button always appears before the Complete checkbox at the end of the Protocol.

When processing Entities in a Pipeline Protocol, the Pipeline is run by selecting the Start Pipeline button.

Once completed, the icon to the right of done or failed can be selected to view the metadata and reports associated with the Pipeline instance. For failed Pipelines, the modal will display the standard error and a button to resubmit the Pipeline.

Note

Upon completion, Pipeline Protocols complete the row and save the Worksheet.

Note

Pipeline development is out-of-scope for this class, but you can refer to L7U Module 6 or attend the Developer MasterClass to learn more about them.

Pipeline Buttons

Pipeline buttons associate a Pipeline with a field instead of the Protocol, allowing Protocol authors to add more than one (1) Pipeline to Standard and Sample Protocols. Shared (Protocol) fields and Var Groups can be leveraged to collapse multiple Pipelines into one (1) Protocol, separated by Var Group. The Unit Testing Workflow is an example of this.

7.12.png

Note

Upon completion, Pipeline buttons do not complete the row and save the Worksheet.

Pipeline buttons also provide Developers with more flexibility in how Pipeline variables are defined, instead of forcing a custom field-per-variable.

Warning

In time, Pipeline Protocols will be deprecated in favor of Pipeline buttons.

To add a new Pipeline button field:

  1. Select + Add Field

  2. Select Pipeline Button as the field type.

Under parameters:

7.9.png

  • Provide a button label before and after execution in the Worksheet.

  • Select the Pipeline. Only one (1) Pipeline can be selected.

  • Define the Pipeline’s variables (if applicable to the selected Pipeline).

Protocol Actions

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

Note

Actions can be added to Standard, Sample, and Pipeline Protocols.

7.10.png

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 conditions are added to the If section of the action. The actions to perform if the conditions are met are defined in the Then section. L7|ESP offers several out-of-box conditions:

Available Conditions in L7|ESP

Table 9. 

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.

All rows match an expression

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

Note

The expression is evaluated in LIMS context.

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.

Any rows match an expression

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

Note

The expression is evaluated in LIMS context

Entity added to worksheet

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

Entity removed from worksheet

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

Only once

The action is only triggered once for a satisfied condition.



The available out-of-box actions are listed below. "EE" means the value can contain Expressions. Unless otherwise noted, these Expressions are evaluated in the Protocol Action Expression Context.

Available Actions in L7|ESP

Table 10. 

Action

Description

Archive Objects

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

Note

To archive objects, the Role the End User is assigned to must have the following permission:

LIMS → Sample → Delete

Fail Samples

Fail the matching Entities (remove them from the current Experiment).

Notify Roles

Users in the specified Roles receive an L7|ESP notification.

It accepts the following parameters:

  • Roles - a case-sensitive list of Role names.

    • Control works like tags: type the name and hit enter to confirm.

  • Title - The notification title (EE).

  • Message - The notification message (EE).

Notify Users

The specified Users receive an L7|ESP notification.

It accepts the following parameters:

  • Users - a case-sensitive list of user names.

    • Control works like tags: type the name and hit enter to confirm.

  • Title - The notification title (EE).

  • Message - The notification message (EE).

Notify Workgroups

Users in the specified Workgroups receive an L7|ESP notification.

It accepts the following parameters:

  • Workgroups - a case-sensitive list of workgroup names.

    • Control works like tags: type the name and hit enter to confirm.

  • Title - The notification title (EE).

  • Message - The notification message (EE).

Start Workflow

Launches an Experiment using the specified Workflow for the condition-matching Entities.

It accepts the following parameters:

  • Workflow - Name of the Workflow to start (EE).

  • Project - Name of the Project to put the Experiment in (EE).

  • Experiment Name - Name of the Experiment to create (EE).

  • Tags - list of tags to add to the Experiment.

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

    • If this is empty, a Worksheet will not be created.

Start Workflow Chain

Launches an Experiment using the specified Workflow Chain for the condition-matching Entities.

It accepts the following parameters:

  • Workflow Chain - Name of the Workflow Chain to start (EE).

  • Project - Name of the project to put the Experiment in (EE).

  • Experiment Name - Name of the Experiment to create (EE).

  • Tags - list of tags to add to the Experiment.

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

    • If this is empty, a Worksheet will not be created.

Synchronize Field Value To Entity

Copies a value from a LIMS field to an Entity custom field for the current Sample Set 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 custom 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 tag is not on the entity, no change occurs.



Note

Developers can create custom Protocol Actions, which is a topic of the Developer MasterClass.

Protocol Action Expression Parameters

Table 11. 

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

Note

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.

Note

In L7|ESP version 3.0, this list will always be empty.

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.

Note

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.



Protocol Action Example

7.11.png
In this section: