Skip to main content

Modeling Sample and Pipeline Protocols

Goals

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

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

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



Sample Protocols

Sample Protocols have two (2) key components:

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

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

master_sample_protocol_default_item_fields_3_3.png

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

master_sample_protocol_entity_fields_3_3.png

Note

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

They cannot be edited in the Protocol builder.

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.

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

master_sample_protocol_fan_out_3_3.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:

master_sample_point_field_3_3.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:

master_pipeline_protocol_components_3_3.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 are covered in more detail in the Client-Side Developer MasterClass.

To register, please visit L7 University.

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 fields and grouping can be leveraged to collapse multiple Pipelines into one (1) Protocol, organized by group. The Unit Testing Workflow is an example of this.

lims_pipeline_protocol_3_3.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 buttons will likely replace Pipeline Protocols.

To add a new Pipeline button field:

  1. Select + Add Field

  2. Select Pipeline Button as the field type.

Under parameters:

master_pipeline_button_field_3_3.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 and selecting + Add Action.

Note

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

master_new_protocol_action_3_3.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 condition is defined in the If section and the action to perform if the condition is satisfied is defined in the Then section. L7|ESP offers several out-of-box conditions and actions:

Available Conditions in L7|ESP

Table 15. 

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.

* The expression is evaluated in L7 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.

* The expression is evaluated in L7 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.



Available Actions in L7|ESP

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 (see the parameters table below).

Table 16. 

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:

    • UUID

    • Dictionary with a UUID key

    • List of UUIDs or dictionaries with UUID keys

  • To archive objects, the Role the user is assigned to must have the following permission:

    • LIMS → Sample → Delete

Fail Samples

Removes the matching Entities from the current Experiment.

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

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 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 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 Server-Side Developer MasterClass.

Protocol Action Expression Parameters

Table 17. 

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.



Protocol Action Example

In this Protocol, Platelets are being tested for bacterial contamination and stored. Lab Managers need to know which Platelets passed the test.

master_protocol_action_example_3_3.png
In this section: