The trigger
A playbook’s trigger decides which accounts it watches. It is the same rule builder segments use, on the same fields — properties, traits from every namespace, aggregates and indicators — so a trigger and the segment it is meant to behave like cannot drift apart. That includes the change-over-time conditions, so a playbook can watch for a number falling rather than for a number being low. Open a playbook and click the Trigger card at the top of the canvas. Its settings open in the panel beside it, with the same counting choice segments have:
Customers is the default, and it matters more here than on a list. Counting accounts on a customer with three accounts runs the playbook three times and creates three of whatever the steps create.
Preview matches runs against what’s on screen rather than what’s saved, so you can check an edit before it acts on anyone. It reports how many accounts the trigger catches and names the first twenty. Worth using before switching anything on — a trigger that quietly matches your whole book is easier to spot in a list of names than in a number.
Publishing changes
Editing a playbook does not change what it is doing. Your edits are saved as you make them, as an unpublished draft, and the playbook goes on running the version it was already running until you publish. A bar appears at the bottom of the canvas while anything is unpublished, naming what has changed and who changed it. It has two buttons:- Review and publish opens a summary of what a publish would do: the steps added, removed or changed, any step whose runs would now go somewhere different, what the settings were and would become, and — when the trigger has changed — how many accounts it would enroll against how many it enrolls today.
- Discard throws the unpublished changes away and leaves the playbook running what it is running.
A live playbook will not publish a step that still needs its settings, or a trigger with no conditions — the same two
things that stop one switching on. A paused playbook publishes either way, because it cannot act on anyone.
Switching one on
New playbooks are always created switched off. Turn one on from the list, or from the On/Off button in the playbook itself. Three things stop a playbook switching on: unpublished changes, a step that still needs its settings, and a trigger with no conditions in it. A playbook with an empty trigger enrolls nobody, so switching it on would look like it was running while doing nothing at all. A playbook you have built but not published has nothing to run yet, so publish first, then switch it on.Building the flow
A playbook is drawn on a canvas, in the order a run reaches its steps: the trigger at the top, then each step under the one before it.
- Add a step with the + on any line. The list of steps opens in the panel beside the canvas, and the step you pick opens there straight away so you can fill in its settings.
- Edit a step by clicking its card. Its settings open in the side panel; on a phone the panel takes the whole screen. Changes save to the draft as you make them.
- Remove a step with the trash icon on its card or at the top of its panel. The steps either side of it join up.
- Duplicate a step with the copy icon at the top of its panel. See Duplicating below.
- Undo and redo with the arrows at the top left of the canvas, or ⌘Z and ⇧⌘Z. See Undo and redo below.
- Move around by scrolling or by dragging the background. Pinch, or scroll with ⌘ or Ctrl held, to zoom. Fit shows the whole playbook at once, and as a flow grows wider than the screen the canvas zooms out to keep it in view.
Moving steps
Drag a step’s card onto one of the highlighted spots that appear: between two steps, at the top of a path, or where paths meet. It goes in there, and the gap it leaves closes up.- Hold Shift while you drag to bring every step below it in its path along, down to where the path ends or meets the others. The banner at the top of the canvas says how many come with it.
- Move in a step’s panel does the same without dragging, which is the way to do it from a keyboard or a phone. Choose a highlighted spot, and tick and the steps below it to bring those too. Esc cancels.
- A branch always moves with its paths and everything on them.
- What moves keeps its settings and its counters, and if it lands mid-path, the path carries on afterwards to whatever was there before.
Duplicating
Duplicate at the top of a step’s panel puts a copy straight after the step, with the same settings, and opens the copy so you can change what needs changing.- A branch is copied with every path and every step on them. The copy goes where the original’s paths meet, or, if they never meet, below the paths that end. A path that jumps on to another step keeps jumping there, in the original and in the copy.
- A branch whose every path jumps on to other steps cannot be duplicated, because nothing comes after it for the copy to go into.
- To copy one path, use the copy icon on its card in the branch’s panel. The copy has the same rules, the same name with “(copy)” after it, and a copy of every step on it. It is checked straight after the path it came from, so until you change its rules no account takes it: every account it matches has already taken the original.
Undo and redo
The arrows at the top left of the canvas undo and redo your changes to the steps: adding, removing, moving and duplicating them, and what you change in a step’s settings. ⌘Z and ⇧⌘Z do the same (Ctrl+Z and Ctrl+Y on Windows), except while you are typing in a field, where they undo your typing instead.- Each undo saves to the draft like any other change, so nothing goes live until you publish. Discard is different: it throws away every unpublished change at once.
- The history covers your visit to the playbook. It starts again if you discard the draft, or if someone else’s changes to the steps arrive while you have it open.
- Changes to the trigger are not part of it.
What a step can do
These are the steps that act on an account.
A step still missing its settings is marked Needs setup on its card, and a playbook cannot be switched on while one is.
Two more steps shape the run rather than act on an account. Both sit under Shape the run in the list the + opens.
Wait
A wait holds the run before the steps below it reach the account.
A wait-until also takes a give up after in days, so a run is released even if the rules never match. It is optional — but a wait-until with no rules and no maximum holds every run that reaches it for good, so a wait in that state is marked Needs setup.
Split into branches
A branch sends a run down one of several paths. The canvas draws each path as its own column, in the order they are checked, with Otherwise last. A run takes the first path whose rules it matches, so the paths read as an if / else-if chain, and Otherwise catches a run that matched none of them. Click a path’s name to set its rules. Build down a path with the + under its name. The steps you put there run only for accounts that took that path. When paths carry on to the same step, the canvas draws them meeting above it, and the + where they meet adds a step that every one of those paths goes through. A branch you add partway down a playbook starts out that way: every path goes on to the step that followed, so nothing changes for any account until you put steps on a path. A branch added at the very end starts with every path ending. The branch’s own panel holds its paths:
Where a path goes when it ends. Every path finishes at an End, or carries on at another step. Click the End and choose Carry on at another step to send runs on instead. The step the other paths meet at is picked for you, which is how a path rejoins them, and the canvas then draws it joining them; pick any other step and the End becomes Carries on at, naming it. However a path finishes, Then at the bottom of its last step’s panel, and under each path in the branch’s panel, says where it goes and lets you change it. Only steps that cannot lead back to the path are offered, because a path pointing up the flow would send runs through steps they have already had, again on every check.
Removing a branch asks which path’s steps to keep. That path’s steps move up to where the branch was and the others go with the branch. Until you publish, Discard brings them back. A branch with nothing on any of its paths goes without asking.
Two states are marked Needs setup, because both quietly end runs rather than misbehaving visibly: a branch whose paths and Otherwise all end the run, and a path with no rules. A path with no rules matches everything, which makes every path after it unreachable.
Steps no path reaches
A step nothing leads to is drawn off to the right of the flow, under Not reached by any path. It never runs. Remove it, or send the end of a path on to it.Create a task
Due is a number of days counted from when the step runs, because the same step reaches different accounts on different days. Leave it empty for no due date. The title and description fill in per account. See Inserting values below. Tasks are credited to the account’s CSM, or to the connection’s owner when an account has no CSM. A playbook is not a person, and a task has to have come from someone. If the account has no CSM yet, the step asks your assignment rules there and then rather than waiting for the next sweep — so a step does not quietly do nothing while an account waits to be given an owner.Update a trait
Pick a trait, then what to do to it. What is offered depends on the trait’s type:- The day the step runs is that day in the timezone of your organization’s business hours, not the server’s.
- Moving a date starts from the date the account has. An account with no date set is skipped and the trait stays empty. Months and years keep the day of the month where they can: a month after January 31 is the last day of February.
- Keep moving it until it’s after the day the step runs is for renewals. When moving a date later, tick it and a date several periods behind catches up in one step: a monthly contract date from March 2024 moves straight to the next one still to come. Every move is counted from the date the account had, so the day of the month holds. Monthly from January 31 runs February 28, March 31, April 30. Without it, a date that’s still in the past after one move keeps matching the trigger, and the playbook doesn’t run that account again until it stops matching.
- Adding to a number counts an account with no value yet as 0.
- Adding an option an account already has, or taking off one it does not have, changes nothing on that account.
- Clearing removes the value, the same as clearing it on the account page. Leaving a value empty no longer clears a trait; a step with no value chosen is marked Needs setup.
- Dates are written as calendar days, the same as a date typed on the account page.
- If a trait’s type is changed after a step was set up, a change that no longer fits fails on each account the step reaches, and the panel asks you to choose again.
Date.addMonths(zudo.renewalDate, 12) works out a date from the renewal date your pipeline shows. A formula that cannot be worked out on an account fails that step for that account and the run carries on, rather than writing a broken value.
Show an NPS survey
Invites the account’s people to the NPS survey. It does not show anything itself — a playbook runs on a schedule, and a survey has to appear in front of somebody who is actually there — so the survey appears the next time one of them opens your product. What the step is for is skipping the cadence. “Renewing in two weeks” means asking now, whether or not they answered three months ago, so each of the survey’s rules can be waived independently:
Nobody is asked twice in one day whatever you tick. The step also takes how long the invitation lasts, and an optional
replacement question so a renewal playbook can ask a renewal-shaped one.
With no settings at all it invites the account under your ordinary rules, which is a working step.
By default an invitation only adds to the audience. If you want the survey shown to nobody except accounts a
playbook has invited, turn on Require a playbook invitation in Settings → NPS survey.
Call a webhook
Give the step an https URL. When the step runs, Zudo posts JSON naming the playbook, the step and the account. The playbook and the account are named by their Zudo ids, such asacc_k3m9x2pq4r8tvw7n, which the API accepts wherever it takes an id, so account.id is what you pass to GET /api/v1/accounts/{accountId}. externalId is your own id for the account, as your integration sent it:
X-Zudo-Signature header — sha256= followed by an HMAC of the exact body, so your endpoint can tell a real call from anyone who learned the URL. Leave it empty and the call goes unsigned.
A call gives up after 10 seconds. A timeout, a dropped connection or a 5xx is retried once; a 4xx is taken as your endpoint saying no and is not retried. A call that fails either way fails that step for that account, with the reason in the step’s counters, and the run carries on to the next step.
Inserting values
Anywhere a step takes text — a task’s title and description, a flag’s title — you can drop in a value that is filled in per account when the step runs. Type{{ and a searchable list opens with everything your organization has. Arrow keys move, Enter or Tab inserts, Escape closes it and leaves the braces alone. There is also a { } button in the corner of the field, which types the braces for you.
Inserted values show as a highlighted pill so a title reads as a sentence. A pill that turns red is a value Zudo does not recognize — usually a path with a character missing — and it will fill in as nothing rather than as an error.
So
{{account.name}} — renewal on {{trait.current_contract_expiration}} becomes “Acme — renewal on November 4, 2026”.
The list includes the Zudo traits, what Zudo knows about every account without anything connected: {{trait.zudo.renewalDate}} is the date the Renewals page shows, {{trait.zudo.lastActiveAt}} when the account was last active, {{trait.zudo.healthScore}} its health score.
When an account has nothing for it
A value the account does not have leaves an empty space, and “Renewal on ” reads as a mistake. Say what to put instead with a| before the closing braces:
user.<name> and smart traits as smart.<name>, which is what the list inserts for you.
Values are read when the step runs, not when you write it. A step that waits two weeks before creating a task writes
the MRR as it is two weeks from now.
What happens to a step’s work when an account leaves
Every step that creates something carries a setting: keep what this step did, the default, or undo it when the account leaves the playbook.
Keeping is the default because a playbook’s work outlives the run that made it: a task someone has acted on should not vanish underneath them. A flag is the opposite — it describes a condition, so when the condition clears and the account leaves, closing it is usually what you want.
Each undo is recorded on the run, so it is never a silent change.
How often it runs, and when accounts leave
Both live under Trigger, below the rules. An account runs through a playbook once per spell of matching. It enrolls when it starts matching, runs, and stays in the playbook until it stops matching — finishing the steps does not put it back at the start. It enrolls again the next time it matches, subject to the limit:
Accounts should stop and exit the playbook:
The default matters when a last step writes the very trait the trigger reads. Stopping immediately would lose that
step, which is the hardest kind of automation bug to see: the playbook looks like it ran.
Building one with the Assistant
You can ask the Assistant for a playbook in your own words, such as “when an account’s health drops below 50, flag it, wait a week and give the CSM a task if it hasn’t recovered.” It proposes the trigger and the steps on a review card, listing each step in order and how many accounts the trigger matches today. Applying it creates the playbook switched off, so you can open it, check it on the canvas and switch it on yourself. Asked to change an existing playbook, it saves the change to the playbook’s draft, the same as an edit on the canvas, and you publish it from the editor. A new name or description applies straight away, as it does here. The Assistant can’t switch a playbook on or off, publish a draft, or add or change a Call a webhook step. Webhook steps it leaves untouched stay as they are.Managing a playbook
Open a playbook and use the menu beside its switch:- Rename — the name is what shows on flags and tasks the playbook raises, so renaming it changes what they say next time, not what they already said.
- Add a description or Edit description — a paragraph or more, in plain text, about what the playbook is for: what starts it, what it does, what it deliberately leaves alone, and anything someone has to enter for it to work. It shows under the playbook’s name, and its first line shows on the playbooks list. A long description is shortened to a few lines until you choose Show more. Up to 5,000 characters.
- Delete — the playbook and its run history go. What it already did stays: tasks, flags, segment membership and traits it wrote are not undone. Deleting the automation is not a claim that its work never happened.
Who is in it
Under Accounts on the playbook, in three tabs:
Show on any row opens that run’s steps: what it did, when, and the reason for anything that failed. That is where a failed step’s error lives, so a counter saying “6 failed” becomes six accounts and six reasons.
Counters
Every step’s card shows what happened on it: how many runs completed it, failed on it, or are waiting on it. These are worth reading. A playbook where every run piles up on one wait step looks perfectly healthy as a diagram — the counters are the only thing that tells you the steps below it have barely run.Seeing it from an account
Open an account and go to its Playbooks tab. It lists the playbooks working on that account now, and the ones that have run on it before, newest first. That is the answer to “why did this account get a task and a flag this morning”.
Notes on the engine
Worth knowing whether you build a playbook in the screen or over the API.- Run limits cap how often an account can go through. An account part-way through is never enrolled a second time.
- Exit: when an account stops matching the trigger, a run either finishes (the default) or stops immediately. Letting it finish matters when a later step writes the very thing the trigger reads.
- Update a trait works out each account’s new value when the step reaches it, from what that account holds then, so moving a date or adding to a number starts from the account’s own value.