Triggers

Trigger Types

Once

"Once" triggers run the node just one time during the flow. This is the default trigger, so it does not need to be specified.

Use this trigger when a command needs to run only one time during a flow.

flows:
  default:
    nodes:
      A:
        target: sleep-and-echo
      B:
        target: sleep-and-echo
      C:
        target: sleep-and-echo

targets:
  sleep-and-echo:
    commands: |
      sleep 1
      echo "Hi from {{ id }}!"

flowchart TD
  A(A)
  B(B)
  C(C)

After

"After" triggers run the node after some other nodes have completed.

Use this trigger when a node depends on the output of another node.

• After object
  • after array[string] ○ The IDs of the nodes to wait for.

flows:
  default:
    nodes:
      A:
        target: sleep-and-echo
      B:
        target: sleep-and-echo
      C:
        target: sleep-and-echo
      D:
        target: sleep-and-echo
        triggers:
        - after: [A, B]
      E:
        target: sleep-and-echo
        triggers:
        - after: [C]
      F:
        target: sleep-and-echo
        triggers:
        - after: [D, E]

targets:
  sleep-and-echo:
    commands: |
      sleep 1
      echo "Hi from {{ id }}!"

flowchart TD
  A(A)
  B(B)
  C(C)
  D(D)
  A --> D
  B --> D
  E(E)
  C --> E
  F(F)
  D --> F
  E --> F

Restart

"Restart" triggers run the node every time the node is completed.

Use this trigger when you want to keep the node's command running.

• Restart object
  • delay number (Default: 1) ○ The delay before restarting the command after it exits.

flows:
  default:
    nodes:
      A:
        target: sleep-and-echo
        triggers:
        - delay: 3
      B:
        target: sleep-and-echo
        triggers:
        - delay: 1

targets:
  sleep-and-echo:
    commands: |
      sleep 1
      echo "Hi from {{ id }}!"

flowchart TD
  A(A)
  A -->|∞ 3s| A
  B(B)
  B -->|∞ 1s| B

Watch

"Watch" triggers run the node every time one of the watched files changes (directories are watched recursively).

Use this trigger to run a node in reaction to changes in the filesystem.

• Watch object
  • watch array[string] ○ The paths to watch for changes. Directories are watched recursively.

flows:
  default:
    nodes:
      A:
        target: sleep-and-echo
        triggers:
        - watch: ["synthesize/", "tests/"]
      B:
        target: sleep-and-echo
        triggers:
        - watch: [ "docs/" ]

targets:
  sleep-and-echo:
    commands: |
      sleep 1
      echo "Hi from {{ id }}!"

flowchart TD
  A(A)
  w_e00c7e8478b60649551a53dd05f75842[("synthesize/
tests/")]
  w_e00c7e8478b60649551a53dd05f75842 -->|👁| A
  B(B)
  w_49e56c817e5e54854c35e136979f97ca[("docs/")]
  w_49e56c817e5e54854c35e136979f97ca -->|👁| B

Using Multiple Triggers

Example: Restarting on Completion or Config Changes

Synthesize uses mkdocs for documentation. mkdocs comes with a built-in command mkdocs serve to watch for configuration and documentation changes and rebuild the site in response, but it doesn't automatically restart the whole process when hooks are changed. Since hooks are imported Python code, the mkdocs process needs to be restarted when they change in order to pick up changes to them.

However, if the hooks (or any other configuration) are malformed, mkdocs will exit with an error on startup. If we were just running mkdocs serve by hand on the command line, we would have to manually restart it every time we changed the hooks, potentially multiple times if we are debugging.

To get a hands-off developer flow to enable fast iteration cycles, we want the following things to all happen:

• If mkdocs exits (for any reason), restart it.
• If any of the hook files changes, restart mkdocs.
• If neither of those happen, let mkdocs serve keep running forever.

This is straightforward to express with Synthesize by using both restart and watch triggers for a target that run mkdocs serve (which blocks):

flows:
  default:
    nodes:
      docs:
        target:
          commands: mkdocs serve --strict
        triggers:
        - delay: 1
        - watch: ["docs/hooks/"]

flowchart TD
  docs(docs)
  docs -->|∞ 1s| docs
  w_4d475cb3916a7348ab85e5bf7180b6fa[("docs/hooks/")]
  w_4d475cb3916a7348ab85e5bf7180b6fa -->|👁| docs