Journey Studio & Runs

Scope

How to build a custom journey in the studio, test it with a dry run, and trace its runs from the tickets it touched.

This manual covers authoring custom journeys in the studio (journeys.manage) and working with journey runs. Enabling and tuning

Authoring a custom journey

Open Journeys → New journey (or Edit on a hand-authored journey). The studio is three panels: basics + trigger, conditions, and the ordered step list, with a live dry-run preview on the right.

• Conditions are picked, not typed. The field dropdown lists every field a condition may test (ticket fields plus the temporal age_hours / days_since_update family), served by the API — you cannot save a condition on a field Beacon doesn’t know. A misspelled field used to silently match every ticket; it is now a save-time error. Choose context.<key>… to test a trigger-supplied context value (chat slots, automation outcomes).

• Step parameters are validated against a contract. Every step type declares its required parameters, their types and ranges, and which of your tenant’s records they reference. Saving a step with a missing or misnamed required parameter, a group/schedule/category id that doesn’t exist, a fails with an error naming the step number and the bad key — it never saves green and then misfires in production.

• The step palette only offers steps that actually execute. Anything listed can run; there are no paper-only step types.

Changing a journey by describing the change (AI-assisted refine)

When you open a hand-authored journey for editing and AI-assisted authoring is available to you, the studio shows a “Refine with a description” panel. Type the change you want in plain language — “add a step that pages the on-call engineer after step 3”, “only run this for high-priority incidents” — and press Refine with AI. The panel is hidden when no AI is available to you at all, and it never appears for a template-derived journey (use Adjust parameters on the journey’s row for those) or when creating a new journey (use Describe it for that).

What happens next is the same review you get from any AI draft, plus a diff:

• The proposal lands in the editor as an unsaved draft. Every field is editable exactly as if you had typed it yourself.

• “What changed” shows the difference against the saved journey, grouped by section — basics, ticket-type scoping, conditions, steps (each added, removed or changed step named by its position), and the automation allowlists. If the model changed nothing, the panel says so rather than implying it did work.

• Revert puts the editor back exactly as it was, including any unsaved edits you had made by hand before refining. Dismissing the banner does the same. Nothing has been written to the journey at any point — refining is a proposal, not a save.

• Save is the ordinary Save button: the same validation, the same version bump, and the same in-flight-run warning as any other edit.

Two limits are deliberate:

• You cannot change what starts a journey this way. The trigger is the journey’s identity; changing it would make its conditions and steps incoherent. If the model tries anyway, Beacon tells it so and asks once more, and if it still insists, you see the disagreement as a validation error rather than a quietly altered journey. To change the trigger, create a new journey with Describe it.

• Your exception path is never rewritten. The “when does this hand off to a human?” declaration is your attestation, not the model’s — it stays exactly as you wrote it.

Your instruction is recorded. When you save a refined journey, the audit record for that change carries the instruction you typed and marks the edit’s origin as an AI refinement, alongside the usual before/after values. Anyone asking “why did this journey change?” gets the answer inline. The record also names which AI drafted it — Beacon’s built-in model or your own provider. Every refine attempt, including one that failed validation or was refused because an allowance was spent, is on the AI invocation log.

Which AI drafts your journeys, and what it costs you

Describe it and Refine work without you configuring anything. Two sources can run them, and Beacon picks without asking you:

• Your own AI provider, whenever you have one connected in Administration → AI. It always wins — connecting a key is the choice, so there is no picker to get wrong. These calls spend your own monthly token budget, exactly like every other AI feature.

• Beacon’s built-in AI, when you have not connected a provider. It is included in your plan at no extra cost, and it is on by default.

Every draft says which one produced it, on the banner above the editor: “Drafted by Beacon’s built-in AI (included in your plan) — review before saving” or “Drafted by your configured AI provider — review before saving”. Nothing is ever saved or activated on its own, whichever model drafted it.

The built-in AI has a monthly allowance. Each Propose or Refine is one assist (occasionally two, when Beacon asks the model to correct its own draft). Your allowance and how much of it you have used are shown on Administration → AI, under Beacon-managed AI — for example “143 of 200 assists used this month · resets Oct 1” — so you can see where you stand before you run out, not only when you do. If you do reach it, the studio tells you exactly that: how many you used, your limit, the date it resets, and that connecting your own provider removes the limit. The allowance resets on the 1st of each month, and calls made with your own key never count against it.

If Beacon’s shared AI service is busy, the studio says so plainly and, when it can, how long to wait — rather than reporting a generic failure. Your saved journeys are untouched; try again.

Turning the built-in AI off. An administrator with the AI settings permission can switch off “Use Beacon’s model for journey authoring” on the same page. It is a separate switch from the one governing chat classification — turning one off leaves the other exactly as it was. With it off and no provider of your own connected, the Describe-it and Refine panels are hidden and the endpoints say so honestly rather than failing silently.

Refining requires the same journeys.manage permission the studio already requires.

Dry-running before you activate

The Dry-run preview panel answers “would this run, and what would it do?” with no side effects — nothing is written, no provider is called, nobody is notified.

• Test against a real ticket. Enter a ticket id in the panel and the dry-run loads that ticket’s actual field values (your tenant only). Any sample fields you type override on top. Dry-running the seeded “New-incident enrichment” journey against an already-assigned incident, for example, honestly reports would not run with the reason.

• Trigger scope is checked too. A journey scoped to certain ticket types (the trigger’s “Applies to” list) previews “would not run” when the sample ticket’s type is outside that scope — with the reason naming the scoped types — instead of validating a journey that would never fire on that ticket.

• Errors appear next to the offending step. A step whose parameters break the contract, or whose referenced group/endpoint doesn’t resolve, is flagged inline with the exact errors, and the verdict is downgraded to “would not run” with a reason — a dry-run with red in it is telling you the journey is broken, not that the sample didn’t match.

Running a manual journey on a ticket

A journey whose trigger is manual never fires on its own — it exists to be dispatched deliberately. On such a journey’s row, Run on a ticket… asks for a ticket id and fires the journey once against it (requires journeys.manage; the dispatch is audited as journey.manual_run). The run executes immediately and the step trace opens so you can watch what it did. The journey’s conditions still apply: a non-matching ticket produces a completed no-op run, never a bypass. Event-triggered journeys refuse manual dispatch — fire their event instead.

This is the second half of the dry-run story: preview with the dry-run, then confirm for real on one concrete ticket.

Editing a journey that has runs in flight

Runs execute a snapshot of the step list taken when the run started. If you edit a journey’s steps while runs are parked mid-flight (waiting on a timer, an approval, or a device job), those runs finish the exact sequence they started with — inserting a step before their position no longer makes them silently skip it, and shortening the list no longer makes them finish early.

When you save a step change to a journey with active runs, the studio shows a warning naming how many runs are still executing the previous version. That is information, not a block: decide whether to let them finish, or cancel them from the run inspector.

Every run shows which definition version it executes (v3) in the run inspector and on the ticket’s journey panel. Runs older than the snapshot feature are marked as carrying a best-effort reconstructed snapshot.

Steps that wait for delivery confirmation

Two step types hand work to a delivery ledger with its own retries, and the run waits for the ledger to confirm instead of claiming success the moment the work was queued:

delivery confirmation”) while the outbox delivers with retries and backoff. When the receiver accepts, the step completes and the timeline says “delivered … (confirmed)”. If every retry is exhausted (or the endpoint was deleted), the step fails, the timeline states the downstream action was not confirmed, and the run fails — any later step that would have told the requester the action happened never runs. Fix the endpoint (Manage → Integrations → Webhooks) and re-trigger the journey.

• Send notification — the in-app inbox copy lands immediately; if an email or chat copy is queued, the run waits until those lanes settle and the step then reports exactly which channels delivered. A failed email is

While a run is waiting on a delivery, the run inspector shows it waiting at that step with the step still pending. This is expected — it is the product refusing to say “done” before it knows.

Steps that reach nobody say so. A notification whose recipient cannot be resolved (or who has turned every channel off), an on-call assignment against an empty rota, an escalation with no applicable policy, and a chat reply with no bound conversation each write a “reached nobody” entry on the ticket timeline and an audit record — never only a silent green step.

Choosing a named approver

In a new Request approval step, choose the person from the directory and describe the decision needed. The person can be selected before their first Beacon sign-in; they sign in normally when deciding. A cleared selection prevents saving or previewing the step. If a saved person becomes inactive or cannot be loaded, the draft is retained and the screen offers retry or replacement.

Existing approval policies remain visible as preserved policies. Use Replace with a named approver only when you intend to replace their identity and stage configuration with one named person. The original policy is retained until that explicit choice. Requester and author exclusions and current delegation rules still govern who may decide.

Seeing journey activity from the ticket

The desk ticket view has an Automation panel listing every journey run on the ticket — status, outcome, version, and, for a failed run, the error and the step it failed on. A failed or abandoned run also appears loud on the ticket timeline (never collapsed into the “N automation steps” summary), so an agent picking up the ticket cannot miss that an automation gave up.

The AI step and its confidence threshold

An ai_step with Auto-apply enabled exposes a Minimum confidence field (0–1, default 0.75): the provider’s stated confidence must clear it or the result is recorded as advisory only. Two honesty rules apply:

• Unknown confidence never auto-applies. A provider response that omits its confidence is treated as unknown quality, not certainty; the refusal is recorded with its reason on the AI invocation log.

• Every auto-applied change is visible. When the AI step changes a ticket’s category, impact, urgency, or priority, the ticket timeline shows which fields moved, old → new, with the confidence and threshold — and a full compliance record lands in the audit log (ai.auto_applied) with provider, model, and before/after values. An agent whose ticket’s priority moved can always see why.

Understanding resolution and handoff counts

A journey receives resolution credit only for its own completed, audited resolution transition. Enrichment, notes, skipped actions, and closing a ticket that was already resolved do not earn that credit. A run that waits while another run or a person changes the ticket lifecycle does not inherit their result. The recorded resolution must remain uninterrupted by another actor or run until this run finishes; a later own close cannot hide an intervening cycle. A direct close with no recorded resolution is simply completed.

Handoff counts use actual completed escalation results or explicit refusal, rejected approval, and automation failure outcomes. An escalation with no policy or no further stage has not handed work off; inspect its timeline explanation. Historical finalized outcomes retain their recorded values. Older unfinished steps with missing attribution evidence do not gain credit from today’s status.

Recovering an interrupted Studio save

Studio preserves the draft while saving and prevents another save or dismissal until the request returns. Once the definition is acknowledged, an unsuccessful active-state change retains its exact workflow and version. Check and retry active state reads that workflow first and retries only the requested active state, with a server-enforced version precondition. If another author changed it, review the current version before proceeding; the editor does not activate that later version automatically.

For a missing creation response, Studio retains the exact draft and a unique actor- and tenant-bound key across reopening or reload. Check and recover creation reads its receipt. If no committed receipt is observed, it resends only that same immutable intent and key: a still-running request or committed winner cannot create a second workflow. The receipt describes the original created version. Recovery also reads the current workflow and refuses to activate a later author’s version. Deleted workflows and revoked access remain unavailable; the receipt does not restore authority or resurrect a workflow.

For a missing update response, Check and recover update reads the known workflow. It retries only against the original expected version or recognizes the exact intended content at the immediately next version. That recognition confirms current content, not which request applied it. A later or different version retains your draft and offers Review current workflow so you can choose which edits to keep. Old unkeyed pending creations cannot be safely replayed automatically; review them with your administrator instead of guessing from a matching name.

Preview results apply only to the displayed draft and sample. Changing either invalidates the previous evidence; a failed rerun replaces it with an inline error and retry action. Preview is simulation only and does not dispatch an action or prove an external outcome.

Select real preview input with Sample ticket, searching permitted records by number or title. Its actual values are used unless you explicitly enter scenario overrides. Synthetic defaults apply only when no real ticket is selected. Changing ticket access invalidates an outstanding or displayed preview.

Named notification recipients

Notification steps offer Requester, Assignee, or a named directory person. Named selection requires directory.view. Saved selections reload from the current tenant directory; loading, retryable failure, and inactive states preserve the binding. Execution rechecks the current person and tenant status and email, including changes committed since earlier reads.

Named notifications send only the authored message, without ticket details or links. Preview names the person and explains that scope; simulation does not prove delivery. Existing subject and contextual bindings remain compatible. Saved legacy subjects appear read-only until deliberately replaced. Named approver selection remains a separate incomplete authoring requirement.

When an acknowledged workflow has been deleted or its creation receipt reports terminal unavailability, Studio retains the authored request for download. Release completed save and prepare inactive draft explicitly releases that completed recovery guard and restores the authored fields as an inactive draft. It does not submit a new request or activate anything. Permission refusal and network failures retain the pending guard because they do not establish deletion. An existing new-workflow draft must be resolved before this action can replace it.

Named-recipient previews also require directory.view at the API boundary. Losing directory access invalidates displayed and outstanding preview results; the authored binding remains retained without revealing a directory name.

Open and return from a draft

New workflow opens the relevant workflow; editing a workflow opens the relevant workflow. Authoring is a full page: the workflow list is not rendered behind it. Direct links and reloads load the exact requested workflow, with distinct loading, unavailable, no-access and retryable-error states. Legacy the relevant workflow links and ?edit=<id|new> links retain the selected draft, list tab and other query context. Browser Back and Forward move between the list and editor; Close returns to the in-app list even from a fresh deep link. A successful save replaces the editor’s history entry so Back does not reopen the completed save.

A pending save after reload displays its original authored fields read-only. These are the pending intent, not a claim about current server state. Existing recovery actions and exact-request download remain available. Save draft persists an inactive definition version. Editing an active definition also makes the new version inactive; the prior immutable publication and every run already pinned to it remain historical evidence.

Publish and restore a reviewed version

For a saved custom workflow, run Preview against a matching permitted ticket or synthetic sample. Publish reviewed version remains unavailable while fields differ from the saved version, while preview is stale, or while the sample does not reach an executable outcome. Confirmation states the recovery plan and that simulation does not prove a provider result. The server then revalidates typed references and capabilities and reruns the same simulation under the locked current version before it atomically records an immutable publication and makes that version active. Provider verification is a separate evidence claim and is never inferred from preview.

Published versions lists those immutable snapshots and their evidence. Restore vN copies the selected snapshot into a new, inactive definition version. Restore never rewrites history or changes old runs, and it never starts work: review, preview, and publish the restored draft separately. Product templates retain their compact enable/disable control and record their vetted template version on first activation.

Deactivate a published custom workflow from its row to stop new admissions. Beacon retains published versions and all run evidence; a workflow with either cannot be deleted. Delete remains available only for an unused draft.

Run detail identifies the workflow goal and pinned version, ticket target, attempt count, evidence freshness, next owner, and per-step readback. For a waiting, failed, or quarantined run, Check current outcome performs a fresh authoritative read; it does not retry or replay side effects. Automatic retries and quarantine stay bounded by the runtime policy, and a part-finished run is never resumed manually from an uncertain step.

If a directly opened workflow was deleted while an edit was pending, its canonical unavailable response exposes only the signed-in author’s local draft recovery. The retained fields are not a current workflow definition. Export or explicitly recover the inactive draft; no edit or activation is sent to the deleted target. Permission and network errors do not establish deletion. Invalid local recovery data stays intact and blocks saving instead of crashing the page or releasing a potentially pending request.

When a pending edit conflicts with a newer workflow version, Review current workflow first preserves the exact pending request and an editable draft. The current version opens with Resume draft so you can compare and deliberately restore your original edits. This action does not replay the pending request. If local storage cannot preserve the draft, the recovery guard remains in place and the error stays visible; the original edit is not discarded to navigate away.