Feature: Workflows

Modified on Tue, 01 Feb 2022 at 05:36 PM

TABLE OF CONTENTS

Setting-up a Laboperator Workflow:
Using Workflows in Laboperator:

Note: Like any other Resource, you can edit, share, move, and delete Workflows.

Setting-up a Laboperator Workflow:

General concepts

Workflow Templates and Workflow Runs

Workflows in Laboperator provide a powerful tool to orchestrate devices and data with information and control elements which enable lab scientists to create a digital twin of their processes in the laboratory. Workflows operate as a connecting layer between the device integration layer harmonizing device interfaces, commands and data and the API layer which provides data, commands and resources in a unified format to third parties. Workflows can be utilized to provide the full scope of functionalities of a Laboratory Execution System (LES).

Workflows are defined and described in Workflow Templates, which can then be instantiated via execution as Workflow Runs. Workflow Templates are authored as YAML files and can be uploaded and shared by any roles within an organisation and collection which have the required privileges. Once uploaded, Workflow Templates exist as resources in a collection and can be executed by any roles with the required privileges. Changes and parameterization of the Workflow Templates is only possible within the degrees of freedom defined and allowed in the YAML file.

The procurement and instantiation lifecycle of Workflow Templates, Workflow Step Templates and Workflow Runs is outlined below:

Since Workflows are highly customizable and can be arbitrarily complex, this chapter aims at giving a high-level overview of the hierarchical structure and general principles of Workflow templates. It is meant to provide an orientation to the Workflow Template Schema which provides additional detail and functional information.

YAML-file based templating

As a data serialization language that is both human-readable and machine-readable, YAML is the optimal format to allow the authoring of both simple and complex workflows using a predefined schema for defining appearance, functionality and logic within a workflow.

YAML files can be regarded as a script which is then executed by the Laboperator server as an interpreting engine.

Schema definition

All Workflow Templates have a UUID and a Version which is unique to an organization within Laboperator, meaning that a YAML file with the same UUID and Version cannot be added if the same combination of UUID and Version already exists within the Organization. YAML template files also have a distinct structure which is explained on a high level in what follows.

The complete YAML schema definition for Workflows can be found here.

Dynamic workflows and Workflow steps

In addition to defining entire Workflows within a Workflow Template, modular steps can be defined as Workflow Steps, which can be added to and combined into Workflows both at design time and at run time. Examples for Workflow Templates may i.e. be a dissolution test, where a weighing step for the sample to be dissolved may be represented by a Weighing Step, which may then be re-used within other workflows and protocols.

Workflow Step templates can be uploaded, managed and executed the same way as Workflow templates. They also share similar schemata and can be enriched by Workflow elements in the same way.

Details on the schema definitions can be found here:

Design-time loading of Workflow Steps

When designing a Workflow Template as a YAML file, Workflow Steps can be added to the Workflow Template by referencing the UUID and Version as the unique identifiers of a Workflow Step Template. All properties of the Workflow Step Template are then defined in a separate unique resource representing the Workflow Step Template.

When running a Workflow Run with an underlying Workflow Template to which a Workflow Step Template has been referenced, it is required that the executing operator has the access and privileges required to load and execute the template, otherwise, an error will be raised.

Additional details on design-time loading of Workflow Steps can be found in the AddStep Events and Options schema definitions.

Run-time loading of Workflow steps

At run time, Workflow steps which have previously been uploaded and shared as Workflow Step Templates within an Organization or Collection can be appended (i.e. added to the end) to a Workflow Run that is not finalized or locked.

Workflow template structure and hierarchy

On a high level, a Workflow Template YAML file can be divided in three parts: Header, Content Elements, Step Definitions and Flow.

The YAML file header contains all workflow metadata that is summarized in the Info Section schema.

Content Elements

On a high-level, Content Elements comprise all Workflow elements which harbor data in the forms of Fields, Arrays and Tables. Once defined at this hierarchical level, they are available as global variables in the entire workflow.

Step Definitions

Step definitions list the different steps, in which all the user interface (UI) Elements encapsulated which make the data visible and controls available to the user. These include, but are not limited to images, buttons, visualization elements like gauges or line graphs, input fields, dropdown menus and many more. Workflow Steps are also usually the place where behaviors (consisting of triggers and actions) are managed as well as calculations and scripts.

Within steps, variables can also be locally defined as Fields. Locally defined Fields are not available outside the scope of a step.

Flow

In the Flow section, the Workflow Template YAML file defines the sequential order in which the Workflow Steps in the previous sections are executed during the Workflow Run. Conditional and branching logic can be defined in the flow section as well.

Additional information can be found in the Flow Section schema description.

Workflow elements

This chapter summarizes a high-level overview of visual, functional, logic and UI elements that can be utilized within a Workflow Template YAML file. For a complete overview and additional details, please refer to the Laboperator Workflow Schema Index.

Workflow Element	High-level description	Schema Reference
Fields	Fields can be used on a global level and within Step Definitions to store variables and data points. Formatting options exist and they can be used as variables, inputs and display option.	Link
Context Info	Context Info can be used to display static and dynamic information in a viewport which is available during the entire Workflow and can be collapsed and expanded.	Link
Navigation Elements	Navigating to the previous or next step, repeating steps	Link
Media & Content	Different media (i.e. images and videos) as well as in-built data displays (i.e. gauges) can be displayed in a Workflow Step or Substep	Link Media Link
Behaviours	Bahaviours can be used to execute actions (i.e. send command to device, send alert, next step etc.) in response to triggers (i.e. temperature above threshold, button pressed, step started etc.) Find more details on a selection of triggers and actions in the table below. A complete list of available actions and triggers can be found in the linked schema description.	Link Triggers Link Actions
Alerts	Alerts can be raised as an action and can be defined in terms of broadcasting channel according to the linked schema.	Link
Webhooks	Webhooks can be fired off as an action as a response to a trigger. Webhook URLs have to be authorized by an organisation administrator.	Link
Timers	Timers can be used as countdown or as forward counting timers. They can both be controlled by triggers, and can trigger actions by themselves.	Link
Scans	Registered scanners can set off triggers in workflows as well in addition to acting as a keyboard.	Link
Calculations	Arithmetic calculations can be used as part of a script field to calculate values from constants and values from other fields.	Link
Buttons	Buttons can be used to manually trigger actions within a workflow.	Link
Tables	Tables can be used to structure data simplify the workflow navigation for end users	Link
Elements	Data elements allow to render data from device channels on substep or within the context info panel	Link
Devices	Devices can be displayed on substeps with general information, status and activities such as invoked commands	Link

Triggers and Actions

All behaviours in workflows follow a when (trigger) do (action) logic. The tables below list all triggers and actions available.

Info: Triggers can also be combined with logic operators using AND between the when and do part of a behaviour. 

Example
when: on_substep_start
and: my_value > 1
do: complete_substep

Trigger (when)	Description
on run pause	triggered, when a workflow run is paused
on run resume	triggered, when a workflow run is resumed
on run complete	triggered, when a workflow run is completed
on run start	triggered, when a workflow run is started
on run lock	triggered, when a workflow run is locked
on step start	triggered, when a step is started
on step complete	triggered, when a step is completed
on on device status update	triggered, when the status of a device is updated (e.g. from online to offline)
on substep start	triggered, when a substep is started
on substep complete	triggered, when a substep is completed
on timer start	triggered, when a timer is started
on timer complete	triggered, when a timer is completed
on timer reset	triggered, when a timer is reseted
on scan	triggered, when a scan is executed
on command response	triggered, when a command from a specific device is responded (e.g. complete)
on data point	triggered, when a data point from a specific device is provided (e.g. from a wheight channel)
on field update	triggered, when a specific field is updated (e.g. a field is set with a value from a device)
on manual	triggered, when a button with a specific key is pressed by the user

Action (do)	Description
add step	adds a step with a specific uuid and version
alert	displays a pop up window in the user interface that notifies the end user
go to previous step	sets the flow to the previous step
go to step	jumps to the step indicated by uuid and version
notify	displays a notification in the down left corner of the user interface
send command	sends a command to a device
select row	selects a specific row of a table
select cell	selects specific cell of a table
set field	sets a value to specific field
webhook	executes a webhook
complete step	completes the current step
repeat step	repeats the current step
start substep	starts the current substep
complete substep	completes the current substep
repeat substep	repeats the current substep
start timer	starts the timer of the substep
stop timer	stops the timer of the substep
reset timer	resets the timer of the substep
complete timer	completes the timer of the substep
confirm alert	confirms an alert

Flow and flow control

In the Flow Section of the Workflow Template YAML file, the sequential flow of steps and substeps as defined in the Step descriptions section can be defined as described in the Flow Section Schema.

Additional options for conditional flow and loops are listed in a high-level overview below.

Option	Description	Reference
Sequential Flow	As a default option, sequential flow describes in the sequential order in which steps defined within the workflow or loaded into the workflow are executed.	Link
Parallel Flow	Parallel flow allows the parallel execution of nested sequences. Additional information can be found in the linked schema.	Link
While Flow	Within a While Flow, steps or sequences of steps can be repeated as long a predefined condition is met. More details are described in the linked schema.	Link
Loop Flow	Within a While Flow, steps or sequences of steps can be repeated until a predefined condition is met. More details are described in the linked schema.	Link
If-Then-Else Flow	An IF-Then-Else Flow allows the conditional branching of sequential flow. Additional details can be found in the linked schema.	Link
For-Each Flow	A For-Each Flow repeats a certain sequence with a predefined set of conditions, either a series of integers or a predefined data array. Additional details can be found in the linked schema.	Link For-Each Integer Link For-Each Array

Using Workflows in Laboperator:

Uploading/downloading Workflow or Step Templates

Laboperator workflows are built on workflow templates or workflow step templates which are file based workflow descriptions. To upload a template click on the +ADD button on the navigation menu and select Workflow Template or Workflow Step Template. You can also choose the collection you want to upload the template to.

Note: You can upload a template with the same uuid and version only once.

Once uploaded, a template can be shared, moved, edited, delted etc. like any other resource in Laboperator. To download the YML-file of a template double click on the template and open the download tab in the context menu. You can also view a versions history in the context menu of a template.

Creating a Workflow Run from Workflow Templates

From a workflow templates you can create workflow runs that can be executed. Double click on the workflow Ttmplate and click on the start new workflow run button. The workflow run will open automatically. Beside, the workflow run will be available as a resource in my collection. Alternatively you can create a workflow run using the +ADD-button in the navigation menu and select Workflow Run. Choose start from uploaded template and select the template you want to create the workflow run from.

Parameterizing and starting a Workflow Run

After creating a workflow run you see the parameter page where you can parameterize the workflow run to a certain extend. Parameters which are marked with a * are mandatory before the workflow run can be started. After all mandatory parameters are set you can start the execution of the workflow run by clicking on start.

Executing a Workflow Run

After starting a workflow run you see the execution view of the workflow. Within the section of the navigation menu the different workflow steps are listed. You can hide the list by clicking on the menu button in the top left corner of the header. The content section displays the sub-steps and guides you through the workflow. Various actions can be implemented here, for example manual instruction or an automated data capturing from a device.

Pausing, Completing, Closing and Reopening a Workflow

In the top right corner of the header you find several buttons to control the workflow run. With x you can leave the execution view and return to the parameter page. From here you can navigate to all other Laboperator resources and functionalities and return to your active workflow run later. To reopen a workflow run open the corresponding resource and click on open execution view. This can even be done after completing a workflow run.

If you pause the workflow using the pause button within the execution view or on the parameter page the current workflow run will be paused. After pausing a workflow run you can restart it using the play button.

Clicking on the double tick will complete the workflow run right away, even if it's not yet completely worked through. If you have reached the end of a workflow run you’ll be asked to complete the run or add another step. If you complete the run you can exit the execution view by clicking on done or using the x in the top right corner.

Repeating Steps and Sub-Steps

While a workflow run is active (not paused) you can repeat steps or substeps by clicking on the corresponding buttons on the header.

Locking a Workflow Run

workflow runs can be locked at any time from the parameter page or within the execution view. A click on the lock button opens a window to confirm the locking.

Note: After locking the Workflow Run it can't be altered or edited anymore. Locking the workflow run can't be undone.

Comment Feature

On the right side of the execution view you can comment your workflow run. To open the sidebar click on the speech-bubble button. You can even add links or pictures to your comments.

Adding Workflow Steps at runtime

If you have access to workflow step templates you can add steps at runtime. Click on the add step button in the bottom left corner of the navigation menu. Now you can select the steps you want to add. You then might parameterize the step and click on add step. The new step will be added at the end of the steps in the navigation menu and you can adjust the order using drag and drop functionality. Also at the end of a workflow you will be asked if you want to add another step.

Creating a Workflow Run from Workflow Step Templates

Beside starting a workflow run from a workflow template you can create your own workflow using workflow step templates. Click on the +Add button in the navigation menu and select workflow run. Choose start from blank template, insert a title and click on submit. You can further select the collection you want to add the workflow run to.
After creating the blank template you can open it from the collection you created it in. When starting the workflow run a list of available workflow steps is shown. Select and parameterize the steps at your will and click the start button in the top right corner.