Skip to main content

Flow control

Control whether and when each action runs — order actions, gate them on others' success or failure, retry, delay, and branch. Also known as workflow control.

View complete examples here.​

There are 4 key options:

  • run_when_succeeded
  • run_when_failed
  • run_when_finished(aliasdepends_on`)
  • run_on_assertion

For the first 3 options you can define this in one of two ways:

run_when_succeeded: [previous, anotherAction]
run_when_succeeded: 
  at_least: 1
  actions: [previous, anotherAction]

For run_on_assertion this uses the identical assert system used for validating actions, see here. The tests read a prior action (action: or action_value:) or a request value (custom_value: a|body::type|). The action being gated has not run yet, so it has no data of its own to test. When the condition does not hold, the action is skipped, not failed.

- name: Lookup
  json_output: '{"valid": true}'
- name: Charge
  run_on_assertion:
    tests:
      - action: Lookup
        value: valid
        is_equal_to: true
  json_output: '{"charged": true}'

A gate waits for an action declared above it that it reads, so it needs no run_when_finished. It reads that action whether it succeeded or failed, since a failed action keeps its payload. To require success as well, add run_when_succeeded: [Lookup]. Before Air Pipe 3.16.1 a gate did not wait: without run_when_finished: [Lookup] it read Lookup before it had run and skipped every time.

When a branch does not apply​

run_when_failed on an action whose dependency succeeded means "this branch does not apply". That is a clean skip, not a failure: the action carries no error, contributes nothing to the interface's error status, and its own dependents skip in turn — exactly how run_when_succeeded treats a skipped dependency.

- name: Pay
  http: {url: https://api.example.com/payments, method: POST}

- name: Confirm
  run_when_succeeded: [Pay]      # runs when Pay succeeded

- name: Refund
  run_when_failed: [Pay]         # runs when Pay failed; skipped cleanly otherwise

Only an unresolvable gate is an error — naming an action that does not exist in the interface.

This matters when you set http_code_fallback_strategy: any_action: the unused half of a branch must not report the whole request as failed.