Branching routes each record through different steps depending on conditions — for example, sending new customers to a create import and existing ones to an update import — inside a single tool. This article shows integrator.io users how to add a branching to a tool, name and order its branches, define the conditions, and reorder steps on the canvas. It's for anyone whose tool needs more than one path between input and output.
Important
Prerequisites: Add lookups and imports to a tool. Branches route records to steps, so add the steps first or as you go.
How branching works in a tool
- Every branching uses First matching branch: a record follows the first branch, in order, whose conditions it meets, and no other. Order your branches from most specific to least specific.
- A branch with no conditions accepts every record, so put it last as the catch-all.
- Every branch must end at Tool output.
- A tool can contain up to 25 branchings, and each branching can contain up to 25 branches.
A tool without branching routes every record along one path, shown on the canvas as a branch named default. A new branching starts with two branches, Branch 1.0 and Branch 1.1.
Add a branching
- Go to AI studio, and then select Tools.
- Select the tool.
- Select Add step after the step where the paths should split, and then select Add branching. The Add branching editor opens (it's titled Edit branching when you reopen it).
- Enter a Branching name. Long names are truncated on the canvas; hover to see the full name.
- Under Define branch rules, rename Branch 1.0 and Branch 1.1, and select + Branch for each additional branch (named Branch 1.2, Branch 1.3, and so on until you rename them). Drag a branch by its handle to reorder it; the number at the left is the order records are evaluated in.
- In a branch, select + Condition to add a rule, or + Add group to group rules. Leave one branch without conditions to catch records that match nothing else. For the rule editor, see Branching in API builder — the editor is the same.
- Select Preview to evaluate the Input record and see which branch it takes in Output, and then select Save & close.
The branching appears on the canvas as a router with one dotted line per branch, each labeled with its name. Select Add step on a branch to add steps to it.
To define conditions with a script instead of rules, select JavaScript at the top of the editor, choose a Script (or select + to create one), and keep the Function name branching unless your script exports a different function. The branches you named under Rules still apply. During a test run, the input record includes testMode: true, so a script can tell a test from a real invocation.
To remove the branching and its branches, select Delete branching in the editor.
Reorder steps on the canvas
Drag a step to another position on the canvas, including into another branch. The step's mappings and filters move with it, but they were built against the previous position's data, so open the step and check its mapping after you move it.