Protocol Actions Guide
Protocol actions allow protocol authors to add behaviors to protocols that are executed when the protocol is saved and at certain other key points in the life cycle of a worksheet.
Configuring Protocol Actions
You add an action by navigating to the Actions tab of the protocol builder and clicking the + Add Action button.
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 or conditions are added in the If section of the action. The actions to perform if the conditions are met are defined in the Then section.
The available out-of-box conditions are:
All rows completed - the action is triggered in a protocol if all rows are complete, as long as one or more rows was completed during the save.
All rows match an expression - the action is triggered if all rows evaluate to true for the supplied expression. The expression is evaluated in LIMS context.
Any row completed - the action is triggered in a protocol if any row is completed during the save.
Any rows match an expression - the action is triggered in a protocol if any rows match the expression. The expression is evaluated in LIMS context.
Only once - the action is only triggered once for a given row match, see "Understanding Protocol Action Processing" for more information.
The available out-of-box actions are listed below. In this list, the "(EE)" means the value can contain expressions. Unless otherwise noted, those expressions are evaluated in the Protocol Action Expression Context.
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). If this is empty, a Worksheet will not be created. If it is not empty, all Entities from the newly-created Experiment will be added to the Worksheet.
Start Workflow Chain - Launches an Experiment using the specified WorkflowChain 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). If this is empty, a Worksheet will not be created. If it is not empty, all Entities from the newly-created Experiment will be added to the Worksheet.
Synchronize Field Value To Entity - Copies a value from LIMS to an Entity custom field. 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.
Understanding Protocol Action Processing
Each action has one or more conditions and one or more actions that are triggered when all of the configured conditions for the action are met. L7|ESP checks whether actions should be evaluated when Entities are added a Worksheet, removed for a Worksheet, when a Worksheet is saved, when Worksheet entities are failed, and when Worksheet entities are approved.
Note that L7|ESP will only process actions for Worksheet protocols that started or ended "active" (has one or more actionable Entities). An actionable Entity is one that can be completed or failed. For each action, L7|ESP will evaluate every action condition against each row in the Worksheet protocol and collect the set of rows that pass all specified conditions. If one or more rows pass the condition, the action will be executed once against the set of all passing rows. Figure 1 shows where protocol actions fit into a typical worksheet save operation.
In general, for all operations where actions may be performed, the actions are the last OOB piece of the processing.
Figure 2. shows the logic used when processing actions.
The following examples illustrate these concepts.
Example 1
Setup:
Protocol Action Condition: "any row is completed"
Protocol Action: The action is "send a notification"
Scenario Starting Point: A Worksheet with 10 Entities is open with all ten active in the configured protocol.
When:
The user clicks "Complete" for the first Entities and saves. One Alert will be sent, with the first Entity as the "affected" Entities.
The user clicks "Complete" for the next 9 Entities and saves. One Alert will be sent for the remaining nine Entities as the "affected" Entities.
The user clicks "Uncomplete" for the first three entities and saves. Then the user clicks "Complete" again for the first three entities and saves again. One alert will be sent for those three entities.
Example 2
Setup:
Protocol Action Condition: "any row is completed" and "Only Once"
The same as Example 1 for everything else.
When:
The user clicks "Complete" for the first Entities and saves. One Alert will be sent, with the first Entity as the "affected" Entities.
The user clicks "Complete" for the next 3 Entities and saves. One Alert will be sent for the these three Entities as the "affected" Entities because an alert has not yet been sent for any of these entities.
The user clicks "Uncomplete" for the first three entities and saves. Then the user clicks "Complete" again for the first three entities and saves again. No alert will be sent for those three entities because we already alerted for all three.
The user clicks "Uncomplete" for the fourth entity and saves. The the user clicks "Complete" for that entity again and clicks "Complete" for the remaining six entities. An alert will be sent for the remaining six entities but not for the "recompleted" samples since it was included in a previous alert.
Example 3
Setup:
Protocol Action Condition: "all rows complete"
Protocol Action: "send a notification"
A worksheet witih 10 entties is open with 8 samples complete and 2 uncomplete
When:
The user clicks "Complete" for the 9th sample and saves, no notification is sent because all samples are not complete.
The user clicks "Complete" for the 10th sample and saves, one notification is sent for all samples in the sheet since all samples are now complete.
The user clicks "Complete" for one sample in the _next_ protocol: no notifications are sent because the initial and final state of the protocol with the action was inactive, so the actions weren't checked.
The user clicks "Uncomplete" in the protocol for one sample: no notifications are sent because not all samples are complete, but the action _is_ checked since the final state of the protocol is "active"
The user clicks "Complete" for the sample uncompleted just before: a notification is sent for all samples since all samples are now complete (again).
Example 4
Setup:
Protocol Action Condition: "all rows complete" _and_ "Only Once"
Protocol Action: "send a notification"
A worksheet witih 10 entties is open with 8 samples complete and 2 uncomplete
When:
The user clicks "Complete" for the 9th sample and saves, no notification is sent because all samples are not complete.
The user clicks "Complete" for the 10th sample and saves, one notification is sent for all samples in the sheet since all samples are now complete.
The user clicks "Complete" for one sample in the _next_ protocol: no notifications are sent because the initial and final state of the protocol with the action was inactive, so the actions weren't checked.
The user clicks "Uncomplete" in the protocol for one sample: no notifications are sent because not all samples are complete, but the action _is_ checked since the final state of the protocol is "active"
The user clicks "Complete" for the sample uncompleted just before: no notifications are sent since a notification has previously been sent for all samples
Protocol Action Expression Context
Many protocol actions allow users to make use of ESP expressions. Currently, the evaluation context for these expressions is slightly different from the regular LIMS context, so functions that depends on LIMS context may not be used, or may only be used by providing additional parameters (such as "entity_uuids") that are not usually required for LIMS expressions. However, the context provides a useful set of extra information for protocol actions:
affected_samples- A list of the names of entities that "matched" the conditions. For instance, for a rule "any sample completed" and action "send user notification", the message might say:Completed samples {{", ".join(affected_samples)}} in workflow "{{ workflow }}", protcol "{{ protocol }}".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, which can be done as, e.g.:{{ ",".join([x.get_value('My Field ID') for x in affected_rows]) }}. Note that for efficiency, only values in the acting protocol can be referenced.
tab_rows- All rows in the active protocol.
tab_samples- List of entity names for all entiteis 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 unfailed in this request. Note, in L7|ESP 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 (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.