Flow Mapper

1What it is

Genesys Cloud's own Architect editor shows one flow at a time, hides the relationships between flows and the entities they reference, and offers no way to hand a customer a point-in-time "as-built" record. Flow Mapper fills those gaps:

• See a flow, whole. Every published flow renders as an interactive diagram — tasks, menus, decisions, loops, transfers — with the actual prompt wording (and playable audio), queue targets, data-action contracts and expressions inlined, not hidden behind Architect's click-to-open panels.
• Walk a call. The Walker steps through the flow node by node like a virtual call, choosing a branch at each junction, building a caller-facing transcript as it goes.
• Inventory the org. Dedicated pages for prompts, data tables (schema and rows), data actions (contracts), integrations and queues — plus twenty-odd further inventories (users, telephony, outbound, quality, WFM, knowledge, recording policies…) surfaced through the API and the as-built document.
• Audit the configuration. A four-tier audit sweeps every flow and data table for broken references, case mismatches, likely typos and cross-flow naming drift — the classic Task.IsBlocked vs Task.isBlocked problem — with closest-match suggestions and deep links to the offending node.
• Generate an as-built document. A .docx snapshot of the entire configuration with scope presets, PII redaction and optional embedded diagram screenshots, produced by a detached background job that survives tab reloads.

2Quick start

1. Sign in — pick one of the 14 Genesys Cloud regions, paste an OAuth client-credentials Client ID and Secret. The token exchange happens on the server; the browser never sees a Genesys token. Read-only :view permissions are all it needs — see §7.
2. Explore — you land on Flows. Filter by name or type, click a flow, pan and zoom the diagram, click any node to inspect its full configuration.
3. Audit — open Audit and press Run audit. Findings stream in live and deep-link back to the exact node or table cell.
4. Document — open As-Built, pick a scope, press Generate, download the .docx when the job completes.

The header always shows the connected org and region, a Guide button (this page) and Sign out. Sessions end after a period of inactivity.

3The app, page by page

Eight pages sit in the top navigation: Flows · Prompts · Data Tables · Data Actions · Integrations · Queues · Audit · As-Built. Everything below the header is org data.

Flows & flow detail

Flows lists every Architect flow the OAuth client can see, across all 17 REST-listable flow types (voice, chat, email, message, bot, digital bot, workflow, common module, survey, voicemail…). Stat tiles roll the counts up into voice / digital / bots & workflows. Controls: a search box (name contains), an exclude box (comma-separated terms — handy for hiding staging, test flows) and a type dropdown. Columns show division, the published commitVersion and the date that version was published.

Clicking a flow opens flow detail: header badges for version and default language, a raw JSON ↓ button (downloads the exact Architect configuration for diffing/archiving), stat tiles for nodes / edges / variables / references, the diagram itself, a colour legend, and three collapsible tables — Variables (scope, type, initial value), References (every external entity the flow touches) and Edges. If the parser meets an action type it doesn't model yet, an amber banner lists the unknown kinds rather than failing the render.

Diagram & inspector

• Layout — containers (tasks, menus, states) stack vertically in call order; within each container actions are ranked into layers, and the flow's happy path is pinned to a straight centre column so the primary story reads top-to-bottom with error branches hanging off the sides. Cross-container edges route through gutters, and edge crossings render as little bridge hops so lines never read as merged.
• Toolbar — Go to start re-centres on the entry node; Show returns (n) toggles the dashed amber return paths from task ends back to their callers; Happy path dims everything except the success route from start to exit.
• Nodes — colour-coded by kind (control flow, communication, ACD transfer, external call, data, branching, endpoint); multi-output actions show port chips (Success / Failure / Timeout / case labels) so you can see every branch at a glance. Unresolvable queue names are flagged in red on the node — a typo finding you can see before running the audit.
• Inspector — click a node and the side panel shows its full configuration: prompt wording per language, pretty-printed expressions, data-action input/output contracts, queue records (members, division, wrap-up codes), plus every incoming/outgoing edge as a clickable jump. Jumps and calls have a Go to target button; clicking an edge highlights exactly where that one output goes. Deep links (used by the audit) pan to and flash the node on load.

The Walker

Started from the inspector, the Walker replaces it with step-through controls: it follows the flow from the entry node, and at every junction offers the outgoing branches as buttons (Yes/No, case values, Success/Failure, menu choices…). As it lands on communicate nodes it appends to a transcript — the TTS text or prompt content the caller would hear, with inline audio players for prompts that have recorded media. Synthetic task-ends offer return to caller branches, so reusable-task round trips read naturally. The canvas stays fully interactive while walking, and Restart takes you back to the start. Use it to narrate a call path in design reviews without touching Architect.

Inventory pages

• Prompts — every user prompt, master-detail: per-language resources with TTS text and playable audio. (System prompts are served by the API and resolved inside diagrams, but don't have their own listing page.)
• Data Tables — master-detail: schema (column, type, key, required, default) plus the actual rows with an any-column search and column sorting.
• Data Actions — master-detail: category, owning integration, and the full input / output-success / output-failure contracts.
• Integrations — type and reported state per integration, plus the data actions each one provides.
• Queues — searchable list (name, description, division) with member counts; the detail view adds skill evaluation method, calling-party settings and wrap-up codes.

Audit

Press Run audit and the org-wide sweep streams live: a progress pane with a phase label and scrolling log on the left, findings grouped as they arrive on the right. Stat tiles count high / medium severities; findings can be filtered by severity and free text, and every finding deep-links to the offending flow node or table. Cancel (or leaving the page) aborts the engine at its next checkpoint. Download CSV exports the findings list. See §5 for what the tiers check.

As-Built

Configure and run a document generation job: scope (executive / standard / full), redaction toggle, a self-documenting section picker (ordered the way the document is), a data-table row cap (hidden at full scope, which always includes all rows) and Include diagrams. Progress shows a phase-labelled bar; the browser tab remembers the job, so a mid-generation page reload re-attaches to the same job instead of losing it. When done, Download fetches the .docx. See §6.

4How a diagram is made

Diagrams are not produced by the Architect Scripting SDK. The app fetches the flow's raw configuration JSON directly over REST and parses it itself:

1. Fetch — GET /api/v2/flows/{id} finds the version to read (published, falling back to checked-in then saved for never-published flows), then GET /api/v2/flows/{id}/versions/{versionId}?expand=configuration returns the configuration inline or via a configurationUri the app follows — still authenticated, still GET.
2. Parse — the configuration is walked into a normalized flow AST: lookup tables from uiMetaData, a start node, task/menu containers with their action chains, then edge wiring from nextAction and paths[], jump edges for call-task/transfer/menu-choice targets, loop back-edges, synthetic end nodes at every chain terminus (matching Architect's implicit fall-through), dashed return edges from task ends back to callers, and finally variable + manifest extraction (the manifest catches references a per-action walk would miss).
3. Enrich — two passes run against the org inventory: prompts (Prompt.X / SystemPrompt.X tokens in communicate expressions are resolved to full per-language TTS text and audio URLs) and queues (transferToAcd targets resolve to real queue records; a name that matches nothing is stamped unresolved so the diagram paints it red; dynamic expressions like Flow.queueName are left alone, not flagged).
4. Render — the client lays the AST out with a custom layered ("Sugiyama-lite") algorithm that pins the happy path to a straight spine, precomputes every edge polyline so crossings become bridge hops, and renders the interactive diagram.

5The configuration audit

The audit loads the org inventory (queues, data tables with schema, data actions, user prompts, all flows), then parses every flow with the same JSON-first parser the diagrams use. Four tiers of checks:

• Dynamic references (Flow.x, Task.x, MakeQueue(…) expressions) are skipped — they can't be validated statically and are not typos.
• Every finding carries severity, category, the referencing flow/node or table/cell, the attempted name, the optional suggestion, and a deep link that opens the flow with the node focused and flashing.
• The live stream is kept alive automatically; closing the tab or pressing Cancel stops the engine at its next checkpoint.

6As-built documents

Scopes & sections

The section picker can add or remove any section from the scope's default. If the audit section is included (it is by default), a full audit run happens inside the generation and its findings become the document's configuration-health appendix.

Redaction

With redaction on (default, ignored at full scope): email addresses, international phone numbers and 9+-digit runs (account/employee IDs — first and last two digits kept) are masked in section bodies and data-table rows. UUIDs are deliberately not redacted — they're structural cross-references, not identifying.

The detached job & diagram capture

• Generation starts immediately and runs to completion in the background regardless of what the browser does. Progress advances through weighted phase bands (org → inventories → tables/actions/prompts → flow parsing → people/org → outbound/quality/WFM → audit → diagrams → document build) so the bar moves monotonically; "Parsing flows" interpolates per flow and is the long phase in big orgs.
• With Include diagrams on, the app renders each flow's own diagram page, waits for it to settle and captures just the diagram — with a 30 s per-flow budget. Any per-flow failure simply omits that image; it never fails the run.
• Jobs are owned by the creating session (nobody else can see them) and are kept ~30 minutes after finishing. The finished .docx is held briefly behind a one-shot download token with the same 30-minute TTL — a second click needs a regenerate.

7Genesys endpoints & permissions

Everything below is GET except the token exchange. Lists are paged internally (100 per page) until exhausted. 403s from Genesys come back to the UI with the exact missing permission named.

Practical permission set: the read-only role bundles (architect:readonly, routing:readonly, integrations:readonly, and their telephony / outbound / quality / WFM / directory equivalents) cover all of the above. Only the flow pages strictly need architect:flow:view; each inventory page degrades independently with a named-scope error if its permission is missing. Also confirm the OAuth client's role has division visibility over the flows you expect to see.

Rate limiting & resilience

• Genesys calls are rate-limited per session, well within Genesys’ limits.
• 429s are retried up to 4 attempts honouring Retry-After (exponential backoff otherwise); a 401 triggers exactly one token refresh-and-retry.
• Requests time out at 30 s; failures are shown with the Genesys status and, for a 403, the missing permission.

8Storage, privacy & security

• No database. Flow Mapper stores no organisation configuration data at rest — every page fetches live from Genesys through your session. The only thing kept is your sign-in (an encrypted credential and token), so a service restart doesn’t sign you out.
• Sessions — protected by a secure session cookie; sessions end after a period of inactivity.
• Credentials — the client secret is held encrypted on the server and decrypted only when a token is refreshed. The browser never receives a Genesys token or secret. Logout wipes your sign-in from the server.
• Read-only guard — the app refuses any non-GET Genesys request before it is sent (§1). There is no write path.
• One org per session — each browser session binds to exactly one org; use another browser/profile (or sign out) to switch. Sessions are fully isolated from each other.
• As-built output — generated .docx files are held only briefly behind a one-shot download link and are discarded on download or after 30 minutes. Mind that a full-scope document itself contains unredacted configuration — treat the file accordingly.

9Technology

• Web application — a rate-limited, read-only Genesys client; Word document assembly for as-built output; automatic diagram capture for the document. No database — every page reads live from Genesys.
• Browser interface — interactive diagrams, inspector and inventory pages.
• Layout engine — a custom layered ("Sugiyama-lite") algorithm ranks actions into layers per container, pins the flow's happy path to a straight centre spine and precomputes every edge polyline so crossings render as bridge hops.

10Troubleshooting

Login & permissions

"Invalid Client ID or Client Secret for this region."

Wrong credentials, the OAuth client isn't a client-credentials grant, or the wrong region — each region has its own login host, so a Frankfurt client won't authenticate in Virginia.

403 with a named permission.

The error banner names the missing permission (e.g. architect:flow:view). Add it to the OAuth client's role in Genesys Admin, save, then sign out and back in — token grants are minted at login. Also confirm the role's division visibility.

Signed out unexpectedly.

Sessions end after a period of inactivity. Sign in again — nothing else is lost, since Flow Mapper stores no organisation configuration data.

Diagrams & data

A flow won't render / parse error.

Check the flow has some version — published, checked-in or saved; a flow with none of the three has nothing to fetch. The loading banner is honest about big flows: 500+ actions can take 15–30 s to parse and lay out.

A queue chip is red ("TYPO?").

That's a finding, not a bug: the flow transfers to a queue name that doesn't resolve in the org (typo or deleted queue). The audit lists the same issue with a closest-match suggestion.

Amber "action types not yet modeled" banner.

The parser met an action kind it doesn't classify; those nodes render as unknown but the rest of the flow is intact — nothing is hidden, and the banner lists exactly which kinds were affected.

Slow first load on a big org / 429 messages.

Every list goes through the app's rate limiter; persistent 429s usually mean another tool shares the OAuth client's org-wide budget — retries with backoff are automatic, but a dedicated OAuth client for Flow Mapper is the fix.

Audit & as-built

Audit stream stops mid-run.

The live connection was dropped; rerun the audit. Closing the tab intentionally cancels the run.

As-built job "not found or expired".

Job records live ~30 min after completion and are owned by the session that started them — a different browser/session can't poll them. Regenerate. (A reload in the same browser re-attaches automatically via the stored job id.)

Download says the file is not found.

The download link is one-shot; a second click or a download manager's pre-fetch consumes it. Regenerate the document.

Diagrams missing from the .docx.

The app couldn't capture those flows within the 30 s per-flow budget — the run tolerates that and omits the images rather than failing. Regenerate to retry.

Generation "stuck" at Parsing flows.

That phase is a per-flow REST fetch + parse under the rate limit; hundreds of flows take several minutes. The percentage interpolates within the phase, so movement is slow but real.

FAQ

Can Flow Mapper change anything in Genesys?

No. The app rejects every non-GET Genesys request before it is sent; there is no write path.

Does it see draft edits?

Not for published flows — you always get the most recent published build. Only a flow that has never been published falls back to its checked-in or saved configuration. An in-progress editor state is never visible.

Where do my credentials go?

The secret is held encrypted on the server for your session only and never sent to the browser. Logout wipes it.