A workflow is the process a shipment follows: the ordered set of steps it passes through from booking to completion. It is defined in the system rather than written down in a procedure note, which means the system can enforce it — a shipment cannot skip a step, and each step can require specific information before it is left behind.
What a workflow holds
| Field | Notes |
|---|---|
| Code | The workflow's identifier. |
| Description | What this process is for. |
| Entity | What it applies to — shipment, LCL shipment, FCL shipment, air shipment, container, master shipment, vessel, voyage, storage, warehouse, truck, LCL or FCL clearance. |
| Shipment type | Import or export. |
| Steps | The ordered list. |
Workflows apply to more than shipments. A container, a voyage or a clearance can each have their own workflow — which is how a container's movement through a yard is tracked independently of the shipment it belongs to.
Steps
Each step carries:
| Field | Notes |
|---|---|
| Code | The step's identifier, used by transitions. |
| Name | What operators see. |
| Description | What has to be true at this step. |
| Order | Position in the sequence. |
| Is initial | The step every new record starts at. |
| Is terminal | An end state. |
Step codes must be unique within a workflow — "Each step must have a unique code within the workflow."
Exactly one step must be initial, and this is enforced at the point it matters: a workflow with none fails with "No initial step found for workflow …" when something tries to start. A workflow can therefore be saved in a state that only breaks later, so check it after editing.
There can be several terminal steps — a normal completion and a cancellation are both endings, and it is worth modelling them separately so your reporting can tell them apart.
Designing a workflow
Some hard-won advice:
- Model what happens, not what should happen. A workflow that omits the "waiting for customer documents" step because it shouldn't occur will have shipments parked in the wrong step instead, and nobody will be able to see why.
- Keep steps meaningfully distinct. If two steps are always crossed in the same minute, they are one step.
- Name steps as a state, not an action. Awaiting customs clearance tells you where a shipment is; Clear customs does not.
- Give every non-terminal step a way out. A step with no outgoing transition is a dead end, and a shipment that reaches it is stuck for good.
Steps do not move on their own
A shipment's current workflow step changes only through a transition — a defined move from one step to another, with its own permissions, form and consequences. See Running a transition.
This is the point of the design: progress is an action someone takes and the system records, not a field somebody edits.
The workflow editor
Beyond the list-based view, workflows have a graphical editor for laying out steps and the transitions between them. Use it to check the shape of a process — dead ends and unreachable steps are obvious as a diagram and easy to miss as a list.
Changing a live workflow
Workflows govern shipments already in flight. Before editing one:
- Removing a step leaves any shipment currently sitting in it in an undefined position.
- Renaming a step's code breaks the transitions that reference it.
- Disabling a transition can strand shipments whose only route forward was through it.
Where a process change is substantial, create a new workflow and use it for new shipments, rather than reshaping the one that live jobs are running on.
The timeline
A shipment carries a timeline: the steps it has passed through, which is current, and when it became current. This is the operational history — the answer to "when did this actually clear customs?" — and it accumulates without anyone maintaining it, provided people move shipments with transitions rather than by editing.
Last updated 15 September 2026