Automation Maintenance User Guide

An automation watches for something happening to records of one type, enrols each record that qualifies, and runs an ordered list of steps against it - send an email, create a task, update a field, add it to a list, tell a colleague - with a wait between steps and an optional exit condition that stops the sequence early, for example because the candidate replied.

The terms used throughout this guide are:

• Trigger - What puts a record into the automation: record created, field changed, stage reached, a date approaching or passed, no contact for N days, or a watchdog search finding it.
• Filter - An optional saved search whose criteria a record must also match before it is enrolled.
• Enrolment - One record's journey through one automation. A record can be in several automations at once, but only once in each. The requirement stage trigger is the exception.
• Step - One action in the sequence, with a wait before it and an optional exit condition. Steps run in order.
• Exit condition - Checked when a step becomes due. If met, the rest of the sequence is skipped and the enrolment ends as 'exited'.
• Scan - The background check that looks for records to enrol. Its frequency is set per automation ('Scan every').
• Run state - Live: steps really run. Dry run: records are enrolled and every step is logged as what would have happened, but nothing is sent or changed. Paused: no new records join.

• Engine switch - Global Settings > Automation > Enabled. While it is off nothing scans, no steps run, the Automations menu entry and the record-level tab are hidden, and the maintenance screen shows a notice with a "Switch the Automation Engine on" button for full-access users. "Stop All" on the list screen switches it off again. It is the kill switch.
• Permission - User Group Permissions > Automation Maintenance. Full access does everything; read-only sees the list and monitoring only, with no Save, Preview or run-state changes.
• Where - The left-hand menu entry Automations (above Admin), or Admin > System > Automation Maintenance. Once the engine is on, an Automations tab appears on Candidate, Company, Contact, Requirement and Placement records for every logged-in user.

The list screen shows one row per automation. The toolbar holds "Add Automation" and "Stop All".

The editor has three tabs - Configuration, Enrolments and Preview - and the following toolbar buttons.

Pausing an automation that has records mid-sequence asks what to do with them: leave them to finish, pause them so they resume where they left off when you reactivate, or cancel them.

Changing the steps of an active automation that has records mid-sequence also warns you. Those records carry on from their next step using the new list, and a step that no longer exists is skipped to the next one that does.

Record created. Every new record of the type from the moment the automation is active. There is no back-fill: records that already existed are never enrolled by this trigger. Use a saved-search trigger or a date trigger for those.

Field changed. Pick any field of the record type, including custom fields, and optionally the value it must change to (a drop list for lookup fields). Saving switches Colleague's Track Changes on for the field if it was off, and the editor tells you, so only changes made after that are seen. Changes made by imports, the API or another automation's field update count too.

Stage reached. What it means depends on the record type:

• Candidate - The candidate is enrolled when they reach the chosen pipeline stage on any requirement (Longlisted, Shortlisted, CV Sent, Interview, Offered, Placed, Rejected, Removed). The requirement is carried so requirement merge fields work in emails.
• Requirement - The requirement is enrolled each time a candidate reaches the stage on it, one enrolment per candidate, so the same requirement can be in the sequence several times at once. Which requirements: All requirements, Requirements I own (owned by whoever created the automation), or These requirement IDs (comma separated). The candidate is carried for merges.
• Offer/Placement - The placement or offer record is enrolled at Offer created, Offer accepted, Offer rejected, Placement made (offer accepted or placed directly), Authorised level 1 or Authorised level 2. The candidate is carried for merges.

Like Record created, stage triggers watch from activation onwards. There is no back-fill.

Date approaching / Date elapsed. A date field of the record type (standard fields plus the type's custom date fields) and a number of days: within the next N days, or more than N days ago. Re-checked on every scan, so set the schedule.

No contact for N days. Records whose Last Contacted is older than N days, including records never contacted. Contact made means any history entry whose code is flagged as contact made. Candidates, Companies and Contacts only.

Saved search gains a match. Pick a user, then one of their saved searches. The search must be a watchdog; the editor warns if it is not or has expired. Each record the watchdog newly finds is enrolled, on the watchdog's own schedule. The search owner keeps their normal watchdog notification.

Filter (optional). Pick a user, then one of their saved searches for this record type, and click "Use this search's criteria". The criteria are copied into the automation at that moment; editing the search later changes nothing until you click Use again. Only records matching the filter are enrolled. "Qualifying now" counts the records that match the filter today, before the trigger and exclusions. "Clear filter" removes it.

The save message for an active automation tells you when the next scan is due.

• Wait after enrolment / after step N - Hours or days before this step becomes due. A new step defaults to 0, so it runs as soon as the previous step has run, or on enrolment for step 1.
• Then - The action.
• Skip the rest if, by the time this step is due... - The exit condition.

Merge fields. Choose one from the picker in the box heading, click in a subject, text box or email body, then select "Insert merge field". Tags look like {FORENAMES}. {RECORDLINK} gives a link to the record in internal emails. Run summaries have {AUTOMATIONNAME}, {ENROLLEDCOUNT}, {RUNDATE} and {AUTOMATIONLINK}.

Email suppression. Before an email or MailChimp step runs, the engine checks the record may be emailed: it needs an email address, must not be archived, and its mailshot status and GDPR consent must allow it. A blocked record is logged as suppressed, not failed, and the sequence carries on. Reason codes you will see are NO_EMAIL, ARCHIVED, MAILSHOT_STATUS, GDPR_NO_CONSENT, MAILCHIMP_RULE, and DAILY_CAP when the system-wide daily email cap was reached; that step is retried at 08:00 the next day.

Who sends. The automation's author must be an active user with an email address and a Microsoft 365 link in Colleague; otherwise the email falls back to the notification address and the step log says why. Internal emails and run summaries always come from the notification address.

Whatever you choose, a record that is archived or deleted always leaves the sequence.

The Enrolments tab is available once the automation has been saved. For a period you pick (7, 30 or 90 days, all, or dates) it shows:

• Enrolments in the period - Enrolled, still in the sequence, completed, exited early, failed, cancelled, and how they ended by exit reason.
• Steps run in the period - Executed live, logged in dry run, skipped by exit condition, skipped by suppression, failed, and emails queued, sent and dry run.
• Suppressed by reason.

Every count is a link that filters the enrolment list below it by status, outcome or reason. The list shows each record, when it was enrolled, its current step and when the next action is due, its status and exit reason, the trigger reference (the requirement or candidate that triggered it) and the number of log rows. From a row you can cancel an active enrolment or retry a failed step.

Select the log count to open the step log: every step that ran for that enrolment, with when, which step, the action, the outcome (ran, suppressed, exited, failed, dry run), the reason and a detail line. Where a step produced something you can open it inline: the email as queued (subject, from, template body, each recipient's send status, and the merged text that was actually sent), the task, or the history row. Dry-run rows are greyed and italic.

The same panels open from the list screen's Active enrolments count and log icon.

On a Candidate, Company, Contact, Requirement or Placement record, the Automations tab shows the record's active enrolments (automation, enrolled, current step, next action and when it is due, with a cancel link for full-access users) and its past enrolments (automation, enrolled, finished, outcome, steps run). The automation name links to its enrolments in Automation Maintenance.

"Preview" saves the automation and then works out, without enrolling, sending or changing anything:

• Qualifying now / Would enrol next scan for date and no-contact triggers, or Hit the trigger in the window / Would have been enrolled for event triggers. Those fire on events, so the preview looks back over the window since the last scan, or the last 7 days for an automation that has never scanned.
• Would be excluded and why: already in the sequence, inside the re-enrol window, over today's cap.
• Would be suppressed: how many of the batch could not be emailed and the reasons. Above 50% the filter is probably wrong.
• A sample of the first 25 records, with links.
• The merged email for the first email step against a real record (the latest record if nothing hit the trigger), to check the template and merge fields.

The Preview badge shows 'current' while the configuration matches the preview and 'out of date' after any change that affects who is enrolled or what happens to them. Preview is recommended, not required, before going live: choosing Live without a current preview asks you to confirm.

• Scans run in the background at the automation's Scan every gap or schedule. The system default gap is 15 minutes.
• Due steps are picked up by the background runner about once a minute, so a step with a 0-hour wait normally runs within a minute or two of becoming due.
• Emails are queued and sent by the email worker shortly afterwards. Send at hour holds them until that hour in the author's time zone. The step log's email detail shows each recipient's send status.
• All dates on the automation screens are shown in your local time.

The following settings are held under Global Settings > Automation:

• No back-fill. Record created, field changed, stage reached and watchdog triggers only see things that happen after the automation is active. Use Dry run to watch enrolments appear without anything being sent.
• Dry run enrols. Records join the sequence and every step is logged with what it would have done. Switching to Live later continues those enrolments for real from their next step.
• Field changed needs Track Changes. The editor switches it on when you save; changes before that are invisible to the trigger.
• Date and no-contact triggers scan daily at most, at the time you set.
• Emails only go to Candidates and Contacts, the records with their own email address. For other record types use an internal email or a task.
• The author's mailbox is used for Send as: the automation's author. If that user has no Microsoft 365 link in Colleague the email is sent from the notification address instead, and the step log says so.
• Templates that an automation step uses cannot be deleted from Templates maintenance.
• Copy makes a paused dry-run copy with the steps. Delete asks what to do with records mid-sequence.
• Watchdog searches enrol on the watchdog's own schedule, not the automation's.
• Removed or renamed lists, templates and custom fields show as '(not in the list)' in the editor so you can see what needs fixing.