Onboarding Automation

What onboarding automation actually is

The difference from a checklist is that a checklist records intent and a state machine records reality. A checklist tells you eleven of fourteen boxes are ticked. A state machine tells you the account is blocked on a tax form requested nine days ago, that two reminders were sent, that the third fires tomorrow, and that the whole thing then becomes a named person's problem.

Most of this is not a model problem. Provisioning, dependency handling, retries and nudges are ordinary software. Models earn a place in three narrow spots: reading and validating documents people upload, drafting the chase messages, and answering the newcomer's questions from your own handbook.

Terms used on this page

State machine

A model of a process in which each item sits in exactly one named state and every move between states is an explicit, logged transition with a rule attached.

Exit criteria

The condition that defines onboarding as finished, expressed as an observed event rather than a completed list. Without one, onboarding ends when somebody stops looking.

Compensating action

The operation that undoes a completed step when a later step fails. Provisioning without one leaves half-created accounts behind every time something goes wrong.

Dependency edge

A declared prerequisite between two steps. Declaring dependencies is what lets independent work run at the same time instead of queueing behind the slowest item.

Nudge schedule

The timed sequence of reminders sent to whoever owes an outstanding step, counted from the due date, with a stop condition and a defined escalation point.

Who this is for, and who it is not for

This is worth building when onboarding crosses more than two teams, takes more calendar days than touch hours, and stalls in different places each time. It is not worth building when you onboard a handful of accounts a month through one person who is good at it.

• Nobody can name the finish line. If you cannot say what event means this customer is onboarded, the system will report success on incomplete work.
• The steps are not written down anywhere true. The documented process and the real one are different documents. We map the real one, and that is a week of work by itself.
• No owner for the sequence after launch. Templates rot faster than pipelines, because the business changes underneath them. Read who owns the automation after launch before starting.
• You want it to replace the human welcome. It should not. The system removes chasing, not contact.

What we actually build

Five components, and the template definition is the one that decides whether the rest ages well.

The template definition

A declarative file per onboarding type, holding every step with its kind, actor, owner, dependencies, due offset, nudge schedule, validation and failure behaviour. It lives in version control and changes go through review. Running instances pin the version they started on, so editing a template never mutates work already in flight.

The engine

A scheduler that walks the dependency graph, starts everything whose prerequisites are met, holds state per instance, and wakes on timers. Independent steps run at the same time, which is where most of the calendar time comes back. A linear checklist waits on its slowest item even when nine other things could have started on day one.

Provisioning and verification

Typed integrations with each system that has to create something, written idempotently and keyed, with timeouts, bounded retries and a compensating action. Every one is paired with a verification step that checks the thing exists and works. This is standard integration work, covered under systems integration, and it is most of the engineering hours.

The human layer

Forms and upload links for collection, a review queue for decisions, nudges on a schedule with stop conditions, and escalation to a named person after a set number of unanswered reminders. Uploaded documents are validated against a schema and read for content, which is where document processing belongs rather than a person squinting at a scan.

Observability

A stuck-step histogram, cycle time per step, chase count per step, first-time-right rate on collected documents, and time to the exit event. The stuck-step histogram is the single most useful chart we build, because it names the one step that costs you a week.

• A versioned template file per onboarding type, editable by an operations lead
• Idempotent provisioning integrations, each with a compensating action
• A verify step for every provision step, with its own retry and escalation
• Forms, upload links and schema validation for everything collected
• A queue for the decisions humans must make, with the evidence attached

How it works technically

One instance moves through a lifecycle with timers on it. The times below are the shape, not a promise; your own dependency graph decides the real numbers.

Idempotency, and why it decides everything

Every write in this system will happen twice eventually. A webhook retries, a worker restarts mid-step, an operator clicks the button again. If provisioning is not keyed, you get two workspaces, two licences and a support ticket. Keys go on instance creation and on every provisioning call, derived from stable identifiers rather than timestamps. The mechanics are covered in idempotency in automation, and it is the concept that separates a sequence that survives from one that quietly corrupts your data.

# onboarding/templates/customer_standard.yaml
# One file per template. Versioned in the repo and reviewed like code.

template: customer_standard
version: 11
clock: account.billing_country     # due dates in the customer's calendar

steps:
  - id: collect_tax_details
    kind: collect                  # provision | collect | decide | teach | verify
    actor: customer
    owner: role:account_manager
    depends_on: []
    due_after: P2D                 # ISO 8601 duration from template start
    nudge:
      at: [P1D, P3D, P7D]          # measured from the due date, not the start
      channel: [email, in_app]
      stop_on: step_complete
      escalate_after: 3            # then it becomes a named person's problem
    validation:
      schema: schemas/tax_details.v3.json
      on_invalid: return_to_actor_with_reason

  - id: provision_workspace
    kind: provision
    actor: system
    depends_on: [collect_tax_details, decide_plan_tier]
    idempotency_key: "{{account.id}}:workspace:v1"
    timeout: PT90S
    retry: {attempts: 3, backoff: exponential, jitter: true}
    on_fail: dead_letter           # a queue a human reads every morning
    compensate: revoke_workspace   # what undoes it if a later step fails

  - id: verify_workspace_reachable
    kind: verify                   # every provision step needs one of these
    actor: system
    depends_on: [provision_workspace]
    check: http_get {{workspace.url}}/health expect 200
    on_fail: raise_to:role:platform_oncall

exit_criteria:                     # onboarding does not end when the steps end
  - verify_workspace_reachable.passed
  - first_value_event within P14D  # name the event or there is no finish line

Three details in that file do the heavy lifting. The clock is the customer's, not the server's, so a due date does not land on a holiday somewhere. The nudge schedule counts from the due date and carries a stop condition and an escalation, so reminders end. And the compensating action is declared at the same time as the provisioning, because nobody ever goes back and adds one.

The five kinds of onboarding step

Before automating anything, label every step. The argument about which label applies is where the real design happens, and it usually exposes two or three steps that were never going to work as written.

Two rules make the grid useful. Every Provision step must have a matching Verify step. And no step may carry two kinds, because a step that is both a collect and a decide is two steps wearing one name, and it will be the step that stalls.

The build process, stage by stage

Six stages. The first two are archaeology, and they are the reason the rest works.

1. Walk the last ten onboardingsWeek one

   Not the documented process, the real one. We read the actual threads, tickets and tasks for ten recent instances and build a timeline of each. The documented process is a description of an intention; the threads are what happened.

2. Label every step with its kindWeek one to two

   The step grid applied to the real process. This is where missing verify steps appear, where two steps hiding in one name get separated, and where somebody says out loud that a step nobody performs is still on the list.

3. Model the graphWeek two

   Dependencies, owners, due offsets, escalation targets, exit criteria. Drawing the graph almost always shows that half the sequence could have run in parallel and never did, which is where the calendar time hides.

4. Build provisioning and verificationWeek two to five

   Idempotent integrations with compensating actions, paired verify steps, dead letter queues. Most of the hours land here, and the count of systems matters far more than the count of steps.

5. Human layerWeek four to six

   Forms, upload validation, nudge schedules with stop conditions, decision queues, escalation routing. Also the messages themselves, which should read as though a person wrote them, because a recipient who feels processed replies more slowly.

6. Run in parallel, then switchWeek six to eight

   The system tracks real onboardings while humans still act, so the graph is corrected against reality before it takes control. Then provisioning is handed over one step at a time, starting with the reversible ones. Rollout advice is in rolling out automation to a team.

What you get at handover

A running engine, templates an operations lead can edit without an engineer, and enough measurement to tell whether the process is getting better or just faster at being wrong.

• The engine and integrations in your repository, with infrastructure as code
• Template files per onboarding type, documented, versioned, and editable without a deploy
• A test harness that runs a template end to end against sandbox systems before it ships
• Dashboards: stuck steps, cycle time per step, chase counts, first-time-right rate, time to exit event
• A runbook covering how to add a step, change a nudge schedule, reverse a provisioning action and handle a dead letter

Where these projects go wrong

Onboarding failures are mostly about state, ownership and reversal. Very few of them are about the model.

Automating the decision instead of the packet

The most tempting mistake is letting the system approve things. It reads well in a demo: the model reviews the documents and grants the tier. Then a case arrives that needed a human to notice something nobody wrote down, and the decision is defensible to nobody. Automate the assembly instead. Pull the documents, run the checks, lay the evidence out, and put one screen in front of a person with a yes and a no on it. That removes most of the work and none of the accountability.

What it costs to run once it is live

Model spend on an onboarding system is small, because most steps never touch a model. The recurring cost is integration maintenance: systems change their APIs, permissions get revoked, and a step that worked in March fails silently in September unless something is watching.

Run that with your own numbers and the point becomes obvious quickly. Model spend on this workload is usually a rounding error against a single integration breaking for a week. Budget accordingly, and be suspicious of any proposal where token cost is the headline number.

• Integration maintenance. The real recurring cost. Every connected system is a dependency with its own release schedule.
• Credential rotation. Service accounts expire and get revoked during unrelated security work. Monitor the auth path, not just the happy path.
• Template maintenance. Pricing changes, a new plan tier, a new region, and the template needs an edit. Budget an owner rather than a project.
• Sandbox environments. Testing a provisioning change against production is how you create a real account for a customer who does not exist.
• Infrastructure. A scheduler, a queue, a database and a log store. Small next to everything above.

How to tell whether you need this

Pull the last ten onboardings and answer five questions. It takes an afternoon and it decides the whole thing.

1. How many calendar days did each take, and how many hours of actual work went into it? A large gap is waiting, and waiting is what a sequence removes.
2. Which step was the last one done in each case? If the same step is late in seven of ten, you have one problem rather than a process problem.
3. How many steps had to be redone because the first attempt did not take effect? That count is your missing verification.
4. How many chase messages did a human write by hand? Those are free to automate and nobody enjoys writing them.
5. Can everyone in the room name the event that means onboarding finished? If two people give different answers, fix that before anything is built.

If the ten instances look similar and the gap between calendar time and touch time is wide, the build pays back on that gap alone. If they look nothing alike, automate provisioning and verification only, keep the sequence in human hands, and revisit when volume argues otherwise.

How to start

Bring artefacts, not a description. The first call goes fastest when we can look at real instances and a list of the systems that have to be touched.

• Ten recent onboardings, with their threads and tickets, however messy
• The list of systems something has to be created in, and who owns access to each
• The current checklist, if one exists, plus an honest note on where it lies
• Whoever will own the templates afterwards, on the call from the beginning

The first deliverable is a labelled graph of your real process with the missing verify steps marked. That document is useful even if you never build anything, which is the point of producing it first.