How Items Move

The state machine behind every workflow item: how it waits, gets worked, fails and retries, runs late, and recovers, and which phase setting decides each step.

The Model

An item is always in exactly one phase. Inside that phase it is hidden for a while after some events (a cooldown), then available, then held by whoever works it: a person who was assigned or claimed it, or an agent or API worker that pulled it. The holder ends the attempt by routing the item on, or by handing it back (fail, defer or release), which hides it again until it is retried. Two clocks run on top of this: the phase timeout and the workflow's end-to-end deadline.

An item enters a phase, may be hidden by a cooldown, becomes available, is held by a person or worker, and is either routed on or hidden again for a retry (after a fail, defer, release, claim expiry or seat auto-release). On its last attempt it goes to Exceptions. The phase timeout runs from entry in every state.Phase timeout clock: runs from entry, in every state belowwhen due: moves to its target, stops with "Move stopped", or only emits the eventEnters phasenew stay, 0 attemptsHiddencooldownAvailablecan be takenHeldclaimed or assignedRouted onnext phaseHidden againfail · defer · release · expiryExceptionsattempt limitcooldown endsno cooldownclaim · pull · assignroutehide endslast attempt
One stay in one phase. Leaving the phase, by hand, by an On arrival rule or by a timeout, opens a new stay in the next phase with fresh attempts.

The worker classifies; the platform counts and limits

Whoever works an item only says what happened to this attempt: done (route it on), a business problem (route it to a phase where a person fixes it), not ready yet (defer or release), or failed (fail with a reason). The phase configuration decides how long the item waits, how many attempts it gets, when it is late and when it goes to Exceptions. Do not count retries in your worker: a counter in memory is lost on restart, and the platform already keeps one per item.

Stays, Attempts & Passes

Every time an item enters a phase it starts a new stay. The stay is what the phase measures:

CounterMeaning
AttemptsHow many times the item was handed out in this stay. Each claim and each pull counts one. An item assigned to a person counts once if that person fails or defers it.
Fails, defersHow often the holder failed or deferred it in this stay.
PassesHow many times the item has entered this phase, this stay included. It is what stops an item from bouncing between two phases forever.
Entered atWhen the stay began. The phase timeout is measured from here.

A new stay starts with zero attempts. That is deliberate: an item sent back to a phase gets a fresh set of tries there, and the pass count is what limits how often that can happen. Every item response carries the current stay as processing, including attempt_count, passes and timeout_deadline, the moment the phase timeout will fire for this item.

A Running Example: Freight Billing

The rest of this guide follows one process. A logistics company bills its shippers each month: capture bots collect the transport documents, a validation bot checks each one against the carrier system, business rules are applied, analysts fix what the bots cannot, and an invoicing bot issues the invoice.

PhaseModeWorked byPurpose
Document validationPull onlyValidation botCapture bots create one item per billing batch here. The bot checks every document.
Business rulesStandardRules botContract rules and pricing for valid batches.
Pending issuesStandardBilling analystsData problems the bots found: a missing document, a wrong tax id.
EscalatedStandardBilling supervisorsPending issues that ran late.
InvoicingStandardInvoicing botIssues the invoice.
Done, CancelledTerminal—Finished batches. Clocks stop here.
ExceptionsBuilt inPlatform, then a personAutomation failures, as opposed to business problems.

Keep the two kinds of trouble apart. A business problem (the document does not exist, the tax id is wrong) needs a person who knows the customer: route it to a phase like Pending issues. An automation failure (the portal is down, the bot crashed) needs a retry or an engineer: fail the attempt and let the limits send it to Exceptions.

Worker Phases: Pull, Claims & Retries

The validation bot calls POST /phases/{phase_id}/items/pull with a filter (for example, only the shippers it supports) and an X-Ergon-Consumer-Id header naming the process. The platform hands out up to max available items, claims each one for that consumer, and counts one attempt on each. Items that are hidden, held by someone else, already completed for this stay or out of attempts are skipped.

For each item, the bot reports one outcome:

What the bot foundCallWhat the platform does
All documents validroute → Business rulesOpens a stay in Business rules.
A business problemroute → Pending issuesA person picks it up there, with the reason in a field.
Document cancelledroute → CancelledTerminal; clocks stop.
Carrier portal downfailHides the item for the retry delay (or the release cooldown, if longer); on the last attempt, moves it to Exceptions.
Not ready yetrelease or deferRelease hides it for the release cooldown; defer for the longer of its delay and that cooldown. On the last attempt, Exceptions.
Bot crashed mid-itemnothingThe claim expires: every seat on the item is cleared and it hides for the retry delay; the attempt it used stays counted. On the last attempt, Exceptions.

The phase's Processing tab holds most of the numbers; the phase timeout is on the Timeouts tab:

SettingValueWhy
Claim timeout1800 sLonger than the slowest real check, so only a crashed bot loses its claim.
Retry delayFixed, 3600 sPortal outages last hours, not seconds. Exponential backoff suits flaky calls.
When released here60 minHow long a “not ready yet” batch waits before the next look.
Max attempts5Five tries per stay, then Exceptions.
Max passes3At most three entries into this phase. See Exceptions below.
OrderingOldest firstBatches are billed in the order they were captured.
Phase timeout10080 min → ExceptionsA hard limit of 7 days in this phase, whatever the reason.

Make the limits fit together

Five attempts an hour apart take about five hours, well inside the 7-day timeout. If max attempts × wait were longer than the timeout, the timeout would always win and the attempt limit would never matter. Without a claim timeout, pulled items do not expire (unless the bot extends a claim with a duration). A crashed bot then holds them until the item's or the phase's timeout minutes release its seat; with neither set, until a timeout rule or a person moves the item. A Pull only phase created without processing settings starts with a 300 s claim timeout and a fixed 60 s retry delay; a standard phase starts with neither.

The bot can also extend a long claim (extend-claim), or finish with complete, which marks the stay done and moves the item along the phase's one declared route in the same call (pass target_phase_id when there are several, naming one of them; with none, the item stays put and is no longer handed out). A Pull only phase never assigns items, by hand or automatically; assignment groups there only restrict who may pull. A standard phase can carry exactly the same processing settings, for phases where both bots and people take items.

# Pull up to 10 batches for this bot process
curl -X POST https://platform.ergondata.ai/api/v1/workflows/phases/{validation_phase_id}/items/pull \
  -H "Authorization: Bearer {token}" \
  -H "X-Ergon-Consumer-Id: validation-bot-1" \
  -H "Content-Type: application/json" \
  -d '{"max": 10}'

# The portal is down: fail this attempt and let the phase decide the retry
curl -X POST https://platform.ergondata.ai/api/v1/workflows/items/{item_id}/fail \
  -H "Authorization: Bearer {token}" \
  -H "X-Ergon-Consumer-Id: validation-bot-1" \
  -H "Content-Type: application/json" \
  -d '{"reason": "infrastructure_failure", "details": "Carrier portal returned 503"}'

People Phases: Assignment & Working Hours

Pending issues is worked by the billing analysts. An assignment group bound to the phase hands each new item to one of them, using the binding's strategy: round_robin, least_loaded, random, or manual to leave items for members to claim. A per-member capacity keeps anyone from being buried. When an item arrives over a route with Carry assignees on, the people already on it stay if they may still work the new phase (never into a Pull only phase); otherwise the item is queued to the phase's group again.

The analysts work Monday to Friday, 8:00 to 18:00, so the phase has those working hours. Outside them, nobody can claim, pull or be assigned items in the phase. A person's own schedule applies to them too. An item that arrives while the phase is closed is not auto-assigned (routing_skipped), and nothing assigns it when the schedule opens: on Monday morning it waits in the queue until an analyst claims it or someone assigns it. (An item that came from a conversation is offered again when a member becomes available, the group changes or someone releases it.) Claim and pull work again as soon as the schedule is open.

Working hours do not pause the clocks

Timeouts are wall-clock minutes. A 2-business-day target set as 2880 minutes runs through the night and the weekend. Size timeouts for calendar time, and never put working hours on a phase that bots pull around the clock: they would stop pulling at 18:00.

Separately, anyone, person or bot, who has held an item longer than the item's or the phase's own timeout minutes (timeout rules do not count here) loses the seat, whatever the timeout move does: the item goes back to the queue (auto_released) after the phase's release cooldown, if it has one, and a bot's claim ends with its seat, so work does not sit with someone who is away. An item that came from a conversation and still has a group is offered to another eligible member (the last member released in that pass is excluded); the cooldown ends early only if that assignment lands.

Waiting: Cooldowns & Holds

A cooldown hides an item for a number of minutes. A hidden item is still listed (greyed on the board), but nobody can claim, pull, move, edit, delete or comment on it until the cooldown ends; attachments can still be added or removed, and timeouts still move it. Assigning it to someone ends the cooldown early, as does clear-cooldown. On a phase whose group assigns automatically, the item goes to a member right away and the cooldown ends then: there a cooldown does not hold it back.

CooldownStarts whenSet on
When created hereAn item is created in the phase (not items from a conversation channel).Processing tab
When it arrives hereAn item arrives over any route.Processing tab; a route's own arrival cooldown replaces it for that route
When released hereThe last person or worker lets go of it, or it is deferred or failed.Processing tab
Arrival cooldownAn item arrives over this route.Routing tab of the phase it leaves
  • After a fail, the item hides for the longer of the retry delay and the release cooldown. After a defer, the longer of its delay and the release cooldown. After an expired claim, the retry delay alone.
  • A route call can add delay_seconds to hide the item longer after the move, up to the destination phase's longest allowed defer; a longer delay is rejected.

Defer is for “not before a known time” (at most 7 days per defer). For “waiting on someone for weeks”, route the item to a phase where a person owns the wait; repeated defers spend attempts on every pull that finds it still not ready.

Deadlines: Phase Timeouts & Move Rules

The phase timeout is how long an item may stay in a phase. It is measured from the moment the item entered, and it keeps running while the item is hidden, deferred, assigned or claimed. When it is due, the platform emits workflows.items.timeout once for the stay and moves the item to the target: a phase reachable by a route, Exceptions (no route needed), or nowhere if you only want the event. If the move would break a pass limit, the item goes to Exceptions instead. A timeout move out of Exceptions is not diverted: it stops, with a “Move stopped” pill (see below). When the timeout moves the item, a worker that was still holding it loses it: its next fail, defer, complete or extend-claim with the same consumer id gets 409 claim_lost. The same happens when a person or the attempt limit moves it. If the claim only expired, with no move, those calls get 409 not_claimed instead, or 403 not_claim_holder once someone else holds the item. An event-only timeout leaves the claim alone.

The Timeouts tab has a default and an ordered list of move rules (timeout_rules in the API). Each rule says: if the item came from these phases and matches these conditions, wait this long, then move it here. The first enabled rule that matches wins; items that match none follow the default. In Pending issues:

RuleMatchesWaitThen
1Priority is Urgent240 minMove to Escalated
2Came from Invoicing (sent back)480 minMove to Escalated
DefaultEverything else2880 minMove to Escalated

Which wait applies to an item:

  • The item's own timeout, if someone set one (it is cleared when the item moves).
  • Otherwise the first enabled rule that matches, in order.
  • Otherwise the phase default. With none of the three, the item has no phase timeout.

Turn on On arrival on a rule (a wait of 0 in the API) to move the item as soon as it enters, instead of after a wait. It is a move, not a timeout: no workflows.items.timeout, and the item's own timeout does not delay it. Order still decides, so a timed rule above it that matches makes the item wait, and several On arrival rules with conditions send each item to a different phase. The route's conditions, the destination's required fields and max passes still apply. If they block the move, the item shows why, every On arrival rule is skipped for it and the next timed rule that matches (or the phase timeout) applies, and editing the item tries again at once. Rules that would move items in a loop cannot be saved. On arrival rules replace the “Move automatically” setting routes used to have; saved routes were turned into On arrival rules at the top of their phase's list.

The phase countdown on a board card (marked P) and processing.timeout_deadline in the API use this same resolution, so they show when the platform will actually act on a timeout, rules included. On arrival rules have no countdown: the countdown is the deadline that applies if the item stays. When the end-to-end deadline is closer, the card shows that one instead (marked G). Terminal phases have no timeout clock, though On arrival rules still move items out of them.

The End-to-End Deadline

Billing has to close within the month, whatever phase a batch is in. The workflow's global timeout covers that: 43200 minutes (30 days) from when the item was created, then move it to Exceptions. It does not restart when the item changes phase (not even when a route takes it to another workflow, whose global timeout then applies from the original start), it stops only in a terminal phase, and an item can carry its own global timeout. Without a target it only emits the event, and an item that already sits in the target phase stays there. When the global and a phase timeout are due together, the global one acts first. Its move needs no route and skips the exit gate. A move into Exceptions skips both gates, so it always succeeds, which is why Exceptions is the safe target. If the target is an ordinary phase, its required fields still apply: when one is empty the item stays where it is, with no “Move stopped” pill, and the global deadline does not fire again. After 15 minutes the phase's own timeout and attempt limit take over again. The target's pass limits apply too: over them the item goes to Exceptions instead. An item that is already in Exceptions cannot be diverted: the move is rejected and the item stays in Exceptions. Again there is no pill, and the global deadline does not fire again.

Exceptions & Automatic Redrive

Every workflow has one Exceptions phase, always last, with routes to and from every other phase already in place. Items get there when a person, agent or automation sends them with a reason, when they run out of attempts, when a move out of another phase by anything other than a person (a bot, an agent, an on-arrival rule, a timeout) would break a pass limit, or when a phase or global timeout targets it. Each entry records the reason, the phase the item came from, the source and the count of visits, and emits workflows.items.exception_raised. Leaving emits workflows.items.exception_resolved, saying whether it went back to its origin.

Portal outages are the most common failure in Document validation, and most of them clear on their own. Instead of a person moving each batch back, Exceptions gets a timeout rule:

RuleMatchesWaitThen
1Came from Document validation30 minReturn to the phase it came from
DefaultEverything elsenoneWait for a person

The batch returns to Document validation with a new stay and five fresh attempts. The phase's max passes of 3 is the loop guard: when a return would be its fourth entry, the move stops (see below) and the batch stays in Exceptions for an engineer. Without a pass limit, a permanently broken batch would cycle forever.

curl -X PUT https://platform.ergondata.ai/api/v1/workflows/phases/{exceptions_phase_id}/timeout-rules \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [{
      "enabled": true,
      "origin_phase_ids": ["{validation_phase_id}"],
      "condition": null,
      "timeout_minutes": 30,
      "target_kind": "origin",
      "annotation": "Redrive validation failures"
    }]
  }'

When the Automatic Move Stops

A timeout move can be impossible: Escalated requires an Escalation owner, and the late item has none. The platform does not retry blindly. It marks the stay, shows an amber Move stopped pill on the card with the reason in the item, and emits workflows.items.exhausted (again each time an edit retries the move and it is still blocked). The item stays where it is and can still be worked.

ReasonCauseResumes when
Route blockedThe route's exit gate or the destination's landing gate failed: a required field is empty or a route condition does not match. The card names the fields.Someone fills a field or attachment, or the rules or phase default change.
Target missingThere is no recorded origin, the target or origin phase was deleted or is in another workflow, the target is the same phase, the origin is Exceptions, or there is no route.The rules or the phase default are saved again. Adding the missing route alone does not resume it.
Max passesA timeout move out of Exceptions (back to the origin or to the phase's target) would break a pass limit, or the item is going back to its origin and last left it because a move from there hit a pass limit.Not on its own, and not by edits or by raising the limit. It ends when any move lands (by a person or an integration, or by the global timeout) in a phase where neither the phase nor the route limit is reached. Moving it out of Exceptions over either limit is rejected for everyone.

A move that lands in another phase clears it, because the item starts a new stay. The Exceptions drawer can show only the stopped items that sit in Exceptions with Exhausted only; elsewhere, look for the pill on the card. Saving the rules or the phase default also re-runs timeouts that already fired, so giving an event-only rule a target moves those items once they are due under the new rule.

Gates & Limits

Every move follows a route, except a global timeout. A route can have an exit gate (conditions to move, checked on the item's values) and the destination phase has a landing gate (its required fields). Who checks what:

MoveExit gateLanding gateRoute needed
A person, agent or bot routing itYesYesYes
On arrival move ruleYesYesYes
Phase timeoutYesYesYes
Global timeoutNoOnly into an ordinary phaseNo
Into ExceptionsNoNoBuilt in
  • An On arrival move rule is checked when the item arrives and again after each edit. If a gate blocks it, the item shows why and the next matching timed rule or the phase timeout applies; fill the fields to move it.
  • Max passes exists on the phase (entries however they arrive) and on a route (entries over that route). Both apply to every phase, Pull only and terminal phases included; only entries into Exceptions are never limited. Anyone moving an item out of Exceptions over a limit gets 409 max_passes_exceeded. From any other phase, only a person gets that error; a call made with a person's sign-in token counts as a person. Every other caller, such as a bot using an API key, an agent or an automation, is not rejected: the call succeeds, the item goes to Exceptions instead and workflows.items.max_passes_exceeded is emitted. On arrival rules and phase and global timeouts from an ordinary phase do the same. complete follows the same rule as a route. A route or complete response then has diverted set (reason, requested_phase_id, requested_phase_name, limit, passes); otherwise it is null.
  • Out of Exceptions, a timeout move (back to the origin or to the phase's target) over a limit stops with “Max passes”. A global timeout move is rejected and the item stays in Exceptions.
  • A bulk route checks each item. When the caller is a person, or an item is leaving Exceptions, an item over a limit rejects the whole batch: 409, with one entry per failing item in detail.errors (item_id, code set to max_passes_exceeded, and detail with limit and passes). For any other caller, items over a limit go to Exceptions and are listed in diverted (the same fields plus item_id), not in succeeded.
  • Entries into Exceptions are never limited and never gated.

Settings Reference

Every setting that shapes how items move, by where it lives in the phase editor.

SettingTabWhat it doesUse it to
Processing modeProcessingStandard (people and workers) or Pull only (workers take items; nobody assigns). Fixed at creation.Keep bot queues free of manual assignment.
CooldownsProcessingHide items after create, arrival or release. Automatic assignment does not wait for them.Space out retries; give upstream systems time.
Claim timeoutProcessingHow long a worker's claim lasts before it is released.Recover items from crashed workers.
Retry delayProcessingWait after a fail or an expired claim: none, fixed or exponential.Ride out outages without hammering a system.
Longest deferProcessingCap on one defer, and on a route's extra delay.Stop workers parking items for months.
Max attemptsProcessingAttempts per stay before Exceptions.Turn repeated failure into a visible exception.
Max passesProcessingEntries into the phase per item.Stop loops, including automatic redrive.
OrderingProcessingOldest or newest first on pull.Match the business order of work.
Phase timeoutTimeoutsDefault wait and target for the phase.Set the service level for a step.
Move rulesTimeoutsOrdered waits and targets by origin and conditions, or On arrival with no wait.Different deadlines for different work; skip steps that need no one.
Return to originTimeouts (Exceptions)Default target that sends an item back where it came from.Retry automation failures automatically.
Working hoursTimeoutsWhen items in the phase can be taken or assigned.Match the team's schedule.
Assignment groupsAssignmentWho works the phase, by which strategy, with what capacity.Spread work evenly and fairly.
Conditions to moveRoutingThe route's exit gate.Require data before a step is done.
Route max passesRoutingEntries over this route.Limit returns along one path.
Carry assigneesRoutingKeep the people on the item across the move.Let one owner follow the item.
Arrival cooldownRoutingCooldown for arrivals over this route.Delay only one path into a phase.
Global timeoutWorkflow settingsEnd-to-end deadline and its target.Enforce the process deadline.

Per item, timeout_minutes and global_timeout_minutes override the phase and workflow deadlines for that one item. The field-by-field API is in the Workflows API Reference.

Events

Each step emits an event that automations and integrations can react to. All are in the event catalog.

StepEvents
Movesworkflows.items.created, workflows.items.routed
Assignmentgroup_assigned, auto_assigned, assigned, claimed, released, auto_released, routing_skipped, routing_failed
Workerspulled, claim_extended, claim_expired, failed, deferred, completed, attempt_limit_reached
Waitingvisibility_restored, cooldown_cleared
Deadlinestimeout, global_timeout, exhausted
Exceptions and limitsexception_raised, exception_resolved, max_passes_exceeded

Names after the first row omit the workflows.items. prefix.

Why Didn't My Item Move?

Open the item and check, in this order:

  • Terminal phase? No clocks run there.
  • Move stopped? The pill and the item say why: fill the named fields, fix the target or route and save the Timeouts tab, or move it by hand.
  • No deadline? If timeout_deadline is empty, no item timeout, rule or phase default applies to it.
  • Hidden? A cooldown, retry delay or defer is running; the card shows it greyed.
  • Held? Someone has it, or a worker's claim has not expired yet.
  • Out of attempts? It is on its way to Exceptions, or there already.
  • Outside working hours? Nobody can take or receive it until the schedule opens. If it arrived while the phase was closed, it was not auto-assigned and will not be when the schedule opens; claim or assign it.
  • On arrival rule did not move it? A timed rule above it matched, or a gate blocked it: the item says which fields or route are missing. Fill them and it moves.
  • Bouncing? Set a max passes on the phase or the return route.

For the building blocks themselves (phases, fields, routes, groups), see the Workflows guide.