- A supplier uploads a catalogue.
- The parent workflow may be waiting for a child.
- A transaction ID does not answer any of those questions.
- For a Medusa marketplace with long-running imports, bulk catalogue work and image processing, we built an operational workflow monitor around business execution families.
The client problem
A supplier uploads a catalogue. The request returns. Ten minutes later, operations still sees “running”.
What does that mean?
The parent workflow may be waiting for a child. A child may still be processing. One step may have failed while compensation is underway. The workflow engine may have removed a completed live row. Or an active execution may simply have stopped updating.
A transaction ID does not answer any of those questions.
For a Medusa marketplace with long-running imports, bulk catalogue work and image processing, we built an operational workflow monitor around business execution families. Each instrumented launch records why it started. Nested workflows keep their parent and root transaction identities. Live engine state is projected into a durable log, and active work with no recent update is labelled stale without pretending that staleness is itself a failure.
The result is not another developer log viewer. It is a timeline an operator can use to decide whether to wait, investigate or act.
The client problem: one business action creates many technical executions
“Import this catalogue” sounds like one operation.
Underneath, the platform may validate a file, stage rows, create or update products, categorise them, localise images, synchronise search and reconcile failed items. Some work runs synchronously. Some is queued. Some launches its own children.
When those executions appear as unrelated rows, support loses the business story. A failed child looks like an isolated technical incident. A parent looks inactive even while its descendants continue. Searching by one transaction reveals only one fragment.
That makes ordinary questions expensive. Is the supplier's import still progressing? Which step last changed? Did a child fail? Is the original execution complete but absent from the live table? Are two rows part of the same user action?
The marketplace needed lineage, state and time expressed together.
Give every workflow a reason and an identity
The tracking wrapper enriches an instrumented Medusa workflow at launch.
It records the workflow ID, transaction ID, synchronous or asynchronous mode and a source describing what initiated the work. When the request context is available, it can also retain the request, actor, host and process information useful for investigation.
These fields turn an opaque execution into an operational event. “Workflow X, transaction Y” becomes “an asynchronous catalogue reconciliation started from this administrative action”.
The context travels with the workflow rather than depending on a log line surviving somewhere else. After launch, the project persists the tracking data into the workflow execution record with bounded retries, accounting for the short interval in which the engine row may not yet be visible.
The technical identifier remains useful, but it now belongs to a recognisable business action.
Preserve the family when one workflow launches another
Nested work is where flat monitoring breaks down.
When a workflow launches a child, the child receives the parent workflow ID, parent transaction ID and the root transaction ID of the original business action. A direct child and a grandchild therefore share a root even though each has its own execution identity.
This creates two useful views.
The parent link answers: which execution directly caused this work? The root link answers: which original marketplace operation does this entire chain belong to?
The distinction matters when a catalogue import launches several siblings or when one of those siblings launches further processing. Operators can inspect a local dependency without losing the complete case.
Lineage is written when the child is launched. The monitor does not attempt to infer families afterward from timestamps or similar names.
Project engine state into a durable monitor
Workflow-engine tables are designed to run workflows, not necessarily to provide permanent operational history.
The project adds a monitor log as a read model. It snapshots the latest execution state and tracking context, together with creation time, update time, last-seen time, duration and progress counts.
If a launch is recorded before its live engine row becomes queryable, the monitor can create a fallback entry using the known workflow and transaction identity. Later refreshes replace that provisional view with live state.
The log also survives the disappearance of an engine row. During refresh, active entries no longer present in the engine are closed in the monitor after a short observation window instead of silently vanishing.
This gives operations continuity. A completed job remains part of the timeline even when the execution engine has moved on.
Count progress without inventing a percentage
The execution record contains step states. The monitor turns those details into operator-friendly summaries.
It counts the workflow steps, how many have completed and how many currently sit in each state. It also exposes the age of the last update and the elapsed duration.
These numbers are more honest than a generic progress bar. Three completed steps out of five do not necessarily mean sixty percent of the work or time. One remaining step may contain most of the processing.
But the summary still answers valuable questions. Has any step completed? Is the same step state persisting? Did activity move recently? Is compensation happening? Does the detailed execution contain a failure state?
Selected workloads can add domain metrics. Image processing, for example, can expose claimed, localised, reused and failed counts alongside the generic workflow state. The monitor stays common while the business workload contributes meaningful detail.
Distinguish “stale” from “failed”
An execution can remain in an active engine state without changing for a long time.
The monitor labels an active workflow stale when its last activity is older than ten minutes. The threshold applies to states such as invoking, not started, waiting to compensate or compensating.
Stale does not mean failed. It means the system expected an active execution, but the observable record has not moved within the operational window.
That distinction protects two decisions. Operations can filter stalled-looking work without declaring a false terminal outcome. Engineering can investigate whether the worker is genuinely blocked, waiting on an external dependency or merely missing expected progress updates.
A failed workflow has a terminal engine state. A stale workflow has an active state plus an age signal. A completed workflow has a terminal history. Those are different stories and should look different in the interface.
Make the parent reflect activity in its children
A parent can appear quiet while a child is doing the real work.
The dashboard builds a tree by matching each child's parent transaction identity to rows returned by the monitor query. Children are nested beneath their parent. The parent is then sorted using the most recent activity found in its returned subtree, not only its own timestamp.
This keeps an active business case near the top even if the root execution has not updated since it delegated work.
The interface also shows child counts and lets operators filter by parent or root transaction. They can start from one suspicious execution and find related work, or open the original root and understand the chain.
The tree represents relationships present in the returned data. It does not claim to reconstruct a child omitted by a filtered or paginated query. That boundary is preferable to displaying invented completeness.
Let operators search in business-relevant ways
The monitor can filter by workflow and transaction identity, but those are only the starting points.
Mode separates synchronous calls from asynchronous jobs. Source explains which product action launched the workflow. Parent and root transaction filters navigate families. Actor and host context support investigation. State and active-versus-stale filters separate terminal failures from stalled-looking work. Date filters narrow an incident window.
The operator can therefore move from “a supplier says its import never finished” to a bounded set of executions connected to that operation.
The detail view adds the execution steps, state distribution, duration and last-update age. The investigation remains anchored in the same durable record instead of jumping between a notification, database console and application logs.
This also improves communication with the supplier or internal requester. Support can say that the original import completed its staging phase and that a named child is still processing, rather than repeating the meaningless message “the system is working”. If a child failed, the team can identify the affected operation without presenting raw infrastructure logs. Operational transparency becomes part of the service experience, not only an engineering convenience.
Connect stale workflows to the action queue
The separate Control Center turns current marketplace exceptions into assigned work. Workflow monitoring contributes to that system rather than competing with it.
Actionable failed executions and active executions marked stale can become Control Center items with a route back to the workflow monitor. The queue answers “what needs attention?” The workflow timeline answers “what happened inside this operation?”
That separation keeps the operator experience focused. The Control Center does not need to reproduce every workflow step. The monitor does not need to become a general task-management system.
Together they provide ownership and diagnosis: a stable item keeps the problem visible, and the linked execution family provides the technical story required to resolve it.
Why Medusa needed an operational extension
Medusa's workflow engine provides the foundation for durable, compensatable commerce operations. The client's marketplace still needed a way for non-developers to understand those operations across many custom capabilities.
The project did not replace the engine. It added context at launch, preserved lineage between nested workflows and built an operational projection over execution state.
That is the value of choosing an extensible commerce platform. The engine remains responsible for execution semantics. The project can add the business-specific observability needed for supplier imports, catalogue jobs and other long-running work.
Architecture serves the operating model: the platform can grow more capable without becoming more opaque to the people running it.
A workflow-operability checklist
Before putting a long-running marketplace workflow into production, ask:
- What business action started it?
- Does it have one durable transaction identity?
- Is the source recorded with the execution?
- Can nested work name its direct parent?
- Can every descendant name the root transaction?
- Is launch context persisted after the engine row appears?
- Does an operational history survive live-row cleanup?
- Are step totals and state counts visible?
- Is last-update age different from total duration?
- What threshold marks active work as stale?
- Does stale remain distinct from failed?
- Can a parent surface recent child activity?
- Can operators filter by source, lineage and state?
- Do domain-heavy workflows expose useful counters?
- Does an actionable incident link back to the timeline?
If those answers are missing, “running” will eventually become a support ticket nobody can interpret.
The broader lesson
Long-running commerce work is not operable merely because it has logs.
The platform must preserve why an operation started, how its children relate, what state each execution reached and when anything last changed. It must keep terminal history without confusing an old active state with a proven failure.
For this marketplace, we built a workflow family around root and parent transaction identities, projected engine state into a durable monitor and gave operators a clear stale signal alongside real terminal states.
That turns a spinner into a story: what started, what it launched, what progressed, what stopped moving and where the team should look next.
As the marketplace adds more custom workflows, the same vocabulary continues to work. New capabilities may expose different domain counters, but they enter the same family model: source, root, parent, state, activity and outcome. The monitoring system scales with the platform's business surface instead of creating a new dashboard for every feature.