•••
 
Documentation   /   Building workflows   /   Routing with filters and outcomes
 
 

Routing with filters and outcomes

 

Plainly decides which items to show using three directives: ---depends_on, ---outcome and filters.

The rule

An item shows in a task when either:

  • it has no ---depends_on, or
  • the item it depends on is showing and done, and that item's outcome is this item.

An item's outcome is:

  • the |outcome of the filter that matched its answer, if it has filters, or
  • its ---outcome, if it has no filters.

So every connection needs both halves:

--#item:
---id:step_a
---action:done
---title:Step A
---outcome:step_b

--#item:
---depends_on:step_a
---id:step_b
---action:done
---title:Step B

Step A names Step B as its outcome, and Step B names Step A in ---depends_on. If either half is missing, Step B never appears.

Always connections

An "always" connection uses ---outcome. The next item shows as soon as the earlier one is done.

Sometimes connections (filters)

A "sometimes" connection uses a numbered filter and outcome on the earlier item:

---filter1|filter:answer GREATER_THAN £10000
---filter1|outcome:needs_approval
---filter2|filter:answer LESS_THAN_OR_EQUALS £10000
---filter2|outcome:auto_approve

The filter has the form {what} {MATCH_TYPE} {value}. {what} is usually answer, the item's own answer. The match types are listed on Match types. Comparisons ignore case and currency symbols.

Rules for filters:

  • Number them filter1, filter2 and so on, each with a matching |outcome.
  • An item with filters ignores its plain ---outcome.
  • If no filter matches, nothing follows that item.
  • Make filters cover every possible answer, without overlapping. If more than one matches, the last matching filter wins.
  • For a question, filter on the answer text exactly as written in ---answerN|text.

Parallel items

Items without ---depends_on show as soon as the task starts, so several can run in parallel:

--#item:
---id:collect_id
---title:Upload ID
---action:attachment

--#item:
---id:collect_bank
---title:Enter bank details
---action:text_input

Joining branches back together

An item can only depend on one item, and an item can only have one outcome at a time. To bring branches back together, use a Blocker (stop action). A Blocker holds back every item listed after it until the items before it are done. Items after the Blocker don't need ---depends_on.

--#item:
---id:branch_a
---title:Branch A step
---action:done

--#item:
---id:branch_b
---title:Branch B step
---action:done

--#item:
---id:wait_for_both
---title:Waiting for earlier steps
---action:stop
---options:done_at
---block:true

--#item:
---id:final_step
---title:Final step
---action:done

See Flow control actions for Blocker options.

Blocking a single item

---block:true on any item stops later items in the list from being completed until that item is done. It's simpler than a Blocker when you just need "do this first".

For AI builders

Routing checklist for every workflow you write:

  • Every ---outcome:X and ---filterN|outcome:X names an item with ---id:X that has ---depends_on: set to the item naming it.
  • Every ---depends_on:Y names an earlier item whose outcome, or one of whose filter outcomes, is this item.
  • No item has both a plain ---outcome and filters.
  • Filters on one item don't overlap, and together they cover every answer (for numbers, pair GREATER_THAN x with LESS_THAN_OR_EQUALS x).
  • Where branches must reconverge, either duplicate the shared tail items in each branch (with a shared ---alias) or use a stop item with ---options:done_at.
  • Items that should appear immediately have no ---depends_on.