collabSupport/services/voiceDiag/README.md

/voicediag

Rules-engine style diagnostic for the store's Webex Calling per-user configuration. The orchestrator (voiceDiagService.js) walks a registry of check modules, gathers their CheckResult objects, and hands them to the renderer + adaptive-card layer in commands/voiceDiag.js.

Command

/voicediag <storeNum>                 default: hides OK checks, posts fixable cards
/voicediag <storeNum> detail          include OK checks + expand every details block
/voicediag <storeNum> --only dnd,callForwarding
/voicediag list-checks                enumerate every registered check + its scope

HTTP path: GET /voicediag?storeNum=<n>[&detailed=true][&only=dnd,callWaiting]. HTTP callers get the markdown snapshot only — remediation cards are chat-only.

Prerequisites

All checks call /v1/people/{personId}/features/{feature} (with a few Webex-namespace variants noted inline in each check module). The scopes required are:

• spark-admin:people_read — every read (all checks)
• spark-admin:people_write — remediations (disable DND, clear forwarding, enable call waiting, disable call intercept)

These are the same scopes /webexhost and /offboarduser already use, so no operator work is needed to enable /voicediag on an existing deployment. If the token ever loses those scopes, each check self-reports as skipped: scope missing — the run still completes, and the phone-online summary keeps working.

About the URL scheme

Early drafts of this feature documented /v1/telephony/config/people/{id}/callSettings/*. That path family returns 404 "no static resource" from the Webex API gateway — it is not a live surface. The correct admin path is /v1/people/{id}/features/{feature}, per Webex's User Call Settings docs. A couple of features use different feature-name segments than their check id — most notably intercept (not callIntercept); see each check module for the exact endpoint. The runner distinguishes routing-404s ("URL moved, update the check") from "not applicable" 404s ("this person isn't a calling user") using the no static resource marker in the response body.

Store voice standards

The store phone standard is enforced by the checks below. Every check descriptor exports a standards object so the desired state is legible from the check file without reading run(). Changes here are meant to be a two-step change: update standards, then teach run() to interpret it — the checks compare the live state against standards and emit the severity in the "when non-compliant" column.

Per-user Webex Calling standards

Check	Standard	Non-compliant severity	Auto-remediation
dnd	enabled: false	warn	disable_dnd
callForwarding	{always, busy, noAnswer}.enabled: false	error	clear_call_forwarding
callWaiting	enabled: true	warn	enable_call_waiting
callIntercept	enabled: false	error	disable_call_intercept
voicemail	enabled: true, all three send*Calls.enabled: false, mwiEnabled: true	error on send-to-VM, warn on MWI-off / disabled / off-org email	stop_sending_to_voicemail for the send-to-VM path only
hoteling	enabled: false	warn	disable_hoteling
executiveAssistant	type: 'UNASSIGNED'	warn	none — Control Hub cleanup
outgoingPermission	no high-impact call type BLOCKED (LOCAL, NATIONAL, TOLL_FREE, TOLL, INTERNATIONAL)	warn	none — location-scoped fix

callForwarding is intentionally at error severity: forwarding active on a store line silently drops customer calls, and it's the single most common voice ticket. Voicemail's error path is narrower — only the three send-* triggers upgrade to error, since that also silently swallows calls. MWI-off, off-org email forwarding, and voicemail-disabled all stay at warn.

Switchport / port-hygiene standards

These reuse the phone-status snapshot from /phonestatus — no extra Webex API calls — and cross-reference against the Meraki port config that already flows through services/enrichment/merakiEnrichment.js. Trunk uplinks are treated as a visibility boundary: the phone is behind a non-Meraki switch (typically a Cisco stack in a store) and per-port policy isn't ours to enforce, so downstream VLAN / PoE / admin-state checks defer to the operator.

Check	Standard	Non-compliant severity	Notes
portType	portType: 'access' on every wired phone / DECT base	warn	Trunk uplinks flagged so operator checks the downstream switch
portVlan	vlan === VOICE_STANDARD_PHONE_VLAN (default 102)	warn	Env-configurable — VLAN may move from data-side to a proper voice VLAN in the future
portPoe	poeEnabled: true	warn	Skipped for trunk-uplinked devices
portEnabled	portEnabled: true	error	Admin-disabled port → phone is dead

No auto-remediation on any port check — Meraki port-config PUTs are a separate scope of work; the operator handles fixes in the Meraki Dashboard.

Environment overrides

Both port-hygiene knobs live in .env:

Var	Default	Purpose
VOICE_STANDARD_PHONE_VLAN	102	Expected VLAN for a store phone. Set per-site if the fleet moves onto a proper voice VLAN.
VOICE_STANDARD_ENABLED	true	Global kill-switch for the port-hygiene bucket. false silences portType / portVlan / portPoe / portEnabled while Meraki cleanup is in progress. Feature-config checks always run.

Apply-all-N-fixes card

When two or more checks return fixable results, /voicediag posts one extra adaptive card at the bottom offering to apply the whole batch in a single click. The individual per-issue cards stay on-screen so operators can still pick and choose; the combined card is a shortcut for the common "everything looks right, do it all" case. The batch executes each fix in sequence (not parallel) so audit lines stay readable and per-person Webex API write throttling doesn't stack; failures accumulate into a final summary line rather than aborting the run.

Dispatcher-side, the combined card uses the same pendingVoiceFixes map and the same voicediag branch in index.js — the payload's combined: true flag + the confirm_voicediag_all / cancel_voicediag_all action ids are what pick the batch handler over the single-fix handler.

Adding a new check

1. Create services/voiceDiag/checks/<newCheck>.js and export a descriptor:

   // The standards block is *the* source of truth for the desired
   // state. Keep the run() comparison in sync — regression tests
   // in tests/voiceDiag.checks.test.js assert every check has one.
   export const MY_NEW_STANDARDS = Object.freeze({ enabled: false });
   
   export const myNewCheck = {
     id: 'myNew',
     label: 'My New Check',
     requires: ['personId'],          // subset of ['personId','phoneStatus','telephonyProfile']
     scope: 'spark-admin:people_read',
     standards: MY_NEW_STANDARDS,
     async run(ctx) {
       const data = await ctx.webex.request('GET', `people/${ctx.personId}/features/whatever`);
       if (!!data?.enabled === MY_NEW_STANDARDS.enabled) {
         return { status: 'ok', message: 'Compliant.', details: null, remediation: null };
       }
       return {
         status: 'warn',              // 'ok' | 'warn' | 'error' | 'skipped'
         message: 'Human sentence for the chat row.',
         details: { relevant: 'facts' },
         remediation: {               // optional
           action: 'fix_my_thing',    // globally unique remediation id
           title: 'Fix My Thing',
           summary: 'One-line description of what the fix will do.',
           payload: { personId: ctx.personId, personLabel: ctx.personLabel, storeNum: ctx.storeNum },
         },
       };
     },
     remediations: {                 // optional
       async fix_my_thing(bot, data, requester) {
         // do the PUT, audit, reply
       },
     },
   };
   

2. Register it in services/voiceDiag/checks/index.js at the position you want the renderer to output it.

3. Add a describe-level block to tests/voiceDiag.checks.test.js covering the enabled / disabled / 403 branches.

That's it — no changes to the runner, renderer, command handler, index.js dispatcher, or commands/registry.js. The single confirm_voicediag / cancel_voicediag action namespace routes through the shared dispatcher, which looks the remediation up in the central registry built at module load. Remediation id collisions throw at import so you'll notice immediately.

CheckResult shape

type Severity = 'ok' | 'warn' | 'error' | 'skipped';

type Remediation = {
  action: string;             // globally unique across all checks
  title: string;              // button label
  summary?: string;           // optional card body line
  payload: Record<string, unknown>;  // handed to remediations[action](bot, payload, requester)
};

type CheckResult = {
  id: string;                 // set from check.id automatically
  label: string;              // set from check.label automatically
  status: Severity;
  message: string;
  details?: object | null;    // shown under `detail` mode
  remediation?: Remediation | null;
};

Error handling

Never throw from run(). The runner wraps every check in a try/catch and converts:

• HTTP 401/403/404 → status: 'skipped' with a "missing scope" hint pointing at check.scope.
• Any other error → status: 'error' with the API message.

So if you can't reason about a specific 5xx, just let it bubble — the runner will surface it.