A transition is a defined move from one workflow step to another. It is how a shipment progresses — you do not edit the step, you run the transition, and the system records who did it and when.
Running one
Open the shipment and choose Transition. You see only the transitions available from the shipment's current step, and only those you are permitted to run.
Most transitions present a form before completing. That form is not decoration: it collects the information the next step depends on, which is why a transition is the right place to capture it — the data arrives at the moment it becomes true.
Why a transition might not be offered
| Reason | What to do |
|---|---|
| It does not start from the shipment's current step | Check which step the shipment is actually in. |
| You are not one of its permitted operators | Each transition names who may run it. Ask whoever is. |
| It is disabled | Someone has switched it off in configuration. |
| A precondition fails | Something the transition requires is not yet true — see below. |
Preconditions
A transition can carry preconditions: condition checks that must pass before it runs. This is how the process is enforced rather than merely described — a shipment cannot reach ready for release if the checks for that step have not been satisfied.
A failure reads "Preconditions not met for transition …". The fix is in the data the check is looking at, not in the transition: fill in what is missing on the shipment and try again.
A different message — "Error checking precondition (…)" — means the check itself could not run. That is a configuration or system fault, not missing data, and it should be escalated rather than worked around.
Post-actions — what happens automatically
Completing a transition can trigger post-actions. These run for you, which is why transitions are worth using properly:
| Post-action | Effect |
|---|---|
| Email notification | Sends a message — to the customer, the agent, an internal team. |
| Update entity | Writes values onto the shipment or a related record. |
| Generate template | Produces a document from a template. |
| Generate XML | Produces an XML message for an external system. |
| Call microservice | Triggers another part of the platform. |
So a single transition might set the actual departure date, generate the bill of lading, email the consignee and notify customs — all from one action. This is the reason to move shipments with transitions rather than by editing fields. An edit changes the record; a transition changes the record and does everything that is supposed to accompany it.
If a document was not produced or an email was not sent, the first question is whether someone advanced the shipment by hand. If the transition was run, look for "Post action execution failed for type …" — the step completed but its follow-up did not, so the shipment has moved on while the document or notification has not happened. This is the failure mode worth watching for: the shipment looks correct and something downstream is silently missing.
Document-generating post-actions have their own configuration requirements — a template must be available for the entity type in question, and a persisted document needs somewhere to save to. Those failures name the template, so take the name to whoever maintains them.
Running a transition on several shipments at once
Transitions can be run in bulk. The rule is all-or-nothing on the starting step:
Every selected shipment must already be in the transition's from step. If any is not, the whole run is refused with "Some shipments are not in the expected step …", followed by the details of which ones.
Nothing is applied partially — the shipments that were eligible are not moved either. Correct or deselect the odd ones out and run it again.
A related refusal, "Some shipments not found", lists the IDs that could not be resolved. That normally means a selection made against a stale list.
Transitions on other entities
Transitions are not confined to shipments. Containers, master shipments and voyages each have their own transition screens, driven by their own workflows. A container can move through a yard process independently of the shipment it belongs to. See Master shipments, containers and voyages.
What a transition holds (for administrators)
| Field | Notes |
|---|---|
| Name, Description | What it is called and what it does. |
| From step / To step | The move. |
| Target entity / Entity name | What it acts on. |
| Form config | The form shown when it runs. |
| Operators | Who may run it. |
| Preconditions | Checks that must pass. |
| Post-actions | What runs afterwards. |
| Enabled | Whether it is available at all. |
Forms are built with the form builder.
A note on designing transitions
Ask for the minimum at each step. A transition form with twenty fields, most of which the operator cannot know yet, gets filled with placeholder values — and placeholder values are worse than blanks, because nothing downstream can tell them apart.
If a shipment is stuck
- Check its current step on the shipment record.
- Look at what transitions exist from that step — an administrator can see them on the workflow.
- If a transition exists but is not offered to you, it is operators or enabled.
- If it is offered but fails, it is a precondition — the message says what.
- If no transition leaves that step at all, the workflow has a dead end and needs fixing. See Workflows.
Last updated 9 September 2026