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 uses the identical assert system used for validating actions, see here.

  - name: GetUser2
    run_when_finished: [GetUser1] # you should typically ensure the actions that run_on_assertion depends on are finished 
    run_on_assertion: #<---! this is used for asserting any of the prior actions before starting this one
      tests:
        - action: GetUser1
          value: .name
          is_equal_to: "Ervin Howell"
    http: 
      url: https://jsonplaceholder.typicode.com/users/2
      headers:
        content-type: application/json
    assert: # this is used for asserting the data you fetched from this action itself
      tests:
        - value: .body.name
          is_not_null: true

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.