Adding a trigger

Running tasts sequencially is a fundamental ability of ecFlow. This task sequencing can be enforced by using a trigger. Triggers are used to declare dependencies between two tasks e.g. a task needs data created by another task.

For example, when task t2 processes data produced by task t1, a trigger can be used to enforce this dependency.

When ecFlow tries to start a task, the trigger expression is evaluated, and if the condition evaluates to “true” the task is started, otherwise the task remains queued.

Triggers can be specified between tasks, between families, or any mixture of these. Remember the two rules:

A family is complete when all its tasks are complete.
A task will be started if its triggers and the triggers of all is parent families evaluate to true.

Each node can only have one trigger expression, but very complex expressions can be built (and keep in mind that the triggers of the parent nodes are also implicit triggers).

Sometimes triggers can also be used to prevent too many jobs from running at the same time. For these cases, making use of a limit (covered later Limits section) tends be a better solution.

Trigger expressions can refer to nodes using full names or, in some contexts, relative names (such as ../t1). Considering the ongoing example,

/test/f1/t1 refers to the task t1.
/test/f1 refers to the family f1.

An example of a simple trigger expression is:

trigger /test/f1/t1 == complete

Triggers expressions can be very complex, as ecFlow supports all kinds of conditions (not, and, or, …). In addition, trigger expressions can also reference Node attributes like event, meter, variable, repeat and generated variables.

Update Suite Definition

Consider the following suite definition, with a trigger added to task t2 to ensure that it only runs once t1 is complete.

# Definition of the suite test.
suite test
   edit ECF_INCLUDE "{{HOME}}/course" # replace '{{HOME}}' appropriately
   edit ECF_HOME    "{{HOME}}/course"
   family f1
     edit SLEEP 20
     task t1
     task t2
         trigger t1 eq complete
   endfamily
endsuite

The trigger expression can be checked, this is especially important when dealing with very large suites and complex triggers.

Listing 26 $HOME/course/test.py

import os
from ecflow import Defs, Suite, Family, Task, Edit, Trigger


def create_family_f1():
    return Family(
        "f1", Edit(SLEEP=20), Task("t1"), Task("t2", Trigger("t1 == complete"))
    )


print("Creating suite definition")
home = os.path.join(os.getenv("HOME"), "course")
defs = Defs(Suite("test", Edit(ECF_INCLUDE=home, ECF_HOME=home), create_family_f1()))
print(defs)

print("check trigger expressions")
check = defs.check()
assert len(check) == 0, check

print("Checking job creation: .ecf -> .job0")
print(defs.check_job_creation())

print("Saving definition to file 'test.def'")
defs.save_as_defs("test.def")

What to do

Modify the suite definition to include the trigger, as shown above.

Replace the suite, using:

ecflow_client --suspend /test
ecflow_client --replace /test test.def

python3 test.py
python3 client.py

Inspect the tasks in ecflow_ui.
Observe the triggers by selecting task t2.
Observe the trigger relation by opening the Trigger tab.
Search any reference to t1 by using the search menu.
(Optional) Using the Python API, introduce an error in the trigger expression and observe that this error is detected. For example, change the trigger to:
```
Trigger("t == complete")  # Error: no node with name `t`
```