Skip to main content
Use a routine to turn repeatable instructions into Tasks on a schedule, from a manual run, or through an authenticated integration. This guide shows the board-operator workflow in the AoA UI and the checks that confirm each run did what you intended.

​
Prerequisites

Before you create a routine:
  • Select the company that will own the routine.
  • Make sure you have task-assignment permission. Creating routines, enabling them, adding or editing triggers, and starting manual runs require tasks:assign.
  • Create the agent and project you want to use, if the routine should assign its Tasks automatically.
  • For scheduled runs, make sure the heartbeat scheduler has not been explicitly disabled. Scheduling is enabled by default; setting HEARTBEAT_SCHEDULER_ENABLED=false disables schedule ticks.

​
Create a Routine

  1. Open Routines from the WORK section of the company sidebar.
  2. Select Create routine.
  3. Enter a name that describes the resulting Task, such as Prepare weekly customer report.
  4. Choose an agent and project when the generated Task should be assigned and scoped automatically. Both fields are optional.
  5. Add the instructions the agent should receive.
  6. Open Advanced settings and choose how overlapping and missed runs should behave:
    • coalesce if active keeps one existing live execution Task instead of creating another overlapping Task.
    • always enqueue creates a Task for every trigger occurrence.
    • skip if active records the overlap as skipped while a live execution is running.
    • skip missed ignores schedule windows missed while scheduling was unavailable.
    • enqueue missed with cap catches up missed windows, up to 25 runs in one scheduler pass.
  7. Select Create routine.
AoA creates the routine as active and opens its Triggers tab. A routine without a trigger is valid and can still be started with Run now.

​
Add a Schedule

  1. On the routine’s Triggers tab, select Add beside Schedule.
  2. Choose a preset such as every hour, every day, weekdays, or specific days. Choose Custom cron when you need a five-field cron expression.
  3. Set the time. The UI stores the browser’s local IANA timezone, such as Asia/Kolkata, with the trigger.
  4. Use Add another schedule if the same routine should run at more than one time.
  5. Confirm the dialog.
The trigger card should show a human-readable schedule and its Next run. Edit the trigger when you need to change its cron expression, timezone, or label.

​
Add and Configure Variables

Variables let one routine produce differently titled or instructed Tasks without duplicating the routine.
  1. Add placeholders to the routine name or instructions:
  2. Save the routine.
  3. Open the Variables tab. AoA detects placeholders from both the name and instructions.
  4. Configure each variable’s label, type, default value, and whether it is required. Supported types are text, textarea, number, boolean, and select.
  5. For a select variable, enter its allowed values and optionally choose a default.
  6. Select Save variables.
Variable names must begin with an ASCII letter and may contain only ASCII letters, digits, and underscores. {{date}} is built in, resolves to the current UTC date in YYYY-MM-DD form, and does not appear in the Variables editor. Removing a placeholder from both the name and instructions removes it from the detected variable set the next time variables are saved.

​
Test the Routine Manually

Test a routine before relying on an automatic trigger.
  1. Select Run now from the routine page or its card.
  2. Enter values for any variables. Defaults are prefilled, and the dialog blocks submission while a required value is empty.
  3. Select Run routine.
  4. Open the Runs tab.
A successful dispatch first appears as issue created and links to the generated Task. Open that Task to confirm:
  • the title and instructions contain the interpolated variable values;
  • the project, goal, parent Task, priority, and assignee match the routine;
  • the Task’s completion policy matches the routine or the applicable company/project policy.
Manual runs are allowed while a routine is paused. Archived routines cannot be run.

​
Verify Automatic Runs

Use the routine detail tabs as the operational record:
  • Triggers shows whether each trigger is enabled, its next run, last fire time, and last result.
  • Runs shows the source, status, linked Task, time, and failure reason.
  • Activity combines routine, trigger, and run audit events.
  • History shows saved definition revisions and their authors.
Run statuses mean: Routine failures also create a failure-only item in Inbox. Successful, coalesced, and skipped runs remain visible in run history without an extra Inbox notification.

​
Pause, Archive, or Restore

  • Pause disables automatic schedule and webhook execution. Existing Tasks keep their own lifecycle, and board operators can still use Run now.
  • Enable returns a paused routine to active status.
  • Archive prevents automatic and manual runs while keeping history.
  • Restore from the archived filter returns the routine to active status.
Routine-definition edits save the previous definition as a revision. Trigger creation, edits, and deletion are not included in those snapshots and cannot be recovered from History. To recover an earlier routine definition:
  1. Open History.
  2. Review the available revision. The current UI diff shows only description changes, even though restore replaces the full saved definition.
  3. Select Restore.
  4. Verify the restored title, description, assignee, project, goal, parent Task, priority, status, concurrency and catch-up policies, completion-policy override, and variables.
  5. Reopen Triggers and Runs as well. Existing triggers remain in place because triggers are not part of the restored snapshot.
Restoring a revision rotates every webhook secret attached to the routine. The restore response does not reveal those new values. Immediately rotate each webhook secret through the Routines API, save the one-time secret response, and update the sending integration before treating the restored routine as operational.

​
Use a Webhook or API Trigger

The backend supports bearer-token and HMAC-SHA256 webhooks, but the current Routines page disables creation of new webhook triggers. Create webhooks through the Routines API. The create and rotate responses show the plaintext secret once. For bearer mode, send:
For HMAC mode, sign {timestamp}.{rawBody} with SHA-256 HMAC and send the timestamp and hex signature in X-AoA-Timestamp and X-AoA-Signature. The default replay window is 300 seconds. Use an idempotency key for integrations that may retry. AoA returns the existing matching run instead of creating a duplicate for the same routine, source, trigger, and key. For an authenticated API trigger, create a trigger with kind: "api", then call POST /api/routines/{routineId}/run with that trigger’s ID, a source of api, and any variable values. See Start a Run for the request contract and accepted response.

​
Troubleshooting

​
A schedule never fires

  • Confirm the routine and trigger are both active.
  • Confirm the trigger card has a Next run value.
  • Confirm HEARTBEAT_SCHEDULER_ENABLED is unset or set to true; the exact value false disables scheduling.
  • Check that the stored timezone is a valid IANA timezone and the cron expression has five fields.
  • Check server logs for routine scheduled trigger tick failed.

​
Run now returns 403

Your board identity lacks tasks:assign. Ask a founder or instance administrator to grant task-assignment authority, or have an authorized operator start the run.

​
A routine request returns 409

Common causes are:
  • the routine is archived;
  • the selected trigger was disabled;
  • another operator edited the routine and your revision token is stale;
  • the assignee is pending approval or terminated.
Reload the routine before retrying. Choose an active assignee when assignment caused the conflict.

​
A run returns 422

Check required variable values, number and boolean formats, select options, cron syntax, timezone, and company ownership of linked entities. Unknown variableOverrides keys are rejected.

​
Saving the priority fails

The current detail UI offers critical, while the routine API validator accepts urgent, high, medium, or low. Leave the existing priority unchanged in the UI, or update it through the API with one of the accepted values until the UI and validator are aligned.

​
A webhook is unauthorized

  • Confirm you are using the newest secret. Rotation invalidates the previous value.
  • For bearer mode, include the exact Bearer prefix.
  • For HMAC mode, sign the raw request bytes, not reformatted JSON.
  • Make sure the timestamp falls inside the configured replay window.
  • After a revision restore, rotate the secret again and replace the sender’s stored value.

​
A webhook URL has the wrong origin

Verify the server’s AOA_API_URL. The public path is always: