The pictorial journey of one Genesys Cloud CX conversation through your Architect flows —
every prompt the caller actually heard, every key they pressed (and how long they hesitated), every
lookup that hit or missed, every branch, transfer and exit. Paste a conversation ID; get the story of
the call, as an exhaustive written analysis and as a colour-coded node-graph diagram.
Continuously integrated and updated. This is a published sample of the user guide. The App Suite changes frequently, so this page may not reflect the latest features, screens and behaviour. The current guide is available in the application through the QVCCS apps portal, included with every Managed Professional Services tier.
At a glance
flow-execution replay
one conversation at a time
analysis + diagram views
built-in demo
no database
strictly read-only
Security at a glance
Flow Journey
Read-only
Sign-in
OAuth client credentials you supply; secret held encrypted on the server and never sent to the browser
Stores
No conversation data stored; each journey is fetched fresh and held only in the page. Only your encrypted sign-in is kept
AI
No AI features are described in the user guide
Exports
Copy as plain text; raw step JSON in the inspector
When a customer says “your IVR hung up on me”, or an agent asks “why did this call land
in my queue?”, the answer is buried in Genesys Cloud’s Historical Flow Execution Data — a
raw, machine-oriented trace of everything the Architect runtime did on that conversation. Flow
Journey turns that trace into a story you can read and a picture you can walk:
One conversation, fully replayed. Every Architect flow the conversation passed through
(inbound call flow, in-queue flow, bot flow…) appears in execution order with the steps the
runtime actually took.
Two views of the same trace.Analysis (the default) is an exhaustive, numbered,
written step-by-step report — every switch case and which was taken, every data-table column
returned, every variable assigned, the full prompt wording, the caller’s keypress and think-time,
reusable-task boundaries — with one-click “Copy as text”. Diagram is a node-graph: flows as lanes, steps as pictorial cards, the traversal drawn as labelled,
tone-coloured edges.
Human details surfaced. Prompts show the wording actually played; menus show the DTMF
digit entered and how long the caller took to press it; data-table lookups show inputs, outputs
and hit-vs-miss; transfers name their target; every flow ends with its real exit reason.
What worked and what didn’t, at a glance. Steps, paths and whole flows are colour-coded:
green = worked, amber = friction (no-match, lookup miss, hesitation), red = error/failure,
blue = handoff to an agent.
Demo built in. A fully synthetic journey exercises both renderers with zero credentials.
Scope. Flow Journey deliberately does one conversation at a time. For
the aggregate picture — how thousands of callers move through a flow — use its sibling app
IVR Sankey.
2Quick start
Sign in — pick your Genesys region and enter an OAuth client-credentials
Client ID/Secret. The client needs the
architect:flowInstance:search and architect:flowInstance:view
permissions plus directory:organization:view (§8).
Find a conversation ID — from Genesys Performance → Interactions, or from any QVCCS tool
that lists conversations. It is a UUID; copy just the ID, not the interaction URL.
Paste it on the entry page and press Show journey. The app reconstructs the trace live (a few seconds).
Read the Analysis — the numbered report opens first. Switch to Diagram for the
graph; click any step for its raw detail; use Copy as text to paste the whole analysis
into a ticket or an email.
No credentials to hand? Press View demo — it works signed out. It is a canned journey served by the app itself: no Genesys traffic, no login.
Two prerequisites live in Genesys, not in this app: flow-execution capture is
opt-in per flow (“capture execution data” in Architect), and traces are retained for roughly
10 days. A conversation older than that, or routed only through non-capturing flows, has
nothing to show — see §3.
3Flow execution data — the domain
What Genesys records
When “capture execution data” is enabled on an Architect flow, every execution of that flow writes
a flow instance: metadata (flow name/type/version, start/end time, error and warning reasons)
plus a downloadable trace whose core is data.flow.execution[] — an ordered list of
single-key step objects (startedFlow, actionPlayAudio,
menuMenu, actionDataTableLookup, actionSwitch,
actionCallTask, actionTransferToAcd, endedFlow, …). One
conversation produces one instance per flow it entered, so a call that hits the main IVR and then an
in-queue flow yields two instances.
Opt-in per flow. Capture is a per-flow Architect setting, and only calls made
after it was enabled produce traces. A journey can therefore be partial: captured flows
render in full; non-captured flows simply don’t exist in the data.
~10-day retention. Genesys keeps flow execution data for about ten days. Older
conversations return nothing to download.
Truncation and secure flows. A trace can be flagged isTruncated (Genesys
cut it short — shown as an amber truncated badge) or isSecure (a secure flow —
shown as a secured badge; sensitive values arrive redacted).
Redaction. Where Genesys marks a value valueIsRedacted (secure input,
redacted DTMF), Flow Journey shows «redacted» / a masked dot — it never sees the
cleartext either.
Everything comes from the trace — nothing is faked
A design rule shared across the QVCCS flow tools: what you see is what the runtime recorded on
that call, never a reconstruction from today’s flow configuration. Prompt wording is the text the
TTS/audio engine was handed on that call (including «redacted»,
«null prompt» and «Nms silence» placeholders and a
[barge-in] marker where barge-in was enabled); branch labels are the
outputPathId the runtime actually took; keypresses are the recorded DTMF turn. If a flow
wasn’t capturing, Flow Journey shows nothing for it rather than guessing from static flow config.
Step taxonomy — family-aware, not enumerated
Architect has roughly 150 action types, and traces also carry lifecycle
(started*/ended*), menu and event-handler entries. Flow Journey classifies
by family and prefix (a shared step catalogue), so any action*,
event*, menu*, started*, ended* or
turn kind gets a category, icon, readable title (derived from the kind, with the flow
author’s action label appended when it adds information) and rich detail extraction — coverage does
not depend on the app having seen that action before. Only a key outside those families is
“genuinely alien”: it still renders with its full raw detail, tagged unmodelled, and the page
shows an “Unrecognised step kinds” notice listing the keys.
4How a journey is built
The four-step fetch
The app assembles a live journey against the Architect flow-instances API:
Query — POST /api/v2/flows/instances/query?pageSize=200 with
ConversationId eq <id> finds every flow instance the conversation produced.
No instances → the app reports that there is no trace.
Job — POST /api/v2/flows/instances/jobs?expand=dataActions with the first
50 instance ids starts a job that prepares presigned download URIs.
Poll — the job is polled up to 30 × 800 ms (~24 s) until
Success. If it doesn’t finish (or fails), the metadata alone is returned so the UI can at least show which flows the call touched.
Download — each instance’s ordered step trace is fetched from its presigned download URI (no Genesys token or API quota needed), a few at a time. A failed download is recorded for that instance without failing the whole call.
The result is one journey — exactly the shape the demo reproduces. Nothing is cached or stored:
every lookup is a fresh fetch, and a reload re-runs the whole pipeline.
In your browser — normalisation and analysis
The browser does the rest, in two parallel passes over the same envelope:
Instances are sorted by start time; the journey’s identity — ANI, DNIS, language, remote
name — is read from the first instance with data (the startedFlow variables
Call.Ani, Call.CalledAddress, Call.Language,
Call.RemoteName; tel:/sip: schemes stripped).
Steps are walked in order, unwrapping each single-key entry. Structural span markers
(startedTask/endedTask/menuTask) aren’t rendered as steps:
the Analysis view folds them into named task groups; the Diagram uses them for grouping only.
actionCallTask (reusable tasks) recurse into their own nested step lists.
Caller input — each menu’s DTMF turn yields the digit pressed and the think-time
(prompt-finished timestamp → keypress timestamp). Re-prompts append turns; the last turn — the
one that finally got an answer — wins.
Timing — every step carries its offset from flow start (+12.4s); a step’s
duration is the delta to its next sibling.
Path taken — the label on each connector is derived per kind: pressed 4 →
Track my order for menus, Found/Not found for data-table
lookups, the matched case (or Default) for switches and decisions,
→ Queue name for transfers, the outcome name/value for flow outcomes.
Status is rolled per step → flow → journey using the heuristics in §6.
5The user interface
Sign-in & entry
Sign-in: region picker (14 Genesys regions),
Client ID and Client Secret of a client-credentials OAuth grant. The token exchange happens on the server — the browser never sees a Genesys token — and the app immediately resolves your org name
via organizations/me, shown in the header thereafter. Failures are specific: bad credentials/region show “Invalid Client ID or Client Secret for this region”; missing permissions show the exact missing scope. Sessions end after a period of inactivity.
Entry page: a single Conversation ID field — validated as a UUID
before any request — with Show journey and View demo, plus a reminder of the retention
and capture caveats. The header offers Guide (this document, new tab) and Sign out
everywhere; the signed-out demo shows Sign in instead.
Journey header & summary
The journey page is titled ANI → DNIS (falling back to “Flow journey”), with the
conversation ID beneath and a ← New lookup link back to the entry page. A six-stat summary
strip covers: Conversation (the UUID) · From → To · Language ·
Flows traversed · Total duration (first flow start → last flow end) · Outcome
(a tone badge — see §6 — plus truncated, secured and demo badges when they
apply). To its right sits the Analysis | Diagram view toggle (Analysis is the default).
Two contextual notices can appear here: “Execution detail still preparing” (metadata only, reload shortly) and “Unrecognised step
kinds” (genuinely alien keys, listed).
Analysis view — the written report
An exhaustive, numbered, plain-language account of the call, one section per flow
(“Flow 1 of 2 — Main Contact Centre IVR · inbound · v3.0” with duration, exit reason and
error/warning/truncated/secured/status badges). Every executed step is a numbered entry with a
status-coloured left bar, its offset from flow start and how long it lasted. Unlike the diagram, the
analysis preserves task grouping: reusable tasks and named tasks nest with dotted numbering
(3, 3.1, 3.2…), so task boundaries and names are explicit. Per step it surfaces everything:
Prompts — the full spoken text, quoted, with [barge-in] markers.
Menus — prompt played, Caller pressed, Time to respond, Routed to,
menu variables.
Switches / decisions — the complete option list with the taken branch ticked
(✓ … ← taken) and the default row, plus the evaluation style.
Events and anything unmodelled — family-aware fallback extractors surface error
type/message/code, language changes, targets, inputs, assignments, returned values and the path
taken for any kind, so nothing renders empty.
Copy as text exports the entire report as indented plain text with the same numbering and
status tags — made for pasting into tickets, chats and post-mortems.
Diagram view — the pictorial journey
The same trace as a top-down node-graph with automatic layered layout. Each flow instance
is a titled container lane — type chip (inbound / in-queue / bot…), flow name, version,
error/warning/truncated/secured badges, duration and status — tinted by its status. Inside, each
executed step is a card: a category-coloured accent bar and icon, the raw kind
(menuMenu…), the offset from flow start, a bold title, a one-line detail (prompt text,
table ← lookup value, case count, target queue…), and — the headline — a keypad chip
with the caller’s DTMF digit and their think-time (“4 · 2.3s to answer”), amber when the pause
read as hesitation. Flow termini are coloured by how the flow ended. Reusable tasks render as dashed
sub-containers with their own − collapse / + expand control.
Edges tell the story: consecutive steps chain top-to-bottom, each connector labelled with
the path actually taken and coloured by its tone; flow-to-flow hops are dashed and labelled
(“→ in-queue flow”). Hiding nodes never breaks the spine — edges re-chain across whatever is
visible.
Toolbar (top-left):
Fit — re-frame the graph: width-fitted at a readable zoom, anchored to the top (a call
is tall and narrow — you scroll down to follow it).
Decisions & input only — show only the salient spine: prompts, menus, decisions,
switches, lookups, sub-flow calls, transfers, outcomes, events and termini.
Collapse utility (N) — hide housekeeping steps (update/set-participant-data, screen-pop
and similar; they render dimmed even when visible).
Collapse / Expand tasks — fold every reusable-task container at once.
Plus a pannable/zoomable minimap (nodes coloured by status), zoom controls, and a legend
under the header decoding the node category colours (control / prompt-comms / data / branch /
sub-flow / transfer / event / endpoint) and the path tones (worked / friction / error / handoff).
Step inspector
Click any step (in the Diagram) to open the right-hand inspector: title, kind badge (amber when
unmodelled), status and utility badges, then At (offset + time spent), Path taken,
Caller pressed (with think-time; redacted input masked), the one-line detail, all scalar
Fields, and the complete pretty-printed Raw step JSON — the ground truth, one click
away.
6Status model — what worked and what didn’t
Four tones run through both views — green/OK, amber/Warning, red/Error,
blue/Handoff — assigned per step, rolled up per flow, then summarised for the journey:
Status model — what worked and what didn’t
Tone
Assigned when
Error
An event…Error/Failure/Exception handler fired · a flow
outcome was set to FAILURE · the step took an __ERROR__/__FAILURE__
path or carries an error/errorType field · the flow exited with reason
ERROR · a Disconnect ended a flow that never set a SUCCESS outcome
(the caller was dropped).
Warning
A menu registered no-match · the caller took longer than
15 s to answer a menu (hesitation) · a data-table lookup came back
Not found · hold music ran past 60 s · timeout / no-input / rejected /
invalid / hangup / abandon events · a truncated trace or an instance whose detail couldn’t be
downloaded.
Handoff
Any transfer step (actionTransferToAcd,
transfer-to-user/number/group/flow…) and a flow exit of TRANSFER — the IVR did its
job and handed the caller on.
OK
Everything else — including a Disconnect in a flow that did set a
SUCCESS outcome (a completed self-service call is a good hang-up).
The SUCCESS flow-outcome signal is what disambiguates the two meanings of a hang-up —
set flow outcomes in Architect and Flow Journey can tell “completed in self-service” from “gave up”.
Journey outcome (the summary badge): Error in flow if any flow errored; otherwise by
the last flow’s exit — Transferred to agent (TRANSFER), Completed in IVR (DISCONNECT
with a SUCCESS outcome), Caller disconnected (DISCONNECT without), In progress (no exit
recorded yet), else the exit reason verbatim.
7Demo mode
View demo serves a canned journey — rendered with a demo badge — through exactly the same client pipeline as a live call:
a realistic multi-flow journey (“Main Contact Centre IVR”, inbound, then “Default In-Queue Flow”)
with menus, keypresses, a data-table lookup, a reusable task and an ACD transfer. It needs
no login and no Genesys credentials — it is reachable signed out, which makes it the reference for “is the renderer healthy?” and for showing the app to someone
without an OAuth client. All identifiers are fictional; phone numbers use Ofcom drama-reserved ranges
(07700 900xxx / 01632 960xxx).
8Genesys endpoints & permissions
The complete set of Genesys touchpoints — there are no others:
Genesys endpoints & permissions
Endpoint
Used for
POST
login.<region>/oauth/token
Client-credentials sign-in (token refreshed automatically, 60 s before expiry)
GET
/api/v2/organizations/me
Org identity at sign-in (name shown in the header)
POST
/api/v2/flows/instances/query?pageSize=200
Find the flow instances for one conversation (ConversationId eq)
POST
/api/v2/flows/instances/jobs?expand=dataActions
Start the job that prepares presigned download URIs (first 50 instances)
GET
/api/v2/flows/instances/jobs/{jobId}
Poll the job until Success (≤ ~24 s)
GET
presigned downloadUri
Download each instance’s step trace (no bearer token, no Genesys quota)
OAuth client permissions: the architect (or architect:readonly)
scope with architect:flowInstance:search and architect:flowInstance:view,
plus directory:organization:view — the org lookup runs during login, so without it
sign-in itself fails with a 403 naming that scope. All 403s carry the exact missing-permission hint
in the UI.
Read-only posture: the app only reads; the only two POSTs it may send are the instance query and the download-job prepare — both read-only by effect. Anything else is refused inside the app before it reaches the network. Flow Journey cannot modify
anything in your Genesys org.
Politeness: all Genesys calls are rate-limited per session. A 401 triggers one token refresh + retry; a 429 honours Retry-After and backs off before retrying.
9Storage, privacy & security
No database, no trace retention. Flow Journey stores no conversation data at all. Every journey is fetched fresh from Genesys per request, sent to the browser, and exists only in that page’s memory. Close the tab and it is gone.
Sign-in kept securely. The only thing kept on the server is your sign-in: an encrypted copy of your credentials and Genesys token, so a service restart doesn’t sign you out.
Secrets encrypted at rest. The Client Secret is held encrypted on the server and decrypted only to obtain a fresh token. Plaintext secrets are never written or logged.
Tokens stay on the server. Credentials are held on the server and never sent to the browser; the Genesys bearer token never leaves the server. Sessions end after a period of inactivity.
Read-only by construction — the read-only Genesys client (§8) means the app cannot write to Genesys even if asked to.
Redaction respected. Values Genesys marks redacted (secure flows, secure input) render as «redacted» — the app never receives the cleartext.
Placement, not masking. Traces do contain caller phone numbers, keypresses and variable values — that is the point of the tool. The mitigations are restricted access, a separate sign-in per app, and no persistence of conversation data.
10Technology
Web application — a server-side, read-only Genesys Cloud client with rate limiting and clear missing-permission messages (§8).
Browser interface — the written analysis and the node-graph journey canvas, laid out automatically in your browser.
No conversation storage — no database and no cache: every journey is fetched fresh from Genesys per request and normalised, analysed and rendered entirely in the browser (§9).
11Troubleshooting
“Invalid Client ID or Client Secret for this region.”
Wrong credentials, a non-client-credentials OAuth client, or the wrong region — each region has
its own login host, so a valid client in the wrong region still fails.
403 with a scope hint — at login.
The org lookup needs directory:organization:view. Add it to the OAuth client’s
role in Genesys Admin, then retry.
403 with a scope hint — when loading a journey.
The client lacks architect/architect:readonly with
architect:flowInstance:search / :view. Fix the client’s role, then sign
out and back in — token permissions are minted at sign-in.
“That does not look like a conversation ID.”
The input must be the conversation UUID, not an interaction URL. Copy just the ID.
“No flow execution trace for this conversation”.
The three causes: capture (“capture execution data”) isn’t enabled on the flows the call
traversed — it’s opt-in per flow, and only calls after enabling produce traces; the
conversation is older than the ~10-day retention; or the call never reached Architect at all.
“Execution detail still preparing”.
Genesys’ download-preparation job didn’t reach Success within ~24 s of
polling. You still see which flows the call passed through (metadata stubs), just not the steps.
Almost always transient — reload in a minute.
A flow shows “No trace / Couldn’t download this instance”.
That one instance’s download failed (expired URI or upstream hiccup). Reload —
the whole pipeline re-runs with fresh URIs.
An “Unrecognised step kinds” notice appears.
The trace contains keys outside every known family (action* / event* /
menu* / started* / ended* / turn). They still
render with their raw detail, badged unmodelled. Worth reporting so the catalogue can name
them properly.
The journey looks incomplete on a huge call.
The query returns up to 200 instances and the first 50 are downloaded. Also remember
that non-capturing flows (bot/in-queue flows without the setting) never appear as detailed
containers.
Everything 401s mid-session.
The session ended after a period of inactivity. Sign in again — nothing else is lost, since no conversation data is stored.
“Genesys rate limit hit despite throttling.”
Another consumer is sharing the same OAuth client’s quota. The app already paces itself and retries 429s honouring Retry-After; wait a moment, or give
Flow Journey its own OAuth client.
Is the diagram or the analysis “more true”?
Neither — both are pure renderings of the same downloaded trace. The analysis shows more raw
detail per step; the inspector’s Raw step JSON is the untouched source for any step.
QVCCS Flow Journey — the per-call flow-execution journey viewer for Genesys Cloud CX. Strictly read-only against the Genesys APIs; no database, no trace retention.
Continuously integrated and updated. This is a published sample of the user guide. The App Suite changes frequently, so this page may not reflect the latest features, screens and behaviour. The current guide is available in the application through the QVCCS apps portal, included with every Managed Professional Services tier.
Included at every tier
Use Flow Journey with QVCCS Managed Professional Services.
The App Suite comes with every Bronze, Silver, Gold and Diamond subscription, used by our engineers and your administrators alike – backed by the certified QVCCS bench.