Org-Audit-Tool

1What it is

When QVCCS takes on a new managed-services client, engineers inherit an organisation they did not build. Years of projects leave behind numbers that ring nowhere and flows that nothing routes to. There are queues with no one in them, integrations quietly in error and users who left long ago. The Org-Audit-Tool gives engineers a clinical assessment on day one: what is there, what works, what is broken and what to do first.

• A full inventory with a diagnosis. Every object is read and given a state and a one-line reason, such as “Reached from call route Main Line; ran 4,812 times in the last 90 days” or “Points at flow Old IVR, which is not published”.
• Findings ranked by impact. Each finding has a severity, the kind of work it needs, the evidence, the objects affected and a recommended fix.
• Vital signs. Seven areas each get a score out of 100 and a grade from A to E. An area whose sources could not all be read is marked incomplete, and one where less than half could be read is not graded at all. The overall health is the mean of the graded areas, marked provisional when anything could not be read.
• A treatment plan. QVCCS AI groups the findings into 3–8 workstreams, most urgent first. Each workstream has an owner and steps. Every critical and high finding is guaranteed a place in the plan.
• Ask QVCCS AI. Engineers can ask plain-English questions about the scan. Answers cite the objects and findings they rely on.
• Coverage. Anything the scan could not read is reported, with the permission it needs. An audit that left areas out without saying so would look like a clean bill of health, so anything that depends on a source that was not read is shown as unknown, never guessed.

2Quick start

1. Get an OAuth client in the client's organisation. Use the Client Credentials grant and a role with view permissions (see §12). A role with only view permissions is the safest choice.
2. Sign in. Choose the organisation's region and enter the client ID and secret.
3. Choose a traffic window. For a first assessment, choose Last 90 days so that seasonal and month-end routes are not mistaken for unused ones.
4. Start the scan. The progress panel shows each source as it is read. Most organisations take a few minutes.
5. Read the Overview. It shows the vital signs, the written assessment and the most urgent findings.
6. Check Coverage. If anything says No permission, add that permission to the role, sign out and back in, then scan again.
7. Work the Treatment plan, and Download Excel to work offline or share with the client.

3Signing in

You sign in with a Genesys Cloud OAuth client that uses the Client Credentials grant, not with a personal login. That way the audit sees the whole organisation through one role you control, and you can revoke access by deleting the client.

• Region: the Genesys Cloud region the organisation lives in (for example, EU West (Ireland) or EU Central (Frankfurt)).
• Client ID and client secret: from Admin › Integrations › OAuth in the client's organisation.

The header shows the organisation's name and region once you are in. Use Sign out when you finish.

4Running a scan

The home page shows the organisation, a Run a full scan panel and a table of earlier scans. Each row in the table shows when the scan ran, its window, its status, its overall grade, its critical, high and medium finding counts, and how many objects it assessed.

The traffic window

Choose 7, 30, 60 or 90 days. The window decides live versus dormant. A flow, number, call route or queue that carried no conversations in the window is reported as dormant. A short window catches more “dormant” objects that are really just quiet (Christmas routes, quarter-end lines, disaster recovery paths). Use 90 days for a first assessment. Use 7 or 30 days for a quick check-up on an organisation you already know.

What happens during a scan

1. Reading. The scan reads 49 sources in turn, such as organisation, users, roles, trunks, flows and queues. The progress bar counts sources and the log shows each one as it finishes. The dependency map comes last and is the slowest: it asks Architect what each published flow uses, one flow at a time. After the flow list, any flow that a call route, messaging address, web deployment or email route points at but that was not in the list is looked up on its own. This tells a deleted flow apart from one the OAuth client cannot see.
2. Snapshot. Everything read is saved, compressed, as the scan's snapshot. Later rule improvements can then be applied without reading the organisation again (§10).
3. Analysing. The rules engine turns the snapshot into the inventory, findings and scores. This takes seconds.
4. Writing. If QVCCS AI is available, it writes the assessment and treatment plan. This usually takes a minute or two. The findings are complete before it starts, so you can work while it writes.

Cancelling and deleting

Cancel scan stops a running scan. Nothing is analysed and the scan is marked cancelled. Signing out also stops a scan you started, because it ends the credentials the scan was using. A scan that could read nothing at all (for example, a role with no permissions) is marked failed rather than reported as a clean organisation. Only one scan per OAuth client can run at a time. Delete on a row of the scans table removes that scan's snapshot, inventory, findings, AI write-up and questions for good. Cancel a running scan before deleting it.

5The report

A finished scan opens on its report. The heading shows the organisation, when it was scanned, the window and the number of objects assessed. On the right are the overall health grade and Download Excel. Six tabs follow.

Overview

• Assessment, written by QVCCS AI. It has a one-sentence headline, a 120–220-word summary for the account lead and client, the biggest risks, and what is in good order. Rewrite asks for a fresh write-up.
• Vital signs: one card per area. Each card shows the grade and score, a bar of objects by state, and counts of critical, high, medium and low findings. If some of the area's sources could not be read, the grade is greyed and the card says Incomplete and lists what was not read. If less than half could be read, the card says Too little read to grade. Select a card to open the Findings tab filtered to that area.
• Most urgent: the six most serious critical and high findings, ranked by impact.

When part of the organisation could not be read, an amber note under the assessment says which areas are affected and links to the Coverage tab. The overall health at the top is then marked provisional.

Findings

Every finding, most serious first. Filter by area, severity and type of work (quick clean-up, repair, client decision). The filters are kept in the address, so you can bookmark or share a filtered view with a colleague who uses the same OAuth client. Select a finding to open it:

• Detail: what is wrong and what it means for customers.
• Recommended fix.
• Evidence: the numbers behind it, such as calls in the window, members or failure rate.
• Affected: every object involved (up to 300 listed here). The full list of each object's state is in the Inventory and the Excel area sheets. Select an object's name to find it in the Inventory.

A finding about one object, such as Queue “Sales” has members but none are joined, is listed on its own. A finding that applies to many objects of the same kind, such as 42 prompts no published flow uses, is listed once with all of them under it.

Treatment plan

The findings grouped by QVCCS AI into workstreams, numbered in order of urgency. Each workstream shows:

• Title, type of work and owner: QVCCS, the client, or both.
• Why it matters, and 2–5 concrete steps.
• Resolves: the findings it covers, with their severity.

Any critical or high finding the model leaves out is added to a final workstream, Other urgent repairs. Nothing serious can drop out of the plan. Rewrite the plan asks QVCCS AI to group the findings again.

Inventory

Every object the scan assessed, grouped by area and type down the left with counts. Pick a type to list its objects with their state, the reason for it and up to six key facts. For a call route, for example, these are its numbers, its open-hours flow and its calls in the window. Filter by state with the chips, or search by name. Up to 2,000 rows are shown at once; narrow the list, or use the Excel for everything.

Coverage

What the scan could and could not read, area by area. Each source shows one of these results:

Ask QVCCS AI

Ask a question about the organisation in plain English, up to 1,000 characters. Some examples:

• Which numbers route to flows that are not published?
• Which queues get traffic but have no members?
• What should we fix first, and why?
• Which call routes have no closed-hours flow?

QVCCS AI answers from this scan only. It sees the scores, the findings and the inventory items whose names match words in your question. Naming a kind of object, such as call routes, flows, queues, numbers, prompts, data actions, email routes, messaging addresses or OAuth clients, adds every object of that kind (up to 150, problems first), so “Which queues have no members?” is answered from all the queues, not only the flagged ones. Under each answer are links to the inventory items it relied on. If the scan does not hold the answer, QVCCS AI says so and says what would. Questions and answers are kept with the scan, newest first, for everyone using the same OAuth client. After a re-analysis, earlier answers are marked as possibly out of date; ask again for a current one.

6States, severity, work & grades

Object states

Nothing is called unused without the evidence. “Dead” and “unused” are only given when every source that could refer to the object was read in full, including the dependency map of every published flow. If, say, call routes could not be read, an inbound call flow that nothing visible routes to is unknown, not dead. Workflows and other flows that can be started from outside the routing configuration (by the API, data actions or scripts) are never called dead.

The dependency map works out what reaches an object. That covers call routes, queues (in-queue flows), messaging and email routes, workflow triggers, and other flows that call it. It also works out what an object uses: prompts, data tables, schedule groups, data actions and other flows. A flow is dead only when nothing reaches it and it did not run in the window. This is why system and default flows that ran are never called dead.

Counting calls. Only voice conversations count as calls (an SMS to the same number does not). Calls to a number are counted once per conversation. A call that goes through the IVR to a queue and then to an agent is one call, not three.

Severity

Type of work

Quick clean-up

Safe tidying an engineer can do once it is confirmed, such as deleting unused prompts or checking flows back in.

Repair

Something is not working and needs fixing.

Client decision

Only the client can say, such as whether a dormant number should be kept or a leaver deactivated.

Impact, scores and grades

Findings are ranked by impact: the severity weight (critical 100, high 40, medium 15, low 5, info 1) scaled by how many objects are affected. The scale is logarithmic, so ten affected objects weigh about twice as much as one, not ten times as much.

Each area starts at 100. Each rule that fires in the area takes off points once, at its worst severity (critical 25, high 10, medium 4, low 1.5, info 0), scaled gently by how many objects it affects. Seventeen flows with the same fault cost more than one, but not seventeen times more. The score is never below 0.

An area is graded only when at least half its sources were read (or are modules the organisation does not have); otherwise it shows Too little read to grade. A graded area with any source not read in full is marked incomplete: its grade covers only what was read. The overall health is the mean score of the graded areas, on the same scale, and is marked provisional if any area was too little read or incomplete.

7What the audit checks

The audit is grouped into seven areas. The rule names below identify each check, so you can talk about a finding the same way across scans.

Telephony: numbers, call routes, trunks, Edges and phones

Architect: flows, prompts, schedules and data tables

Routing: queues, skills and wrap-up codes

Digital channels: messaging, SMS, email and web messaging

Integrations: integrations and data actions

People & access: users, roles, OAuth clients and sign-in

Platform & modules

Products, divisions, quality forms, WFM units, outbound campaigns, scripts and knowledge bases are listed in the Inventory, so engineers can see which modules the client uses.

8QVCCS AI

All AI work runs on QVCCS AI, the QVCCS sovereign AI service that also runs Think. A client's organisation data is confidential, so it stays in house. Nothing is sent to an outside AI provider. The model in use is named on every write-up and on the Ask tab.

What it does

• The assessment: headline, summary, biggest risks and strengths, from the area scores and the findings.
• The treatment plan: findings grouped into 3–8 workstreams, each with an owner, type of work and steps.
• Answers to engineers' questions, from the stored scan.

What it does not do

• It does not decide states, findings, severities or scores. The rules engine does that.
• It does not call Genesys. It sees only what the scan stored.
• It cannot add findings or objects of its own. Plan items may cite only findings that exist, and answers may link only to inventory items it was given. Anything else is dropped before it is shown.

Safeguards

• Names are data. Flow, queue and prompt names were written by the client's staff. They are passed to the model clearly marked as data. Text that looks like an instruction is ignored.
• Nothing serious is lost. Any critical or high finding the model leaves out of the plan is added back under Other urgent repairs.
• No invented failures. It may not add numbers together, or say that calls or customers failed unless a finding says so: calls that reached a route are traffic, not failures. It must name the routes, queues or addresses affected rather than generalise to the whole business.
• Honest about gaps. An area that was only partly read is never described as healthy, and nothing with a critical or high finding is listed as “in good order”.
• Plain UK English, referring to objects by name, with no invented numbers.

9Excel export

Download Excel on a finished scan saves org-audit-<organisation>-<date>.xlsx. It is for engineers working offline and for handing to the client.

Every sheet has a frozen, filterable header row.

10Re-analysing a scan

The audit rules are improved over time. When a scan was analysed with older rules, its report shows “The audit rules have been improved since this scan was analysed” with a Re-analyse button. Re-analysing runs the current rules over the scan's stored snapshot. It makes no new calls to Genesys, so the organisation is judged as it was on the scan date.

Re-analysing replaces the inventory, findings and scores, and clears the old AI write-up so a new one can be written to match. Questions already asked are kept, marked as possibly out of date. A scan cannot be re-analysed while QVCCS AI is still writing its summary.

11Day-one playbook

1. Before the scan. Ask the client for an OAuth client that has only view permissions (§12). Agree that QVCCS may read the configuration and traffic counts.
2. Scan with a 90-day window.
3. Check Coverage first. Get any missing permissions added, then re-scan until nothing important says No permission.
4. Triage the critical findings the same day. These are customers being failed now: broken call routes, trunks or Edges down, queues with no members, flows using deleted objects.
5. Take the Treatment plan to the kick-off. Use the owner column to split the work. Client decision items need the client's sign-off before anything is retired.
6. Do quick clean-ups only after confirming. Export a flow before you delete it, and agree retirements in writing. The Org-Audit-Tool never changes the organisation; engineers do, through the normal change process.
7. Re-scan after each round of work to show the grades improving. Keep the Excel from each scan as a record.

12Genesys endpoints & permissions

Give the OAuth client a role with the permissions below. Anything missing is reported on the Coverage tab with the exact permission it needs. The scan still finishes; it just has gaps.

¹ Genesys only lists message and email routing to clients holding the manage permission; there is no view-only equivalent. The app still only reads these lists. If the client will not grant manage, those two sources show No permission and the rest of the audit is unaffected.
² These two POSTs are queries: they send a time window and a grouping and get counts back. They change nothing. They are the only POSTs the app can make.

13Storage, privacy & security

• Scoped to the OAuth client. Every scan is stored against the region and client ID that ran it. Only sessions signed in with that same client can see it.
• What is stored per scan: the compressed snapshot of what was read, the inventory, the findings, the scores and coverage, the AI write-up, and questions with their answers.
• What is not stored: conversation recordings, transcripts or customer contact details. The scan reads configuration and counts of conversations, not the conversations themselves. User names, email addresses and last sign-in dates are read for the People findings.
• Credentials: the client secret is kept encrypted for the session only, so the app can renew its token. Unused sessions are removed after a period of inactivity, credentials included.
• AI: only QVCCS AI sees scan data (§8).

Stored data and deleting it

Stored data in the header shows how many rows of each kind are kept for the signed-in OAuth client, the size of its stored snapshots and the sessions currently signed in with it.

• Delete everything removes every scan, snapshot, finding, write-up and question for this client.
• Delete everything and sign out all sessions does the same, then ends every session using the client, including yours.

Deleting overwrites the stored data rather than just marking it free, so it cannot be recovered afterwards. You cannot delete while a scan is running; cancel it first. To remove a single scan, use Delete on its row on the home page.

14Technology

• Web application: a server-side Genesys Cloud client, rate-limited below the platform's per-client limit, with automatic retry when Genesys asks the app to slow down.
• Scan pipeline: sources, then coverage, then a compressed snapshot, then the rules engine (states, findings, scores), then QVCCS AI (write-up). Sources are read in parallel; the dependency map runs last because it needs the flow list.
• QVCCS AI: runs on QVCCS infrastructure. Replies are requested in a structured form and checked before use.
• Browser interface: the QVCCS fleet look, royal blue on white. State and severity colours are separate from the brand colour.
• Excel: generated on the server.

15Troubleshooting

Sign-in fails with “invalid client” or “unauthorised”.

Check the region first. A client ID from one region does not work in another. Then check that the OAuth client uses the Client Credentials grant and that the secret was copied in full.

Sign-in works but says the organisation cannot be read.

The role needs directory:organization:view. Add it, then sign in again.

Coverage shows “No permission” after I added the permission.

Permissions are set when the client signs in. Sign out and back in, then scan again. Also check that the role is granted on the right divisions; All divisions is simplest for an audit.

An area says “Too little read to grade”, or its grade is greyed and marked “Incomplete”.

Less than half (or not all) of that area's sources could be read, so a grade would describe the gaps rather than the area. The card lists what was not read; Coverage gives the permissions needed.

Objects say “cannot be called unused”.

Nothing that was read refers to them, but a source that could (call routes, email routes, part of the dependency map …) was not read, so the audit will not claim they are unused. Fix the gap and rescan.

Lots of flows, numbers or queues are “unknown”.

The traffic sources were not read, so the app cannot tell live from dormant. Add analytics:flowAggregate:view and analytics:conversationAggregate:view.

Most phones are “unknown”.

Genesys often does not return a status for phones, especially WebRTC phones. Those phones are shown as unknown rather than guessed. Check them in Genesys if they matter.

Call routes show as “unknown” with “flow could not be checked”.

The route's flow was not in the flow list this OAuth client could read. Usually it is in a division the client's role does not cover. Give the role view access to all divisions, sign out and in, and scan again.

Something seasonal is reported as dormant.

It had no traffic in the window. Scan with 90 days, or treat it as a client decision. Dormant findings are info level and never lower a grade.

The scan is slow on the dependency map.

It reads one request per published flow, and Genesys limits read speed. Large organisations take longer. If some flows cannot be read, the log says how many and the rest of the map is still used.

“A scan of this organisation is already running.”

Only one scan per OAuth client runs at a time. Open it with Watch the running scan, or cancel it.

No assessment or treatment plan appears.

QVCCS AI may still be writing; the Overview says so. If it says no summary yet, select Write it with QVCCS AI; if it says the write-up failed, it gives the reason and offers Try again. If QVCCS AI is unavailable, the findings and Excel are still complete.

A scan says it was stopped because I signed out.

Signing out ends the credentials a running scan uses. Sign in and run it again, and stay signed in until it finishes.

An answer says the scan does not contain the information.

Use the object's name as it appears in the organisation, or name the type (flows, queues, numbers …). Some questions, such as call recordings or agent performance, are outside what the audit reads.

A banner says the rules have been improved.

Select Re-analyse. The stored snapshot is re-assessed with no calls to Genesys (§10).

Everything returns “not authenticated” mid-session.

The session ended (after a period of inactivity, or from Delete everything and sign out). Sign in again; scans are kept.