Trigger Guide
This guide covers the choices and the criteria for deciding when, and on what, to run the work, and how to stop it.
How it is started differs by type. Choosing the type itself is covered in the Design Guide, and how the two types differ in the way they run is covered in Cycle and workflow.
Where a section has a place on screen, you will find where to set or check what it asks you to decide at the end of it.
What each type can use
| Workflow | Cycle | |
|---|---|---|
| Starting it by hand | Yes (the project's participants (owners, operators and members) and people with the organization operations role) | No |
| Starting it at a set time | A Time trigger on the project. A time on the first enabled step also starts it | A Sweep schedule on each placement |
| Starting it from outside | The external API starts a run (no registration) | The external API calls a webhook trigger (registered first) |
| Starting it by email | Email to the project's address starts a run (where the email feature is enabled) | Email to the project's address runs the chosen placement (where the email feature is enabled) |
| A time per step | Yes | No (the schedules belong to the placements) |
Note that the unit differs. A workflow's time trigger is attached to the project, whereas a cycle's schedule belongs to each placement — an agent placed on a step. A workflow need not have a time trigger at all — the project's participants (owners, operators and members) and people with the organization operations role can start it by hand.
Creating and enabling automatic starts
To create or enable starts that run automatically — at a set time, by webhook, by sweep or by email — the administrator must allow you “Scheduled run creation” in Feature permissions. People who are not allowed are refused these operations: creating or enabling a trigger (time or webhook), enabling “Start by email”, setting or changing a step's time (workflow), enabling a sweep or changing the schedule of an enabled sweep, and importing from a file or creating from a company template a definition that contains any of these. Starts that already exist do not stop. Stopping or removing, saving a step's time with the same value, and changing an enabled trigger or “Start by email” setting while leaving it enabled can be done without the permission. Changing the schedule of an enabled sweep is refused.
Everything that runs automatically is listed under “Automations” at the top of the project area. Your personal Schedules, Claws and Mail, and the triggers, first-step times and sweeps of the projects you take part in, are shown with their kind, where they belong, their status and their next start. Of the step times, only that of a workflow's first enabled step is listed (nothing is listed when that step has no time). In a project with an enabled time trigger, it shows as “Inactive”, because that time does not start a run. Create, change or stop each one on its own screen, opened from its name. You can also open the list from “All automations” next to the heading of the “Schedule” screen.
Where on screen The permission: “Connections and Usage Scope” > “Feature permissions” > “Scheduled run creation” in the admin console (system administrators). The list: “Automations” at the top of the project area
Starting a workflow
A workflow usually runs by hand. Add a time trigger only where you want it to start at a set time.
The project's participants (owners, operators and members) and people with the organization operations role can run it by hand (Who decides what). Where starting by email is in use, the same people can start it by email (Starting by email).
There are two ways to start it on time. One is to add a Time trigger; the other is to give the first enabled step a time (see below). Where an enabled time trigger exists, that is what settles the start.
There are two things to settle when you add a time trigger. Where definition changes need approval in the tenant, adding, changing or deleting a time trigger also takes effect only once approved (Checking a draft and applying it).
- When to run it — hourly, daily, weekdays, weekly and so on are there to choose from (weekly lets you pick several days). Where you want something finer, a cron expression works too
- Start step — which step it begins from. Leave it unset and it begins from the First enabled step. Where there are parallel lanes, a run cannot start from a step after the split, and where there is a Branch step, it cannot start from a step inside its lanes
You can attach several. One that starts from one step on weekday mornings and another that starts from a different step at the weekend, say. Each can be enabled and disabled on its own, so you can stop only the one you want stopped.
You are asked to confirm before a time trigger is deleted. Deleting it stops the automatic starts from that trigger, but runs already in progress carry on. Deletion cannot be undone, so to stop it for a while, turn off its switch in the list.
Where on screen The Settings tab > “Triggers and notifications” > “Add time trigger”. “Start step” is chosen in the same place
Running a cycle
A cycle runs on the schedule of each placement. There is no time trigger for the project as a whole.
Placements sharing a step can have different schedules. You can place one agent for the mail and one for the form on "Find them" and have only one of them go round at a short interval. You do not need to divide the steps just to change a schedule.
Each can be stopped on its own. Switch off “Enable sweeping” and that placement no longer runs on its schedule (the schedule itself is kept). The others carry on. What stops, though, is only the scheduled round — where the same placement has an enabled webhook trigger, or is the placement chosen for starting by email, it still runs from that. To stop every new start from here on, disable the webhook trigger and starting by email as well. Whatever has already been accepted is not cancelled.
When you disable a step, the placements on that step take no new starts. The scheduled round stops, and a webhook trigger, starting by email and a rerun of a failed round are refused. Starts accepted before you disabled the step are not cancelled. When you enable the step again, placements that had sweeping enabled go back to their saved schedule (once nothing else, such as pausing the project, is holding them).
Where you have divided the stages, stagger the times they start. Set them to the same time and a stage can run before the previous one has left anything, and come up empty. Staggering them is no guarantee, though, that the previous stage has finished (Design Guide).
You can also settle hours and days when it does not run. Use this when you do not want it to go round at night or on holidays, say. When the way of giving the time is “Interval” or “Hourly”, “Quiet hours and days” appears. The hours are on the hour: choose where they start and where they end (the time it starts again). The days are the days it does not run (not every day can be chosen). The schedule shows “Next: …”, when it next runs, so check that it is what you meant. The Launch card, which opens with “Show All” under “Project info” on Overview, shows the next run too.
Where on screen Edit > select the agent placed on the step in question, in the diagram in the middle, then “Agent on this step” on the right > “Trigger” > “Sweep schedule” > “Enable sweeping”. To stop it, switch it off in the same place. The quiet hours are under “Quiet hours and days” in the same place
A time per step (workflows)
In a workflow, a step that holds agents can have a time of its own. A review step begins once the previous step finishes. There are two to choose from.
- Right after the previous step — the default. It runs as soon as the previous step finishes
- At a set time — it waits for that time before running
Use it where you want the start held until a time you choose — to have the work done overnight in one go, say. It puts no limit on the time once it has started.
A cycle does not have this setting. What settles the timing in a cycle is the sweep schedule from the previous section.
The first enabled step's time is when the run starts (where there is no enabled time trigger). So a time there alone is enough to start it on time. Where an enabled time trigger exists, that is what settles the start.
Starting it from outside
Either type can be started from the external API. What differs is whether something has to be registered first.
A workflow can be started without registering anything. Call the external API's start-a-run with an external API access token and an Idempotency-Key header, and a run begins; the record shows it as "External API". Resending with the same Idempotency-Key returns the same run and does not start it twice. Getting run status returns, besides the run's state and when it started and ended, each step's status and a summary of the agents' output (external API documentation). Deciding where results go is in the Design Guide.
A cycle needs a webhook trigger registered first. You map it to a placement to start (a combination of an agent and a step), and calling that trigger from the external API runs that placement. To register one, the agent has to be placed on that step already.
You are asked to confirm before a webhook trigger is deleted. Deletion cannot be undone, and creating it again changes the place to call, so the caller's settings have to change too. To stop it for a while, turn off its switch in the list.
The call to the external API cannot be made from the screen. What the screen does is register, change and delete webhook triggers, and show how to call it — the path, headers, body and an example — for you to copy (to start a workflow from the screen, run it by hand).
In a cycle, several calls can be merged into a single run. Where a call has not started running yet, whatever arrives after it may be folded into that one. Do not take the number of calls and the number of runs to be the same. The ID returned by a call cannot be used to get run status. The identifier to put on a call, and how resending is handled, are covered in the external API documentation.
Where on screen For a cycle, the Settings tab > “Triggers and notifications” > “Add webhook trigger” > choose the agent and the step under “Placement to start”; how to call it (path, headers, body and an example) appears on the row of each registered trigger. For a workflow, how to call it appears under “Start from the external API” in the Settings tab > “Triggers and notifications”
Starting by email
This is available where the email feature is enabled. The project gets one address, and email that arrives there starts it.
- Workflow — each email starts one run from the first enabled step. The subject, body and attachments are passed to the workflow
- Cycle — first choose one placement to start (a pair of agent and step). Each email runs that placement once, and its subject, body and attachments are passed to the agent in that placement. Emails that arrive while the placement is running are run after it finishes. If the chosen placement is later removed, email does not start anything until you choose again
Only owners can set it. Turning it on creates the address, which members can see too. To stop it, turn it off (the address stays the same).
Email can be sent by this project's participants (owners, operators and members), and by people with the organization operations role, from their registered email address. These are the same people who can run it by hand. Once someone leaves the project (and does not have the organization operations role), email from their address no longer starts a run. The email has to pass sender authentication (DMARC).
To have email from other people start it, an owner allows those addresses (up to 20). Each is registered as a complete address, one at a time; domains and wildcards cannot be allowed. Email from an allowed address is treated as from an external sender only when it passes DMARC.
Whoever sends it, the subject and body reach the agent as external data, not as instructions. No review is added automatically, so in a workflow, put a review step where one is needed (Review Guide).
The body can be up to 20,000 characters, with up to 10 attachments (each up to 10 MiB, 20 MiB in total). Executables, scripts, Office files with macros and similar files are not accepted. Attachments over the limits and attachments that are not accepted are dropped and the email is processed without them (you are not told that they were dropped). Accepted attachments are saved in the “Library” of the project's owner, not the sender's, and passed to the run. Only the first 998 characters of the subject are passed. Email without a Message-ID, and email judged to be spam or to carry a virus, is not accepted. The same email (the same Message-ID) arriving again does not start another run.
Send one and the same email to the project's address and another of the product's addresses at once (such as your personal address for asking your own AI by email), and the product accepts it at only one of them. The other treats it as the same email arriving again, and nothing happens there (no acknowledgement arrives either). Addresses outside the product, such as those of people outside your company, are not affected. Which address accepts it depends on how the mail is delivered. To reach both, send them as separate emails.
Once it is accepted, the sender gets an acknowledgement. It does not mean the run went well. A reply to a participant (an owner, an operator or a member) or a person with the organization operations role carries a link (to the run record for a workflow, or to the execution history narrowed to the agent of the chosen placement for a cycle). A reply to an external sender carries neither a link nor the project name.
Email arriving while starting by email is turned off, while the project is paused, while the placement chosen for a cycle is missing, or while that placement's step is disabled is refused. Email arriving while an administrator has stopped the project or the agent of the placement to start, or while the account of the user the project runs as is suspended is refused in the same way. It does not run later, so send it again once the setting is back (when the number of runs in progress is at its limit, it is resent — see How many can be in progress at once). You can check refused emails under “Rejected emails” below.
You can check refused emails under “Rejected emails” in the “Start by email” section. It shows up to the 5 most recent emails refused in the last 30 days, with the time, the reason, the sender's domain and how to fix it. Emails for the same reason are combined into one per hour (per address for senders who are notified, otherwise per sender domain). The subject and body are not kept, and only the sender's domain is shown. The list is shown to owners, operators and participants who have the organization operations role (not to members without the organization operations role). Emails that pass none of DMARC, DKIM and SPF, emails judged to be spam or a virus, and emails without a Message-ID are dropped before they reach the project and do not appear here.
The records also keep it as “Email start rejected”, with the reason and the sender's domain (Records reference). Members can see the records too.
When the sender passed sender authentication (DMARC) and is a participant in this project, a person with the organization operations role or an address registered under “Email address to allow”, an email telling them it was not accepted is sent to them (at most one per hour for the same address and reason). If recording or sending fails, the refusal is not affected and the notice is not resent. The notice to an address registered under “Email address to allow” carries neither the project name nor a link. Nothing is sent back for an email that did not pass DMARC, for an email from a sender who is neither a participant nor an address registered under “Email address to allow”, or for the same email (same Message-ID) resent with different content.
The reasons in “Rejected emails” and how to fix them:
| Reason in the list | How to fix it |
|---|---|
| Failed sender authentication (DMARC) | Set up a DMARC record for the sender's domain, or send from an address that passes DMARC |
| Sender not allowed to start | Send from the registered email address of a participant in this project or of a person with the organization operations role, or from an address registered under “Email address to allow” |
| Several users share this address | Ask your administrator to fix the duplicate address |
| Start by email is off | Send it again after an owner turns on starting by email |
| Body over the limit | Shorten the body to 20,000 characters or less and send it again |
| Attachment check failed | Attach the files again and send it again |
| No placement to start (cycles) | Choose the placement to start again |
| Same email resent with different content | Send it as a new email |
| The project was not active / Stopped by admin / The user the project runs as is suspended | Send it again once it is resumed (when an administrator stopped it, the administrator resumes it). When the user the project runs as is suspended, ask an administrator to change the project's owner |
| A step has no reviewer assigned | Assign reviewers from the current participants to every enabled review step, then send it again |
| Cannot start on this runtime | Ask an owner to check the placements |
| Cannot start from a step after the lanes split / Can’t start from a step inside a branch lane | An owner moves the first enabled step out of the parallel lanes and branch lanes |
| Other reason (code) | Look up the code in the error table for starting a run on the external API and follow its fix |
In a workflow's records, the “Trigger” column shows “Email”. The request in the run record shows “Sent by”, with “External ([EXT])” added for an external sender. A cycle's sweep started by email shows “Sweep” in the “Trigger” column, and when an owner, operator or member sent it, the request shows “Set up by”.
Where on screen The Settings tab > “Triggers and notifications” > “Start by email” (for a cycle, the placement to start is also chosen there). External senders are under “Registered sender (From)” > “Email address to allow” in the same panel; rejected emails are under “Rejected emails” in the same panel
How many can be in progress at once (workflows)
A workflow has a limit on how many runs can be in progress at once. The limit, and what counts towards it, are in the Settings reference.
Trying to start a new run while at the limit goes as follows.
- By hand — it is refused
- From the external API — it is refused (for the response, see the external API documentation)
- By email — it does not start then. Email intake resends it after a while, and it starts if there is room by then
- At a set time (a time trigger, or the time on the first enabled step) — that occasion is skipped and is not made up later. It does not appear in the execution history either
When reviews pile up, new requests stop starting. How to settle the deadline and the reviewers is in the Review Guide. When starting through the external API, the calling side needs a way to hold a refused request and send it again later.
Giving the time, and the timezone
There are ready-made choices for giving a time. Hourly, daily, weekdays, weekly and an interval (every so many minutes) are all there to pick from. You do not have to write a cron expression.
Where you want something finer, choose Custom (cron). How to write the expression, and the limits on the time increments you can give, are in the Settings reference.
A timezone is always chosen. Before you save, check that it is the timezone you meant. Where you want it to match the working hours of an overseas office, give it here.
A workflow's time trigger shows when it next runs. It is not shown while the project is paused or the time trigger is switched off. The last time is shown too; it is when that time trigger actually started a run, and it does not move on for occasions that were skipped — while the project was paused, or when the number of runs in progress was at its limit.
When it could not start at the set time, the time trigger's row shows “Not started since ◯ (reason)”. Where there is no enabled time trigger and the run starts at the time on the first enabled step, it shows on the “First step's schedule” row instead. The reasons include “A step has no reviewer assigned”, “Cannot start from a step after the lanes split” and “Input files are missing”. It disappears once a run starts. Occasions skipped because the number in progress was at its limit, because the project was paused, or because an administrator had stopped it, do not show here (they were skipped on purpose). The Records (audit trail) keep it as “Could not start from the time trigger”.
Where on screen The screens for giving a time all take the same form: the ready-made choices and “Timezone”. A time trigger is under the Settings tab > “Triggers and notifications”; a step's time is under Edit > select the step in the diagram in the middle, then “Step settings” on the right > “Trigger”; a sweep schedule is under Edit > select the agent in the diagram in the middle, then “Agent on this step” on the right > “Trigger” > “Sweep schedule”
Stopping and resuming
How to stop it depends on what you want to stop. When an administrator stops the project, it shows “Stopped by admin”, and only an administrator can resume it.
- Stop every new run from starting — pause the project. No new run starts, whether by hand, at a set time, from the external API, by sweep, by webhook or by email. A workflow run in progress holds its next agent (an agent already working is not stopped, and review requests awaiting a decision stay as they are). Resume it and runs start again, and the runs that were held continue from where they were
- Stop a workflow run that is in progress — cancel that run. It goes no further through its steps, and review requests awaiting a decision are withdrawn. An agent that is already working is sent a stop (its result is not used)
- Stop only some placements of a cycle — Running a cycle
- Stop only the starts at a set time (workflows) — turn the time triggers off, and remove the time on the first enabled step too (A time per step)
When an administrator stops an agent, the steps it is placed on do not run either. Sweeps of that agent's placements stop, and in a workflow the agent's steps are held instead of starting. Email that arrives for that placement is refused (“Stopped by admin”). When the administrator resumes the agent, sweeps of active projects come back and held steps continue from where they were.
“Resume” in the workflow history is something else. It continues a run closed by a rejection or a failure from a chosen step (Review Guide). Taking a project out of its pause is the “Resume” at the top of the project screen.
When you no longer use a project, delete it. Only owners can delete a project. Its steps and agent placements are deleted and cannot be restored. Runs in progress and review requests awaiting a decision are cancelled, sweeps and triggers stop, and the project's connections to connected services are removed. Run records and audit records are kept. A project on legal hold, or one an administrator has stopped, cannot be deleted. When the owner is leaving, you can also transfer ownership instead of deleting (Runs go out in the project owner's name).
Where on screen “Pause” at the top of the project screen (resuming is “Resume” in the same place; shown to owners, operators and people with the organization operations role. A project an administrator has stopped cannot be resumed by any of these roles). Cancelling a run is the Workflow history tab > “Cancel run” on a run in progress (shown to owners, operators and people with the organization operations role; to members, only on runs they started). Deleting is “Project actions” > “Delete project” at the top of the project screen (shown to owners)
Distinctions worth keeping straight
These are the distinctions that cut across the sections above.
- Thinking that creating it starts it running. Whether the AI (alpha) drafted it or you copied it from another project, a time trigger arrives switched off. Where the AI drafted a cycle and proposed a schedule, the project arrives paused (sweeping starts once you resume it; where the person creating it is not allowed “Scheduled run creation”, the sweeps arrive switched off and do not start when you resume). On a copy, the start step reverts to unset (so it begins from the first enabled step), and a workflow's per-step times, along with a cycle's sweep schedules and webhook triggers and the “Start by email” settings, do not carry over. Before switching anything on, check where it starts from
- Trying to run a cycle by hand. A cycle has no run-by-hand. It runs on each placement's schedule, on a webhook, or by email. To try it straight away, shorten a schedule and switch it on
- Confusing the project's time trigger with a step's time. A time trigger is when a run starts; a step's time is when that step runs. A cycle has no time trigger — its schedules belong to the placements
- Thinking the two types are started from outside by different things. Both are started from the external API. What differs is that a workflow needs nothing registered, whereas a cycle needs a webhook trigger registered first. The call to the external API cannot be made from the screen
- Thinking a member can only look. Members can also start runs by hand, from the external API and by email, and can cancel runs they started. Cancelling a run someone else started, resuming, deadlines, reassigning reviewers and pausing are for owners, operators and people with the organization operations role
- Thinking a run always starts at the set time. At the limit on runs in progress, that occasion is skipped and not made up (workflows)
- Thinking pausing also stops runs in progress. What stops is runs starting, and the next agent of a workflow run in progress. An agent already working is not stopped. To stop it, cancel the run (the working agent is sent a stop)
What to read next
- Design Guide — how to choose a type and divide the work into steps
- Review Guide — where to put a person's decision
- Connection Guide — what to connect to, and where to send word
- Cycle and workflow — how the two types differ in the way they run
- Settings reference — writing a cron expression, the limits on time increments, and how the timezone is handled