Journeys
A journey describes one situation you want your system to play out: where a request starts, what data it carries, and how far the run may go. The diagram is the map; the journey is the trip.
What a journey is
The editor calls these records Journeys. In the saved document and API they are scenario drafts containing ascenario.v1 document, expression.v1 expressions, and canonical-json.v1 serialization. A journey never changes your diagram. It answers three questions: where does the run start (which component and output port), what data is involved (the request payload and any records already sitting in databases, caches, queues, or dependencies), and when should the run stop (limits on events and virtual time).
The compiler turns the compatible graph and scenario into a normalized execution plan. The run stores graph, scenario, plan, engine, executor, and serializer versions with a reproducibility key. The same saved graph, journey content, fixtures, limits, and pinned versions therefore produce the same deterministic event record; a new run still starts from fresh fixture state.
Create a journey
- In the editor, open the Journey tab in the workbench dock at the bottom of the screen.
- Press New journey, or Clone variant to start from a copy of the current one. The Active journey dropdown switches between drafts. A clone keeps a source link and can be grouped in the same journey family.
- Fill in the form — it walks through 01 Setup, 02 Starting data, 03 Run limits, and 04 Run check. Changes autosave as you type.
The journey form at a glance
01 Setup — a name and description, an optional journey family, and the start component and start output port where the run begins. A source actor is the usual starting point, but an eligible boundary output can also be a start.
02 Starting data — Input data (JSON, up to 256 KiB) and Starting component state. The fixture object is keyed by component ID so Mockflow can put each value in the right simulated database, cache, queue, object store, or dependency.
03 Run limits — a non-negative run reference number, max events from 1 to 10,000, and max virtual time in milliseconds. Virtual time is simulated time, not real waiting time.
04 Run check — live compatibility diagnostics for the current diagram and the starting data.
The form autosaves after a short pause. Use Save now when you need an immediate save. If another edit wins the save, choose Keep mine or Use latest; do not assume the draft was saved until the form says All journey changes saved.
Inputs and fixtures
The input payload is the JSON carried by the first token. Fixtures are the state that exists before that token is emitted. The engine copies fixtures into run-local state, so a cache write, queue transition, workflow step, or database mutation cannot overwrite the journey's starting JSON or another run.
A concrete cache-aside setup
Start at component client, output requestOut, with input data { "productId": "sku-42" }. Give the component cache an empty fixture and the component database a products collection containing key sku-42 with { "name": "Desk lamp" }. A safe example can use seed 0, max events 1000, and max virtual time 3600000 milliseconds.
Fixture contracts follow the configured component. Cache entries use the configured cache key. A database fixture is a collection keyed by record key. An object-store fixture is a bucket keyed by the scalar value at its configured key path, and a stored object needs its configured status to count as a hit. Queue fixtures contain messages keyed by deterministic message ID. A fixture target that is missing or has the wrong component type makes the journey incompatible.
The form requires starting component state to be a JSON object keyed by component ID. Payload and fixture content are checked against the 256 KiB payload and 10 MiB aggregate fixture limits. Keep values small and explicit so the resulting event and state diffs remain useful.
Keep the journey compatible
The run check compares the saved scenario with the current graph. It verifies the schema, expression, and serializer versions; the start node and eligible start port; fixture targets and component types; and content limits. A database fixture collection that no longer matches the Database settings is a review warning rather than an invisible rewrite.
The panel uses Ready, Check needed, Fix needed, and Checking. A graph change can remove the selected start node or port, change a fixture target, or require review. The command-bar run menu lists only saved, compatible journeys.
If a journey is missing from the run menu, open the Journey tab, repair the highlighted start, fixture, or version problem, and wait for the draft save and compatibility check to finish.
How a run executes
A compatible journey is compiled before it runs. The plan contains the entry, normalized nodes and edges, interactions, limits, estimated counts, and executor versions. The deterministic scheduler then orders actions by virtual time, priority, and scheduling order. Node durations, boundary latency, waits, and retry backoff advance the simulated clock.
Port handlers run their ordered actions. The supported action shapes include call, await, map, for_each, emit, respond, fail, and assign. Conditions are evaluated against payload, input, variables, fixtures, or arrival context. Calls can wait for a response; a for-each dispatches bounded child work; a catch can route a handled failure with rejected or degraded outcome.
Branches carry token lineage. A join records each matching arrival, becomes satisfied when its barrier is met, or records a timeout when a required branch does not arrive in time. A timeout can schedule a retry when the interaction policy allows it. Queue failures can be requeued or dead-lettered, and workflow failures can run compensation. The full order is visible in the Events reference.
Run it
The fastest path is the numbered Run 01 control in the editor command bar. Wider viewports also preview its journey name; the label contracts as space becomes tighter. Its arrow always lists every compatible journey with the full name as 01, 02, and so on. Choose a journey to make it the active run choice, then press the main numbered button to save pending journey edits and start it immediately. The run dock opens automatically.
You can run directly from the Journey tab with Run this journey, or switch to the Run tab and press Run journey. The panel shows Preparing, Running, Stopping, Finished, Stopped, or Failed. A stopped run can be guarded or cancelled; its artifact summary explains which terminal status was recorded. Use Try again to start a new run from the same saved fixtures.
Timeline and Transcript keep the completed journey name, run number, reference number, and draft provenance visible. Choosing a different next journey does not relabel the immutable run being inspected.
A finished artifact reports event count, virtual duration, optional terminal code, responsible component, and run hash. The summary also reports warning and error counts, stages, tokens, outcome, and remediation when available. These runs demonstrate configured behavior and ordering; times and results are examples, not production predictions.
The run test executes in your browser and does not change your working diagram or journey. Only treat data as real when it is explicitly marked as imported.
Understand reads, writes, and run state
Every run starts from a fresh copy of the journey fixtures. A cache write, queue transition, workflow step, or database mutation changes only that run's simulated state. Run the same saved journey again and it starts from the same fixtures, content, limits, and pinned versions.
A current Database component can get or query records, or insert, update, upsert, and delete them. For a write, Record path selects the record inside the incoming JSON and Key path selects that record's stable key. For example, a payload shaped like {"job":{"jobId":"job-1001","status":"open"}} uses /job as its record path and /jobId as its key path.
In the run timeline, a successful write produces a database mutation event followed by a state patch. Inspect the state before and after that patch to see the exact record that changed. Insert fails when the key already exists; update and delete fail when it does not; upsert handles either case.
Record and key paths use JSON Pointer syntax: an empty path selects the whole value, while a nested value starts with /. Editor diagnostics report an invalid path. The journey compatibility panel reports a fixture collection name that does not match the Database settings.
Replay it, step by step
After a run, switch to Simulate mode to replay the stored artifact without changing anything. This is playback of the recorded event log, not a second execution. The controls play and pause, step one event or one stage in either direction, scrub to a position, restart, and change speed. Watch the canvas while it plays; the active connection and current step follow the selected event.
The Timeline and Transcript show the same authoritative events. Inspect can resolve payload before and after references and reconstruct state before and after an event from the run's automatic state checkpoints. A new Try again run starts fresh and has its own run hash; it is not a mutation of the stored artifact.
Breakpoints pause review at a node, stage, event kind, error, or simple attempt or virtual-time condition. They change playback only, not the run result. See Runs & events for the event kinds and timeline reading guide.
Compare journey variants
Give related journeys the same journey family — say, “Checkout” with a happy-path variant and a payment-fails variant. The Journey matrix panel can then run several variants side by side and show each one's status, path, and outcome in a table.
On the canvas, the Journey route focus toolbar highlights routes: All topology shows the whole diagram, Potential route highlights the path the selected journey could take, and Actual route highlights the path the latest run really took — everything else dims so the story stands out.
Add journeys to a checkpoint
A draft is where you keep working; a diagram checkpoint is a saved review point that does not change underneath you. Select Checkpoint in the editor command bar, add an optional message, choose the compatible journey drafts to include, and create the checkpoint. The checkpoint stores a graph revision and immutable snapshots of the selected scenario content and hashes.
You can make a diagram-only checkpoint when there are no journeys. A journey with a problem cannot be included until it is repaired. Creating a checkpoint never replaces your working draft; the project keeps at most five diagram checkpoints.
This is different from a state timeline checkpoint. The latter is created automatically inside a run artifact so playback can reconstruct component state efficiently. It is not a saved journey version and it is not the editor's Checkpoint command.
See Drafts and checkpoints for the complete explanation and step-by-step instructions.