# Scheduled workflows

Source: https://neondeerdata.com/docs/platform/automations/attio-scheduled-workflows/

Run an Attio workflow for selected records at a future date and time. Each record starts its own one-time run. Review upcoming runs and cancel them when plans change.

## How scheduling works

- **Runs are one-time, not recurring.** Each scheduling action sends the selected records once, at one time. To run again later, schedule the records again.
- Each selected record becomes one run. All the runs from one selection form a batch.
- The workflow must start with the [Scheduled record](https://neondeerdata.com/docs/platform/automations/attio-scheduled-workflows/#trigger) trigger, set to the same object as the records. Turning the workflow on registers it with Neon Deer, which then holds the scheduled runs and sends each one to the workflow at its time.
- Scheduling needs the app's [Neon Deer connection](https://app.attio.com/%5F/settings/apps/installed/workflow-utilities/connections), a Neon Deer plan that includes scheduled runs (see [Settings → Billing in Neon Deer](https://app.neondeerdata.com/)), and a workspace time zone, set in Neon Deer under Settings » General (see [Setup](https://neondeerdata.com/docs/platform/automations/#setup)).

## Configure the workflow trigger

Start the workflow with `Scheduled record`, the trigger's name in Attio. Set `Object` to the object whose records you will schedule, such as Companies or Deals. Choose the object directly; a workflow variable cannot be used for this setting. Turn the workflow on before scheduling records.

When the scheduled time arrives, the trigger provides these outputs to the rest of the workflow:

| Output        | Type      | Meaning                                        |
| ------------- | --------- | ---------------------------------------------- |
| Record        | Record    | The Attio record scheduled into this workflow. |
| Record ID     | Text      | The scheduled record's ID.                     |
| Triggered at  | Timestamp | When the workflow started.                     |
| Scheduled for | Timestamp | The date and time chosen when scheduling.      |
| Scheduled by  | Actor     | The workspace member who scheduled the record. |

Wire `Record` into the later steps that act on it. Each scheduled run starts at most once; another delivery of the same run within 30 days is ignored. The trigger does not check whether the record still exists.

For connection, registration or scheduling errors, see [Scheduling problems](https://neondeerdata.com/docs/platform/automations/troubleshooting/#scheduling-problems).

## Scheduling records

1. **Open the scheduling dialog.** Select one or more records in an Attio view or list. In the bulk action toolbar at the bottom of the screen, click `More`, then `Schedule in workflow`. Scheduling is currently available only as a bulk action. The dialog lists workflows that are turned on and start with `Scheduled record` for this object. If only one qualifies, it is preselected.
2. **Pick `Workflow`, `Date` and `Time`.** Times are offered on quarter hours only (:00, :15, :30 and :45). `Time zone` shows the workspace time zone and cannot be changed in the dialog; change it in Neon Deer.
3. **Choose `Schedule`.** A toast shows `Scheduling records…` and then `Scheduled N records`.

### Which times can be scheduled

- The time must be on a 15-minute mark in the workspace time zone, in the future, and at most 12 calendar months ahead.
- A time that does not exist because clocks spring forward cannot be chosen. A time that occurs twice when clocks fall back resolves to its first occurrence.
- Neon Deer stores the time in UTC together with the time zone, and the platform lists times in the workspace time zone.

### Large selections

Records are sent to Neon Deer 250 at a time. If Neon Deer refuses one of these requests, the remaining ones are not sent and the toast reads `Scheduled N records, then stopped`; the records already scheduled stay scheduled. A workspace can hold up to 10,000 pending runs, and a request that would go over that limit is refused as a whole.

Workflow missing from the list

A workflow that was archived and then unarchived is not active again until it is published. Make any edit to it and publish it, and it appears in the list. A workflow that is turned off, or that starts from a different object, is not listed either.

If the dialog cannot open its form, or Neon Deer refuses the records, the message says why. Each message and its fix is listed under [Scheduling problems](https://neondeerdata.com/docs/platform/automations/troubleshooting/#scheduling-problems).

## When the scheduled time arrives

- Neon Deer checks for due runs every minute and sends each run to the workflow. A workspace has at most 5 sends in progress at once and at most 10 started per second, so a large batch is sent over a short period rather than all at the same instant.
- The workflow is checked when the run comes due. If it is turned off at that moment, or now starts from a different object, the run is skipped. Before then, Upcoming shows the run as `Workflow off` while the workflow is off.
- Pending runs belong to the workflow, not to the version that was on when you scheduled them. Turning the workflow off does not cancel them. If it is turned on again before a run comes due, the run goes to the workflow as it is then, which may be an edited version, as long as it still starts from the same object. To stop runs for good, cancel them.
- Neon Deer also checks your workspace's access before each send. Runs for a workspace without access are held and not sent.
- Each send waits up to 10 seconds. A temporary failure (a timeout, rate limit, server error or network error) is retried: 3 attempts in all, 1 minute and then 5 minutes apart. Other refusals fail the run at once.
- A run more than 6 hours late is never sent and is marked Skipped.
- In the workflow, the Scheduled record trigger outputs `Record`, `Record ID`, `Triggered at`, `Scheduled for` and `Scheduled by` (the member who scheduled it). If Neon Deer sends the same run twice, the trigger starts it only once.
- The trigger does not check that the record still exists. Deleting a record in Attio does not by itself cancel its scheduled runs, so cancel them if you delete records you have scheduled.

### Run statuses

| Status   | Meaning                                                                                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pending  | Waiting for its time. Shown as `Sending now` while a send is underway, and `Workflow off` while its workflow is turned off.                                   |
| Sent     | The workflow's trigger address in Attio returned a success response. Neon Deer does not track what the workflow did next; check the workflow's runs in Attio. |
| Failed   | The workflow refused the record, Attio could not be reached after 3 tries, or the workflow's address in Attio could not be used.                              |
| Canceled | Canceled by a member, or when the app was disconnected in Attio.                                                                                              |
| Skipped  | The workflow was turned off, now starts from a different object, or the run was more than 6 hours late.                                                       |

## Monitoring scheduled runs

### In Attio: the Scheduled runs widget

- On a record, the widget shows `None scheduled`, `1 scheduled` or `N scheduled` (counted up to 100), and the next run time in its time zone.
- Opening it lists the record's pending runs, soonest first, up to 100: the workflow and time of each, marked `Sending now` or `Workflow turned off` where that applies, with `Cancel run`.

### In Neon Deer: the Scheduled runs tab

- `Upcoming` lists pending runs, soonest first. `History` lists ended runs, most recent first, for the last 90 days. Filter by `Workflow`, `Scheduled by` or a date range.
- Any workspace member can view the tab. Record and member names are read from Attio when the page loads; if Neon Deer cannot read your Attio workspace, the page says names will show once it can. Record links are built for Companies and People only.

## Canceling

- Any workspace member can cancel a run; no admin permission is needed.
- In Attio, use `Cancel run` in the record's Scheduled runs widget.
- In Neon Deer, use `Cancel` on a row, `Cancel N runs…` for the runs you selected on the current page (up to 50), or `Cancel batch` on a batch with more than one pending run.
- A run that is being sent cannot be canceled. The widget says so, and the platform disables `Cancel` on that row.
- Canceling changes nothing in Attio, and the records can be scheduled again.
- Removing the app's [Neon Deer connection](https://app.attio.com/%5F/settings/apps/installed/workflow-utilities/connections) in Attio cancels every pending run, if the removal reaches Neon Deer. If it does not, the runs stay pending; cancel them on the Scheduled runs tab.

## Example: schedule 100 companies for tomorrow morning

You have a workflow that starts with Scheduled record, with `Object` set to Companies, and it is turned on. The workspace time zone is set.

1. **Select the records.** In a Companies view in Attio, select 100 companies and choose `Schedule in workflow`.
2. **Choose the workflow and time.** Pick the workflow, tomorrow's date and 9:00 AM. The time zone shown is the workspace's.
3. **Schedule.** 100 records fit in one request, so they are scheduled together. The toast reads `Scheduled 100 records`. Neon Deer now holds 100 pending runs in one batch.
4. **Check them.** Each company's Scheduled runs widget shows `1 scheduled` (if it had none before) with tomorrow's time. In Neon Deer, Upcoming lists the 100 runs, and `Cancel batch` cancels all of them at once.
5. **At 9:00 AM tomorrow** , Neon Deer picks up the due runs and sends them to the workflow, at most 10 starting per second. Each send starts one run of the workflow for one company, with that company as `Record`. Each run then moves to History as Sent, or Failed or Skipped with the reason.

If you turn the workflow off before 9:00 AM and leave it off, the runs are skipped at their time. If a temporary problem delays sending by more than 6 hours, the remaining runs are skipped rather than sent late.