Skip to main content

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​

WorkflowCycle
Starting it by handYes (owners only)No
Starting it at a set timeA Time trigger on the project. A time on the first enabled step also starts itA Sweep schedule on each placement
Starting it from outsideThe external API starts a run (no registration)The external API calls a webhook trigger (registered first)
Starting it by emailEmail 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 stepYesNo (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 — an owner can start it by hand.

Starting a workflow​

A workflow usually runs by hand. Add a time trigger only where you want it to start at a set time.

Only an owner can run it by hand. Members cannot run it by hand (Who decides what). Where starting by email is in use, members 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.

  • 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 lanes, a run cannot start from a step after the one the lanes split from

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 “Enabled”.

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.

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).

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

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 “Enabled”.

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” ＞ “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 owners and members, from their registered email address. Members can start a run by email (running it by hand is for owners only). Once someone is removed from the members, their address no longer counts as a member's. The email has to pass sender authentication (one of DMARC, DKIM or SPF).

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). Accepted attachments are saved in the “Library” of the person who created the project, 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.

Once it is accepted, the sender gets an acknowledgement. It does not mean the run went well. A reply to an owner or member 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, or while the placement chosen for a cycle is missing is refused. It gets no reply and 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).

In a workflow's records, the “Started by” 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 “Started by” column, and when an owner or member sent it, the request shows “Set up by”.

Where on screen For a workflow, the Settings tab ＞ “Triggers and notifications” ＞ “Start by email”; for a cycle, the Settings tab ＞ “Triggers” ＞ “Start by email” (the placement to start is chosen in the same place). External senders are under “Email address to allow” 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.

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.

  • 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)

Where on screen “Pause” at the top of the project screen (resuming is “Resume” in the same place; shown to owners only). Cancelling a run is the Workflow history tab ＞ “Cancel run” on a run in progress (shown to owners only)

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). 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 run it. Only an owner can run it by hand (where starting by email is in use, members can start it by email)
  • 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)