Batches and lanes

A batch is one run of one motion version over a set of companies. It’s what you open, watch, and finish. The batch screen is a wall: one row per company, one column per step, and in each cell a brick showing where that company is on that step.

Opening a batch

You open a batch on a motion, from the app’s Batches page, the motion’s page, or motions open. You choose:

• The companies: a CRM company list, by name or id, or a set of company record ids. The motion’s input.list is the default.
• The version: the live one, unless you’re trying a draft on real companies.
• A label, such as “week 45”, so people can tell batches apart.

The batch reads each company from the CRM when it opens, and keeps that version for its whole life. Pushing a new version doesn’t change an open batch until someone upgrades it.

How companies move

Each company goes through the steps in order, independently of the others. Each step names the steps it runs after, by default the one before it, so steps can also run side by side.

Most steps run per company: as soon as a company is through the steps before, its cell becomes ready and runs. Two kinds of steps wait for the batch instead:

• A batch step runs once, over every company that reached it, when none are still on their way.
• A checkpoint or a changeset is a barrier. Companies collect there until the rest of the batch catches up, a time passes, or someone acts.

Brick	Kind	What it means
	Company step company	Runs your code once for each company. Most steps are this kind.
	Batch step batch	Runs your code once over every company that reached it, after none are still on their way. Use it to compare companies, such as finding duplicates.
	Checkpoint checkpoint	Runs no code. Holds every company until a time, an event, or someone releases it.
	Changeset changeset	Runs no code. Seals the CRM changes proposed so far into one package for an approver.

Cells

Each brick is one company at one step:

Brick	State	What it means
	Pending pending	The company hasn't reached this step yet.
	Ready ready	Queued: it runs as soon as there's room.
	Running running	The step is running for this company now.
	Retrying retrying	The last run failed in a way that may pass on a second try, such as a timeout or a rate limit. It runs again after a pause.
	Asked asked	The step asked a question and waits for someone to answer it.
	Done done	The step finished and saved its facts.
	Skipped skipped	The step's when condition didn't match this company, so it didn't run.
	Failed failed	The step threw an error, or used up its retries. The company is parked until someone retries it.
	Parked parked	The step stopped on purpose: it hit a spending cap, a provider ran out of credit, or the step is waiting on a timer (ctx.wait) and runs again later.
	At barrier barrier	The company is through everything before this step, and waits here for the rest of the batch.
	Approval approval	The company's CRM changes are sealed in a changeset that waits for an approver.
	Writing writing	The changeset was approved and Motions is applying it to the CRM.
	Passed passed	The checkpoint was released, or the changeset was written.
	Stopped stopped	This step won't run: the company left the batch, or its changeset was rejected.

Lanes

Each company is in one lane at a time, shown at the end of its row and counted at the top of the batch:

Brick	State	What it means
	Done done	Through every step.
	Moving active	Steps are running or queued for it.
	Waiting waiting	A step asked a question; the company waits for the answer.
	Parked parked	It stopped and needs someone: a step failed, hit a spending cap or ran out of provider credit. A company whose step is waiting on a timer shows here too, until the step runs again.
	Held held	Kept out of this batch on purpose: a step or an answer held it, or its changeset was rejected.
	Dropped dropped	Removed from the batch, with a reason such as no domain or outside the ICP.

A company is out of the batch, for good, once it’s done, held or dropped. The batch is finished when every company is, and every changeset is written or rejected.

What moves a stuck company

The company is	Someone
Waiting on a question	answers it, from Questions, Today or the batch. If nobody does by the queue’s deadline, the queue’s default answers.
Parked after a failure	fixes the cause, then chooses Retry in the company’s drawer, or Retry failed in the batch’s More actions menu for all of them.
Parked on a spending cap	raises the cap in a new version, upgrades the batch, then retries.
Parked on a timer	waits: the step runs again when the time comes.
At a checkpoint	waits for its time or event, or an approver chooses Release in the batch’s More actions menu.
At a changeset	an approver approves or rejects it.

See Fix a stuck batch for each case.

Pausing

Pause, at the top of the batch, stops new step runs and changeset writes. Runs already going finish. Resume picks up where it left off. Questions can still be answered while paused.

Upgrading a batch

Upgrade, at the top of the batch, moves it to another version of its motion, usually a newer one with a fix. When you upgrade:

• Steps whose code or rules changed run again for the companies that already ran them. A later step runs again when what it reads changed as a result.
• Companies already sealed in a changeset keep what was sealed.
• The app previews what will run again before you confirm.

A step that has already started can’t be removed, change kind, change what it runs after, or move earlier; the upgrade is refused with the reason. This is how you fix a bug mid-batch without starting over.

The record

Every batch keeps an append-only log of what happened: each step run and its result, each question and who answered it, each changeset and who approved it, and every source call with its cost. The company drawer shows a company’s part of it; nothing in it is ever edited.

Runs are repeatable

Inside a step, Math.random is seeded and Date is fixed at the moment the run was dispatched, and source answers are cached. Running the same version on the same company gives the same result, which is what makes retries and upgrades safe.