@webex/contact-center 3.13.0-next.1 → 3.13.0-next.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.repo-context.json +704 -0
- package/.sdd/manifest.json +1065 -339
- package/AGENTS.md +935 -60
- package/dist/webex.js +1 -1
- package/docs/adr/0001-spec-source-policy.md +97 -0
- package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
- package/docs/adr/0003-repo-standards-migration.md +104 -0
- package/docs/adr/index.md +35 -0
- package/docs/architecture.md +460 -0
- package/docs/getting-started.md +142 -0
- package/docs/index.md +53 -0
- package/docs/specs/README.md +98 -0
- package/package.json +10 -9
- package/schemas/repo-context.schema.json +796 -0
- package/src/docs/README.md +727 -0
- package/src/metrics/docs/README.md +710 -0
- package/src/services/agent/docs/README.md +673 -0
- package/src/services/config/docs/README.md +530 -0
- package/src/services/core/docs/README.md +993 -0
- package/src/services/docs/README.md +765 -0
- package/src/services/task/docs/README.md +1569 -0
- package/src/services/task/state-machine/docs/README.md +1388 -0
- package/src/utils/AGENTS.md +6 -4
- package/src/utils/docs/README.md +413 -0
- package/umd/contact-center.min.js +2 -2
- package/umd/contact-center.min.js.map +1 -1
- package/ai-docs/ARCHITECTURE.md +0 -168
- package/ai-docs/CONTRACTS.md +0 -64
- package/ai-docs/GETTING_STARTED.md +0 -168
- package/ai-docs/GLOSSARY.md +0 -43
- package/ai-docs/README.md +0 -138
- package/ai-docs/REVIEW_CHECKLIST.md +0 -41
- package/ai-docs/RULES.md +0 -444
- package/ai-docs/SECURITY.md +0 -52
- package/ai-docs/SERVICE_STATE.md +0 -52
- package/ai-docs/SPEC_INDEX.md +0 -65
- package/ai-docs/adr/0001-spec-source-policy.md +0 -55
- package/ai-docs/adr/README.md +0 -8
- package/ai-docs/adr/_adr-template.md +0 -31
- package/ai-docs/contact-center-spec.md +0 -388
- package/ai-docs/features/contact-owner-change-refactor.md +0 -78
- package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
- package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
- package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
- package/ai-docs/patterns/event-driven-patterns.md +0 -485
- package/ai-docs/patterns/testing-patterns.md +0 -480
- package/ai-docs/patterns/typescript-patterns.md +0 -365
- package/ai-docs/templates/README.md +0 -102
- package/ai-docs/templates/documentation/create-agents-md.md +0 -240
- package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
- package/ai-docs/templates/existing-service/bug-fix.md +0 -254
- package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
- package/ai-docs/templates/new-method/00-master.md +0 -80
- package/ai-docs/templates/new-method/01-requirements.md +0 -232
- package/ai-docs/templates/new-method/02-implementation.md +0 -295
- package/ai-docs/templates/new-method/03-tests.md +0 -201
- package/ai-docs/templates/new-method/04-validation.md +0 -141
- package/ai-docs/templates/new-service/00-master.md +0 -109
- package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
- package/ai-docs/templates/new-service/02-code-generation.md +0 -346
- package/ai-docs/templates/new-service/03-integration.md +0 -178
- package/ai-docs/templates/new-service/04-test-generation.md +0 -205
- package/ai-docs/templates/new-service/05-validation.md +0 -145
- package/src/metrics/ai-docs/AGENTS.md +0 -350
- package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
- package/src/metrics/ai-docs/metrics-spec.md +0 -971
- package/src/services/agent/ai-docs/AGENTS.md +0 -240
- package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
- package/src/services/agent/ai-docs/agent-spec.md +0 -505
- package/src/services/ai-docs/AGENTS.md +0 -386
- package/src/services/ai-docs/services-spec.md +0 -512
- package/src/services/config/ai-docs/AGENTS.md +0 -250
- package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
- package/src/services/config/ai-docs/config-spec.md +0 -669
- package/src/services/core/ai-docs/AGENTS.md +0 -381
- package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
- package/src/services/core/ai-docs/core-spec.md +0 -797
- package/src/services/task/ai-docs/AGENTS.md +0 -457
- package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
- package/src/services/task/ai-docs/task-spec.md +0 -1501
- package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
- package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
- package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
- package/src/utils/ai-docs/utils-spec.md +0 -391
|
@@ -0,0 +1,530 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: Module Spec
|
|
3
|
+
title: 'Config service specification'
|
|
4
|
+
description: Responsibilities, boundaries, design, invariants, and verification for the Contact Center config service (AgentConfigService, the AgentProfile aggregation, and the CC event-name constants).
|
|
5
|
+
tags: [module, specification]
|
|
6
|
+
---
|
|
7
|
+
<!-- sdd-generated-metadata
|
|
8
|
+
doc_kind: module-spec
|
|
9
|
+
generated_from: module-spec@0.3.0
|
|
10
|
+
generated_by: claude-code
|
|
11
|
+
approved_by: rarajes2@cisco.com
|
|
12
|
+
updated_at: 2026-11-17T03:03:58Z
|
|
13
|
+
validation_status: pass-with-warnings
|
|
14
|
+
-->
|
|
15
|
+
|
|
16
|
+
# Config service
|
|
17
|
+
|
|
18
|
+
This source-local document at `src/services/config/docs/README.md` owns the stable specification for
|
|
19
|
+
**the config service**: `AgentConfigService`, which fetches and aggregates agent configuration data
|
|
20
|
+
from multiple API endpoints to build the AgentProfile, the `parseAgentConfigs` mapper, the
|
|
21
|
+
`endPointMap` resource builders, and the configuration and event types in `types.ts`, including the
|
|
22
|
+
`CC_EVENTS` event-name constants. This is the authoritative documentation for the Config service
|
|
23
|
+
scope. See the [package agent instructions](../../../../AGENTS.md) for the orchestrator and
|
|
24
|
+
cross-scope rules. Ground every claim in package evidence and link to the
|
|
25
|
+
[package architecture](../../../../docs/architecture.md) instead of repeating broader facts; no service
|
|
26
|
+
specification exists because this package is a library. The parent module is the
|
|
27
|
+
[services specification](../../docs/README.md).
|
|
28
|
+
|
|
29
|
+
Related context: [documentation index](../../../../docs/index.md) ·
|
|
30
|
+
[package agent instructions](../../../../AGENTS.md)
|
|
31
|
+
|
|
32
|
+
## Metadata
|
|
33
|
+
|
|
34
|
+
| Field | Value |
|
|
35
|
+
| ----- | ----- |
|
|
36
|
+
| Owner | @webex/web-sdk |
|
|
37
|
+
| Source path | `src/services/config` |
|
|
38
|
+
| Resource kind | module |
|
|
39
|
+
| Status | Active |
|
|
40
|
+
| Last verified | 2026-11-16 at `0b8c34db7f` |
|
|
41
|
+
| Module id | `config` |
|
|
42
|
+
| Parent spec | [src/services](../../docs/README.md) |
|
|
43
|
+
| Doc kind | Module spec |
|
|
44
|
+
| Coverage score | Pending coverage assessment |
|
|
45
|
+
| Validation status | pass-with-warnings — assessed 2026-11-17; validator runtime 01a1e76f-2293-79a0-9f8f-f060038448dd; 0 Blocking, 0 Important, 4 Minor findings. |
|
|
46
|
+
|
|
47
|
+
## Applicability
|
|
48
|
+
|
|
49
|
+
| Condition ID | Status | Evidence or reason | Owned section |
|
|
50
|
+
| ------------ | ------ | ------------------ | ------------- |
|
|
51
|
+
| `module.has_tiers` | N/A | No tier policy exists in `package.json` or under src | Tier |
|
|
52
|
+
| `module.has_ui` | N/A | `src/services/config/index.ts` only returns promises; nothing renders | UI use-case flow |
|
|
53
|
+
| `module.crosses_service_boundaries` | Applicable | `src/services/config/index.ts` calls the Contact Center API gateway through `src/services/core/WebexRequest.ts` | Cross-boundary use-case flow |
|
|
54
|
+
| `module.holds_client_state` | N/A | `src/services/config/index.ts` keeps only the WebexRequest handle; the built profile is stored by `src/cc.ts` | Client state model |
|
|
55
|
+
| `module.enforces_domain_rules` | Applicable | All-or-nothing aggregation in `src/services/config/index.ts` and the wellness and aux-code rules in `src/services/config/Util.ts` | Business rules and invariants |
|
|
56
|
+
| `module.is_concurrent_async` | Applicable | `src/services/config/index.ts` starts requests in parallel and joins them with Promise.all | Concurrency and reactive flow |
|
|
57
|
+
| `module.owns_persistence` | N/A | Nothing in `src/services/config/index.ts` writes storage | Data, schema, and migration discipline |
|
|
58
|
+
| `module.stateful_transitions` | N/A | `src/services/config/index.ts` has no state machine | State machine |
|
|
59
|
+
| `module.exposes_wire_protocol` | Applicable | REST resource shapes in `src/services/config/constants.ts`; WebSocket event names in `src/services/config/types.ts` | Protocol and wire format |
|
|
60
|
+
| `module.ui_multi_screen` | N/A | No UI | UI flow |
|
|
61
|
+
| `module.large_data_model` | N/A | Manifest profile false; the response and profile types in `src/services/config/types.ts` are summarized under Public surface | Data model |
|
|
62
|
+
| `module.returns_caller_errors` | Applicable | Every method in `src/services/config/index.ts` logs and rethrows | Caller-visible failure modes |
|
|
63
|
+
| `module.module_specific_conventions` | Applicable | Event-constant and logging conventions in `src/services/config/types.ts` and `src/services/config/index.ts` | Module-specific rules |
|
|
64
|
+
| `module.published_package` | N/A | Manifest profile false; package exports are owned by `src/index.ts` and the package spec | Export stability |
|
|
65
|
+
| `module.embedded_in_host` | N/A | No host theme or mount API | Host integration and theming |
|
|
66
|
+
| `module.has_design_tradeoff` | Applicable | All-or-nothing Promise.all aggregation in `src/services/config/index.ts` | Key design trade-off |
|
|
67
|
+
| `module.has_submodules` | N/A | The module tree computed by scripts/module_tree.py lists no child of src/services/config (manifest has_submodules false) | Sub-modules |
|
|
68
|
+
|
|
69
|
+
## Evidence register
|
|
70
|
+
|
|
71
|
+
Every requirement cites stable source and test file paths. Code and tests are the behavioral referee;
|
|
72
|
+
missing or contradictory evidence blocks promotion.
|
|
73
|
+
|
|
74
|
+
| Evidence | What it establishes |
|
|
75
|
+
| -------- | ------------------- |
|
|
76
|
+
| `src/services/config/index.ts` | `AgentConfigService` and its twelve public methods; the staged `getAgentConfig` orchestration; the per-method log, status-check, and rethrow pattern; the operation groups that justify the `Profile aggregation`, `Pagination`, and `Wellness idle-code lookup` subsections under Data flow and sequence coverage |
|
|
77
|
+
| `src/services/config/Util.ts` | `parseAgentConfigs` and its helpers `getFilterAuxCodes`, `getFilteredDialplanEntries`, `getDefaultWrapUpCode`, `getMsftConfig`, `getWebexConfig`, `getDefaultAgentDN`; the wellness gate |
|
|
78
|
+
| `src/services/config/constants.ts` | `endPointMap`, `DEFAULT_PAGE` (0), `DEFAULT_PAGE_SIZE` (100), `DEFAULT_AUXCODE_ATTRIBUTES`, `WELLBEING_BREAK_IDLE_CODE`, `WELLNESS_BREAK_REMINDERS_ENABLED`, `COLLABORATION_ACCESS`, `METHODS` |
|
|
79
|
+
| `src/services/config/types.ts` | `CC_TASK_EVENTS` (66 keys), `CC_AGENT_EVENTS` (19 keys), `CC_EVENTS`, `VOICE_CONNECTION_EVENTS`, `Profile`, and the response types (catalog source of `contact-center-cc-events`) |
|
|
80
|
+
| `src/services/index.ts` | `Services` constructs one `AgentConfigService` as `services.config` |
|
|
81
|
+
| `src/cc.ts` | Consumers: `connectWebsocket` stores `getAgentConfig` as `this.agentConfig`; `getWellbeingBreakIdleCode` and `getOutdialAniEntries` wrap the service; `CC_EVENT_ALLOW_LIST` filters re-emitted WebSocket event names |
|
|
82
|
+
| `src/index.ts`, `src/webex.js` | Public re-export of `CC_EVENTS`, `CC_AGENT_EVENTS`, `CC_TASK_EVENTS`, `VOICE_CONNECTION_EVENTS`, `IDLE_CODE`, `WRAP_UP_CODE`, and the config types; `Webex.CC_AGENT_EVENTS` |
|
|
83
|
+
| `src/services/core/WebexRequest.ts` | The singleton HTTP wrapper over `webex.request` used by every method |
|
|
84
|
+
| `src/services/core/websocket/WebSocketManager.ts` | Resolves registration on the `CC_EVENTS.WELCOME` message |
|
|
85
|
+
| `src/services/WebCallingService.ts` | Emits `VOICE_CONNECTION_EVENTS.STATE_CHANGE` |
|
|
86
|
+
| `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts`, `src/services/UserPreference.ts` | Other consumers of `endPointMap` |
|
|
87
|
+
| `src/services/ApiAiAssistant.ts` | Consumes `AIFeatureFlags` through `setAIFeatureFlags` |
|
|
88
|
+
| `src/constants.ts` | `CONFIG_FILE_NAME` is `config-index`, the log `module` of every config method |
|
|
89
|
+
| `test/unit/spec/services/config/index.ts` | Unit cases for every request method, pagination, the wellness lookup, `getAgentConfig` staging and rejection, and `getOutdialAniEntries` |
|
|
90
|
+
| `test/unit/spec/services/config/Util.ts` | Unit cases for `parseAgentConfigs` field mapping, aux codes, dial plan, and the wellness gate |
|
|
91
|
+
| `test/unit/spec/cc.ts` | WebSocket allow-list cases: an unknown `data.type` is not emitted; a known one is emitted verbatim |
|
|
92
|
+
| `package.json` | TypeScript 5.4.5 and Jest 27.5.1 |
|
|
93
|
+
|
|
94
|
+
## Purpose and boundary
|
|
95
|
+
|
|
96
|
+
- Responsibility: Config is one of nine confirmed Contact Center SDK modules. Own retrieval and
|
|
97
|
+
aggregation of remote organization, agent, team, profile, auxiliary-code, dial-plan, and feature
|
|
98
|
+
configuration, and own the event-name constants of the `contact-center-cc-events` contract.
|
|
99
|
+
- In scope: `AgentConfigService` request methods and pagination, `parseAgentConfigs`, the
|
|
100
|
+
`endPointMap` resource builders, the system wellness idle-code lookup, the outdial ANI lookup, and the
|
|
101
|
+
types and event constants in `src/services/config/types.ts`.
|
|
102
|
+
- Out of scope: when the profile is fetched and how it is stored or used (`src/cc.ts`, see the
|
|
103
|
+
[package specification](../../../docs/README.md)); emitting events (ContactCenter, the
|
|
104
|
+
[agent service](../../agent/docs/README.md), and the [task service](../../task/docs/README.md));
|
|
105
|
+
HTTP transport (the [core service](../../core/docs/README.md)); queue, entry-point, address-book,
|
|
106
|
+
and user-preference requests that only borrow `endPointMap`.
|
|
107
|
+
- Consumers: `ContactCenter` in `src/cc.ts` through `services.config`; every module that imports the
|
|
108
|
+
event constants or types; applications through the re-exports in `src/index.ts`.
|
|
109
|
+
|
|
110
|
+
## Structure and key files
|
|
111
|
+
|
|
112
|
+
| Path | Responsibility |
|
|
113
|
+
| ---- | -------------- |
|
|
114
|
+
| `src/services/config/index.ts` | `AgentConfigService`: service implementation with all API methods |
|
|
115
|
+
| `src/services/config/types.ts` | Complete type definitions and event constants (`Profile`, response types, `CC_EVENTS`) |
|
|
116
|
+
| `src/services/config/Util.ts` | AgentProfile parsing utilities (`parseAgentConfigs`, `getFilterAuxCodes`, etc.) |
|
|
117
|
+
| `src/services/config/constants.ts` | API endpoints (`endPointMap`), default values, and method names |
|
|
118
|
+
| `src/services/config/docs/README.md` | This module specification |
|
|
119
|
+
| `test/unit/spec/services/config/index.ts` | Unit cases for `AgentConfigService` |
|
|
120
|
+
| `test/unit/spec/services/config/Util.ts` | Unit cases for `parseAgentConfigs` |
|
|
121
|
+
|
|
122
|
+
## Public surface
|
|
123
|
+
|
|
124
|
+
| Surface | Consumer | Compatibility commitment | Source |
|
|
125
|
+
| ------- | -------- | ------------------------ | ------ |
|
|
126
|
+
| `contact-center-cc-events`: `CC_EVENTS`, `CC_AGENT_EVENTS`, `CC_TASK_EVENTS`, `VOICE_CONNECTION_EVENTS`, and the `CC_EVENTS` value union type (exported as `ContactCenterEvents`) | Applications (re-exported by `src/index.ts`; `Webex.CC_AGENT_EVENTS` in `src/webex.js`), ContactCenter, agent, task, and core modules | Values equal the backend WebSocket `type` strings and are public event names; renaming or removing a value is a breaking change | `src/services/config/types.ts` |
|
|
127
|
+
| `contact-center-sdk` (owned by the package spec): `Profile` and the configuration response types (`OrgDesktopLoginResponse`, `UserDesktopLoginResponse`, `TeamList`, `AuxCode`, `Entity`, `DialPlan`, and the others listed below). Field rules: `aiFeature` CONFIG-R-002, `maskSensitiveData` and `MultimediaProfileResponse` CONFIG-R-004, `isWellnessBreakEnabled` CONFIG-R-006 | Applications through `src/index.ts` | Exported TypeScript types; renaming or removing a field breaks consumers | `src/services/config/types.ts`, `src/index.ts` |
|
|
128
|
+
| `contact-center-services` (owned by the services spec): `AgentConfigService` methods `getAgentConfig(orgId, agentId)` (CONFIG-R-001, CONFIG-R-005), `getOrgDesktopLoginConfig(orgId)`, `getUserDesktopLoginConfig(orgId, ciUserId)`, `getSiteInfo(orgId, siteId)`, `getDialPlanData(orgId)`, `getMultimediaProfileById(orgId, multimediaProfileId)`, `getListOfTeams`, `getAllTeams`, `getListOfAuxCodes`, `getAllAuxCodes` (CONFIG-R-003), `getOutdialAniEntries(orgId, params)` (CONFIG-R-010), and `getWellbeingBreakIdleCode(orgId)` (CONFIG-R-007) | `src/cc.ts` through `services.config`; `getOutdialAniEntries` and `getWellbeingBreakIdleCode` reach applications through ContactCenter wrappers, and ContactCenter caches the wellness code per registration | Internal; marked `@private`/`@ignore`; not exported by `src/index.ts` | `src/services/config/index.ts`, `src/services/index.ts`, `src/cc.ts` |
|
|
129
|
+
| `endPointMap` | This service, plus [`Queue.ts`](../../Queue.ts) (`queueList`), [`EntryPoint.ts`](../../EntryPoint.ts) (`entryPointDialNumberList`), [`AddressBook.ts`](../../AddressBook.ts) (`addressBookEntries`), and [`UserPreference.ts`](../../UserPreference.ts) (`userPreference`, `userPreferenceCreate`), which are not called by `AgentConfigService` | Internal resource builders for contract `wxcc-api-gateway`; route shapes in Protocol and wire format | `src/services/config/constants.ts` |
|
|
130
|
+
|
|
131
|
+
Exact package exports are indexed in the [package architecture](../../../../docs/architecture.md).
|
|
132
|
+
|
|
133
|
+
Compatibility: the desktop-login aggregate change is breaking for consumers of these types and needs a major version of the published package (`package.json`; semver rule in the [package architecture](../../../../docs/architecture.md)). The types `DesktopProfileResponse` (replaced by `AgentProfile`), `URLMapping`, and `AIFeatureFlagsResponse` and the field `Profile.environment` no longer exist in src (`test/unit/spec/services/config/Util.ts` asserts that `parseAgentConfigs` emits no `environment`); `TenantData.callVariablesSuppressed` is now `boolean`, and `parseAgentConfigs` copies it onto the returned profile; `getListOfTeams(orgId, page, pageSize, userDbId)` now filters teams by the user's database id (`filter=userId=={userDbId}`) instead of a list of team ids; auxiliary codes come from the unrestricted organization pool (CONFIG-R-011); and `webexConfig.stateSynchronizationWebex` is now read from the organization-level `webexConfig.stateSynchronization` (`src/services/config/Util.ts`), so it can change from `false` to `true`.
|
|
134
|
+
|
|
135
|
+
These methods exist in `AgentConfigService` but are **not** part of the `getAgentConfig()` aggregation flow. They can be used independently of profile building; applications reach them only through ContactCenter wrappers, because `services` is a private field of ContactCenter in `src/cc.ts`.
|
|
136
|
+
|
|
137
|
+
| Method | Status | Returns | Description |
|
|
138
|
+
| ------ | ------ | ------- | ----------- |
|
|
139
|
+
| `getOutdialAniEntries(orgId, params)` | **Publicly exposed** via `cc.getOutdialAniEntries()` | `OutdialAniEntriesResponse` | Fetch outbound ANI entries for caller ID selection. Supports pagination and search via [`OutdialAniParams`](../types.ts). |
|
|
140
|
+
| `getMultimediaProfileById(orgId, multimediaProfileId)` | **Not exposed, never called** | `MultimediaProfileResponse` | Fetch channel capacities (chat, email, telephony, social) and blending config. Available but unused anywhere. |
|
|
141
|
+
| `getListOfTeams(orgId, page, pageSize, userDbId)` | Used internally by `getAllTeams()` | `ListTeamsResponse` | Single-page team fetch with pagination metadata, filtered by `userDbId`. |
|
|
142
|
+
| `getListOfAuxCodes(orgId, page, pageSize, filter, attributes)` | Used internally by `getAllAuxCodes()` | `ListAuxCodesResponse` | Single-page aux code fetch with pagination metadata. Useful for custom pagination. |
|
|
143
|
+
|
|
144
|
+
The AgentProfile is defined as the [`Profile`](../types.ts) type. This is not an exhaustive list — see [`types.ts`](../types.ts) for the full 50+ field definition. Key fields:
|
|
145
|
+
|
|
146
|
+
| Field | Type | Description |
|
|
147
|
+
| ----- | ---- | ----------- |
|
|
148
|
+
| `agentId` | string | Unique agent identifier |
|
|
149
|
+
| `agentName` | string | Display name |
|
|
150
|
+
| `agentMailId` | string | Email address |
|
|
151
|
+
| `teams` | [`TeamList[]`](../types.ts) | Assigned teams (runtime data from `getAllTeams()`; `Profile` declares `TeamList[]`) |
|
|
152
|
+
| `defaultDn` | string | Default dial number |
|
|
153
|
+
| `idleCodes` | [`Entity[]`](../types.ts) | Available idle codes |
|
|
154
|
+
| `wrapupCodes` | [`Entity[]`](../types.ts) | Available wrapup codes |
|
|
155
|
+
| `webRtcEnabled` | boolean | WebRTC calling enabled |
|
|
156
|
+
| `loginVoiceOptions` | [`LoginOption[]`](../types.ts) | Available login types |
|
|
157
|
+
| `dialPlan` | [`DialPlan`](../types.ts) | Number transformation rules |
|
|
158
|
+
| `isOutboundEnabledForAgent` | boolean | Outbound calling allowed |
|
|
159
|
+
| `outDialEp` | string | Outbound entry point ID |
|
|
160
|
+
| `allowConsultToQueue` | boolean | Whether consult-to-queue is enabled on the Desktop Profile |
|
|
161
|
+
| `accessQueue` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab queue access scope from Desktop Profile |
|
|
162
|
+
| `accessEntryPoint` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab entry-point access scope from Desktop Profile |
|
|
163
|
+
| `accessBuddyTeam` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab buddy-team access scope from Desktop Profile |
|
|
164
|
+
| `isWellnessBreakEnabled` | boolean | Effective wellness gate derived from backend enablement/reminder configuration and positive AI Assistant license quantity |
|
|
165
|
+
|
|
166
|
+
`parseAgentConfigs()` maps the three `access*` fields from the user aggregate's `AgentProfile` section onto the public `Profile` returned by `cc.register()`.
|
|
167
|
+
|
|
168
|
+
Types used by the config service, all defined in [`types.ts`](../types.ts):
|
|
169
|
+
|
|
170
|
+
| Type | Description |
|
|
171
|
+
| ---- | ----------- |
|
|
172
|
+
| `Profile` | Final aggregated agent config returned by `getAgentConfig()` |
|
|
173
|
+
| `OrgDesktopLoginResponse` | Response from `getOrgDesktopLoginConfig()`; sections in Protocol and wire format |
|
|
174
|
+
| `UserDesktopLoginResponse` | Response from `getUserDesktopLoginConfig()` — `user` and `agentProfile` sections (fields in Protocol and wire format) |
|
|
175
|
+
| `AgentResponse` | `user` section of the user aggregate — agent metadata, `dbId`, `siteId`, `agentProfileId` |
|
|
176
|
+
| `AgentProfile` | `agentProfile` section of the user aggregate — layout, dial-plan enablement, login options |
|
|
177
|
+
| `TeamList` | Team record from API — `id`, `name`, `teamType`, `siteId`, `multiMediaProfileId` |
|
|
178
|
+
| `ListTeamsResponse` | Paginated wrapper around `TeamList[]` with `meta` for pagination |
|
|
179
|
+
| `OrgInfo` | Organization info — `tenantId`, timezone |
|
|
180
|
+
| `OrgSettings` | Org feature flags — `webRtcEnabled`, `maskSensitiveData` |
|
|
181
|
+
| `TenantData` | Tenant-level config — inactivity timeout, `forceDefaultDn`, `outdialEnabled` |
|
|
182
|
+
| `SiteInfo` | Site config — `id`, `name`, `multimediaProfileId` |
|
|
183
|
+
| `OrgUrlMappings` | Keyed external URL mappings — `ACQUEON_API_URL`, `ACQUEON_CONSOLE_URL` |
|
|
184
|
+
| `MicrosoftConfig` | Org-level Microsoft presence config — `showUserDetails`, `stateSynchronization` |
|
|
185
|
+
| `WebexConfig` | Org-level Webex presence config — `showUserDetails`, `stateSynchronization` |
|
|
186
|
+
| `MultimediaProfileResponse` | Multimedia profile — channel capacities and settings |
|
|
187
|
+
| `AuxCode` | Auxiliary code record — `id`, `name`, `description`, `workTypeCode` |
|
|
188
|
+
| `ListAuxCodesResponse` | Paginated wrapper around `AuxCode[]` with `meta` |
|
|
189
|
+
| `DialPlanEntity` | Dial plan rule — regex pattern, prefix, strip digits, `active` |
|
|
190
|
+
| `Entity` | Basic entity info — `isSystem`, `name`, `id`, `isDefault` |
|
|
191
|
+
| `WrapupData` | Wrap-up config — auto-wrapup settings, available wrapup codes |
|
|
192
|
+
| `OutdialAniParams` | Parameters for `getOutdialAniEntries()` — ANI ID, pagination, filtering |
|
|
193
|
+
| `LoginOption` | Login types (BROWSER, EXTENSION, AGENT_DN) |
|
|
194
|
+
| `Team` | Team configuration; declared in `src/types.ts`, not in this module, and not used by `Profile.teams` |
|
|
195
|
+
|
|
196
|
+
## Dependencies
|
|
197
|
+
|
|
198
|
+
| Dependency | Why it is required | Failure behavior |
|
|
199
|
+
| ---------- | ------------------ | ---------------- |
|
|
200
|
+
| WebexRequest (`src/services/core/WebexRequest.ts`, [core service](../../core/docs/README.md)) | Singleton taken in the constructor; every method calls `request({service: WCC_API_GATEWAY, resource, method: GET})` | A rejection is logged and rethrown by the calling method |
|
|
201
|
+
| WCC organization/profile/team/site/tenant APIs (contract `wxcc-api-gateway`, service name `wcc-api-gateway`) | Desktop-login aggregates, teams, auxiliary codes, site, dial plan, multimedia profile, and outdial ANI resources | Non-200 responses become `Error('API call failed with {statusCode}')`, except in `getOutdialAniEntries` |
|
|
202
|
+
| ContactCenter registration flow (`src/cc.ts`) | Supplies `orgId` from credentials and `agentId` from the Welcome event, and stores the resolved profile | A `getAgentConfig` rejection propagates into registration |
|
|
203
|
+
| Backend notification names (contract `wxcc-websocket-notifications`) | `CC_AGENT_EVENTS` and `CC_TASK_EVENTS` mirror the WebSocket message `type` strings | A backend type missing from the constants is not re-emitted by `src/cc.ts` |
|
|
204
|
+
| `LoggerProxy` (`src/logger-proxy.ts`) | Info, log, and error lines with `module: CONFIG_FILE_NAME` | None |
|
|
205
|
+
| `LOST_CONNECTION_RECOVERY_TIMEOUT` (`src/services/core/constants.ts`) | Default for `Profile.lostConnectionRecoveryTimeout` when the tenant value is falsy | None |
|
|
206
|
+
|
|
207
|
+
## Requirements
|
|
208
|
+
|
|
209
|
+
| ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
|
|
210
|
+
| --- | ---- | --- | --------------- | ----------------------- | ------------------ | ---------- |
|
|
211
|
+
| CONFIG-R-001 | Start the user desktop-login, organization desktop-login, and auxiliary-code requests together; after the user aggregate resolves, start site, teams, and the conditional dial plan; join all five with `Promise.all`. | Dependent IDs and all-or-nothing consistency require staged orchestration. | `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | None. | PRESENT |
|
|
212
|
+
| CONFIG-R-002 | Include the organization aggregate's `aiFeature` section in `parseAgentConfigs` so `Profile.aiFeature` reflects the organization feature contract. | ApiAIAssistant behavior is gated by the remote organization feature contract. | `src/services/config/index.ts`, `src/services/config/Util.ts` | `test/unit/spec/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` | `src/cc.ts` passes `Profile.aiFeature` to `setAIFeatureFlags` and into the task config flags. | PRESENT |
|
|
213
|
+
| CONFIG-R-003 | Paginate teams and auxiliary codes until completion and include `desktopProfileFilter=true` for auxiliary-code requests. | A partial or unfiltered set yields invalid profile/team/auxiliary choices. | `src/services/config/constants.ts`, `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | None. | PRESENT |
|
|
214
|
+
| CONFIG-R-004 | Expose current response/field names: `MultimediaProfileResponse`, `OrgSettings.maskSensitiveData`, and real TeamList fields only. | Type-name drift causes invalid consumer code and incorrect privacy behavior. | `src/services/config/types.ts` | `test/unit/spec/services/config/index.ts`, `test/unit/spec/services/config/Util.ts` | `maskSensitiveData` defaults to false when the organization value is falsy. | PRESENT |
|
|
215
|
+
| CONFIG-R-005 | Reject the entire profile aggregation when any required dependent request fails. | Consumers must never receive an internally inconsistent partial Profile. | `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | Rejection is asserted for five of the six requests; a `getDialPlanData` rejection inside `getAgentConfig` is not asserted. | PRESENT |
|
|
216
|
+
| CONFIG-R-006 | Always populate `Profile.isWellnessBreakEnabled`; set it true only when `agentWellbeing.enable` is true, `wellnessBreakReminders` is `ENABLED`, and `OrgSettings.aiAssistantQuantity` is greater than zero. Missing or null inputs fail closed. | Hosts need one license-and-server-rollout-aware signal rather than reconstructing partial configuration. | `src/services/config/Util.ts`, `src/services/config/types.ts` | `test/unit/spec/services/config/Util.ts` | The supported SDK contracts expose no separate rollout response field; backend delivery of enabled `agentWellbeing` configuration is the rollout decision. `Profile` declares the field optional. | PRESENT |
|
|
217
|
+
| CONFIG-R-007 | Retrieve the wellness idle code from `/v2/auxiliary-code` using `workType=IDLE_CODE`, `customFilter=isSystemCode==true`, and `desktopProfileFilter=false`; follow pagination and accept only the exact active system code name `WellbeingBreak`. | The dedicated state must be independent of desktop-profile filtering and must never fall back to a similarly named or non-system code. | `src/services/config/index.ts`, `src/services/config/constants.ts` | `test/unit/spec/services/config/index.ts` | `src/cc.ts` caches the result per registration and rejects with `WELLNESS_BREAK_NOT_ENABLED` when the profile flag is false. | PRESENT |
|
|
218
|
+
| CONFIG-R-008 | `CC_EVENTS` is the spread of `CC_AGENT_EVENTS` and `CC_TASK_EVENTS`; each value is the backend WebSocket `type` string, and `src/cc.ts` re-emits a message's `data.type` only when it is one of these values. | The values are the public event names applications subscribe to, and the allow-list stops an unknown or server-injected type from being emitted (comment on `CC_EVENT_ALLOW_LIST` in `src/cc.ts`). | `src/services/config/types.ts`, `src/cc.ts`, `src/index.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/index.ts` | The shared `BuddyAgents` value is listed under Pitfalls and constraints. | Present |
|
|
219
|
+
| CONFIG-R-009 | `getAgentConfig` resolves `multimediaProfileId` from the first team's `multiMediaProfileId`, falling back to the site's `multimediaProfileId` when there is no team or the team has none. | The multimedia profile defines channel capacities; teams override the site default. | `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | None. | Present |
|
|
220
|
+
| CONFIG-R-010 | `getOutdialAniEntries(orgId, params)` adds only the provided `page`, `pageSize`, `search`, `filter`, and `attributes` query parameters, resolves `response.body?.data`, and rethrows a request rejection; it does not check `statusCode`. | `cc.getOutdialAniEntries` is the public caller-ID lookup and records the result count in metrics. | `src/services/config/index.ts`, `src/cc.ts` | `test/unit/spec/services/config/index.ts` | A resolved non-200 response yields `undefined`, not an error (asserted by the 404 and 500 cases). | Present |
|
|
221
|
+
| CONFIG-R-011 | `parseAgentConfigs` keeps active aux codes of each `workTypeCode` from the full pool as `Entity` values, appends the synthetic idle code `{id: '0', name: 'Available'}`, and sets `defaultWrapupCode` to the default wrap-up code id or an empty string. | The desktop-login aggregate does not carry per-agent restriction lists, so the whole pool applies (JSDoc of `getFilterAuxCodes`). | `src/services/config/Util.ts` | `test/unit/spec/services/config/Util.ts` | None. | Present |
|
|
222
|
+
| CONFIG-R-012 | When `dialPlanEnabled` is true, `Profile.dialPlan` is `{type: 'adhocDial', dialPlanEntity}` built from every active plan; otherwise it is `undefined` and no dial-plan request is made. | The aggregate does not carry the per-profile `dialPlans` selection, so all active plans apply (JSDoc of `getFilteredDialplanEntries`). | `src/services/config/Util.ts`, `src/services/config/index.ts` | `test/unit/spec/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` | None. | Present |
|
|
223
|
+
|
|
224
|
+
## Design overview
|
|
225
|
+
|
|
226
|
+
The Config Service is an **internal service** that builds the comprehensive AgentProfile (`Profile` type) from six requests; their order is under Profile aggregation.
|
|
227
|
+
|
|
228
|
+
The AgentProfile is the central configuration object required for an agent to operate within the contact center. It is built during the registration flow (`cc.register()`) and contains all the data an agent needs: identity, team assignments, dial plans, aux codes, login options, and feature flags. Once constructed, the AgentProfile is stored on the `ContactCenter` plugin instance as `this.agentConfig` and is used by other services (Agent, Task) throughout the session.
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
// Config service is used internally during the registration flow.
|
|
232
|
+
// Inside cc.ts → connectWebsocket(), after WebSocket connection is established:
|
|
233
|
+
const agentId = data.agentId;
|
|
234
|
+
const orgId = this.$webex.credentials.getOrgId();
|
|
235
|
+
this.agentConfig = await this.services.config.getAgentConfig(orgId, agentId);
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Stack: TypeScript 5.4 REST client, Promise-based parallel aggregation, Jest 27.
|
|
239
|
+
|
|
240
|
+
Config separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit; profile creation is all-or-nothing (CONFIG-R-005).
|
|
241
|
+
|
|
242
|
+
`parseAgentConfigs` in Util.ts combines all data into a unified `Profile` object. See [types.ts](../types.ts) for full type definitions.
|
|
243
|
+
|
|
244
|
+
[`parseAgentConfigs`](../Util.ts) takes one object `{orgConfig, userData, agentProfileData, teamData, auxCodes, dialPlanData, multimediaProfileId}` typed `OrgDesktopLoginResponse`, `AgentResponse` (the `user` section), `AgentProfile` (the `agentProfile` section), `TeamList[]`, `AuxCode[]`, `DialPlanEntity[]`, and string, and returns a `Profile`. It destructures `organization` (orgInfoData), `organizationSetting` (orgSettingsData), `tenantConfiguration` (tenantData), `urlMappings`, `aiFeature`, `microsoftConfig`, and `webexConfig` from `orgConfig`. `getFilterAuxCodes(auxCodes, WRAP_UP_CODE)` and `getFilterAuxCodes(auxCodes, IDLE_CODE)` check `workTypeCode` and `active` over the full org pool (the aggregate returns no per-agent restriction) and map to `Entity` `{id, name, isSystem, isDefault}`; the hardcoded "Available" state (`id: '0'`) is always appended to idle codes. The returned profile sets `agentId` from `userData.ciUserId`, `analyserUserId` from `userData.id`, `agentName` from `firstName` and `lastName`, `teams` from `teamData` as-is, `webRtcEnabled` from `orgSettingsData`, `loginVoiceOptions` from `agentProfileData.loginVoiceOptions ?? []`, `enterpriseId` from `orgInfoData.tenantId`, `tenantTimezone` from `orgInfoData.timezone`, `multimediaProfileId` from the input, and `aiFeature` unchanged, plus the remaining fields: see Util.ts for the full implementation.
|
|
245
|
+
|
|
246
|
+
## Data flow and sequence coverage
|
|
247
|
+
|
|
248
|
+
Call style: in-process promise calls on `AgentConfigService`, each of which makes authenticated HTTPS
|
|
249
|
+
GET requests through `WebexRequest.request` to the `wcc-api-gateway` service.
|
|
250
|
+
|
|
251
|
+
Sequence coverage:
|
|
252
|
+
|
|
253
|
+
| Operation group | Entry and outcome | Diagram or evidence | Failure and recovery coverage |
|
|
254
|
+
| --------------- | ----------------- | ------------------- | ----------------------------- |
|
|
255
|
+
| Profile aggregation and AI feature flags | `getAgentConfig(orgId, agentId)` resolves one `Profile` | Profile aggregation diagram; `src/services/config/index.ts` | Any required request rejection rejects `getAgentConfig`; no partial Profile is returned. |
|
|
256
|
+
| Team/aux-code pagination | `getAllTeams`, `getAllAuxCodes` resolve the concatenated list | Pagination diagram; `src/services/config/index.ts` | Continue until page metadata is exhausted; any page rejection rejects the operation. |
|
|
257
|
+
| Wellness system idle code | `getWellbeingBreakIdleCode(orgId)` resolves one `Entity` | Wellness idle-code lookup diagram; `src/services/config/index.ts` | Sequential pages stop at the first match; no match rejects with `WELLBEING_BREAK_IDLE_CODE_NOT_FOUND`; a non-200 page rejects. |
|
|
258
|
+
| Single-resource fetches | `getOrgDesktopLoginConfig`, `getUserDesktopLoginConfig`, `getSiteInfo`, `getDialPlanData`, `getMultimediaProfileById`, `getListOfTeams`, `getListOfAuxCodes` resolve the response body | `src/services/config/index.ts` | Non-200 throws `API call failed with {statusCode}`; rejections are logged and rethrown. |
|
|
259
|
+
| Outdial ANI lookup | `getOutdialAniEntries(orgId, params)` resolves `body.data` | `src/services/config/index.ts` | Rejections are rethrown; a resolved non-200 response yields `undefined`. |
|
|
260
|
+
|
|
261
|
+
AI-feature retrieval shares the same actors, ordering, Promise aggregation, and all-or-nothing failure outcome as the other profile dependencies, so it is represented in the Profile aggregation diagram rather than duplicated.
|
|
262
|
+
|
|
263
|
+
### Profile aggregation
|
|
264
|
+
|
|
265
|
+
Main method that aggregates all configuration data into the AgentProfile.
|
|
266
|
+
|
|
267
|
+
**Returns**: `Promise<Profile>`
|
|
268
|
+
|
|
269
|
+
**Flow**:
|
|
270
|
+
|
|
271
|
+
1. Fire the user aggregate (`getUserDesktopLoginConfig`), the org aggregate (`getOrgDesktopLoginConfig`) and aux codes (`getAllAuxCodes`) in parallel
|
|
272
|
+
2. Await the user aggregate — it supplies `user.dbId`, `user.siteId` and `agentProfile.dialPlanEnabled`
|
|
273
|
+
3. Fetch site info (`getSiteInfo`) and teams filtered by `userId` (`getAllTeams`)
|
|
274
|
+
4. Fetch dial plan if `agentProfile.dialPlanEnabled` (`getDialPlanData`)
|
|
275
|
+
5. `Promise.all` the five remaining promises
|
|
276
|
+
6. Resolve `multimediaProfileId` from the team value, falling back to the site value
|
|
277
|
+
7. Parse and combine all data (`parseAgentConfigs`)
|
|
278
|
+
|
|
279
|
+
The following diagram shows how `getAgentConfig` orchestrates six API calls and combines their results into the AgentProfile via `parseAgentConfigs()`:
|
|
280
|
+
|
|
281
|
+
```mermaid
|
|
282
|
+
sequenceDiagram
|
|
283
|
+
participant CC as ContactCenter
|
|
284
|
+
participant Cfg as AgentConfigService
|
|
285
|
+
participant API as WCC APIs
|
|
286
|
+
participant Util as parseAgentConfigs
|
|
287
|
+
CC->>Cfg: getAgentConfig(orgId, agentId)
|
|
288
|
+
par requests started before user data resolves
|
|
289
|
+
Cfg->>API: getUserDesktopLoginConfig
|
|
290
|
+
Cfg->>API: getOrgDesktopLoginConfig
|
|
291
|
+
Cfg->>API: getAllAuxCodes
|
|
292
|
+
end
|
|
293
|
+
API-->>Cfg: user.dbId / user.siteId / agentProfile.dialPlanEnabled
|
|
294
|
+
par user-dependent requests
|
|
295
|
+
Cfg->>API: getSiteInfo + getAllTeams(filter userId==dbId)
|
|
296
|
+
Cfg->>API: conditional dial plan gated on agentProfile.dialPlanEnabled
|
|
297
|
+
end
|
|
298
|
+
Note over Cfg,API: Promise.all awaits 5 result promises after the user aggregate
|
|
299
|
+
alt all succeed
|
|
300
|
+
API-->>Cfg: five results
|
|
301
|
+
Cfg->>Cfg: multimediaProfileId = team value, else site value
|
|
302
|
+
Cfg->>Util: parseAgentConfigs(orgConfig, userData, agentProfileData, ...)
|
|
303
|
+
Util-->>Cfg: Profile including aiFeature
|
|
304
|
+
Cfg-->>CC: Profile
|
|
305
|
+
else any fails
|
|
306
|
+
Cfg-->>CC: throw; no partial Profile
|
|
307
|
+
end
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
### Pagination
|
|
311
|
+
|
|
312
|
+
For endpoints with pagination (teams, aux codes):
|
|
313
|
+
|
|
314
|
+
`getAllTeams(orgId, pageSize, userDbId)` starts at `DEFAULT_PAGE` (0), awaits the first `getListOfTeams(orgId, page, pageSize, userDbId)` request to get `totalPages` from `firstResponse.meta.totalPages`, concatenates `firstResponse.data` into `allTeams`, then issues parallel requests for the remaining pages from `DEFAULT_PAGE + 1` while `page < totalPages`, awaits them with `Promise.all`, and concatenates each `response.data` in request order before it returns `allTeams`. `getAllAuxCodes(orgId, pageSize, filter, attributes)` follows the same pattern over `getListOfAuxCodes`. Both log `{method} API call failed with {error}` and rethrow on any rejection.
|
|
315
|
+
|
|
316
|
+
```mermaid
|
|
317
|
+
sequenceDiagram
|
|
318
|
+
participant Caller
|
|
319
|
+
participant Cfg as AgentConfigService
|
|
320
|
+
participant WR as WebexRequest
|
|
321
|
+
participant API as WCC API
|
|
322
|
+
Caller->>Cfg: getAllTeams(orgId, pageSize, userDbId) / getAllAuxCodes(orgId, pageSize, filter, attributes)
|
|
323
|
+
Cfg->>WR: request page 0
|
|
324
|
+
WR->>API: authenticated GET
|
|
325
|
+
alt first page succeeds
|
|
326
|
+
API-->>Cfg: page 0 data + meta.totalPages
|
|
327
|
+
par remaining pages 1..totalPages-1
|
|
328
|
+
Cfg->>WR: Promise.all(page requests)
|
|
329
|
+
WR->>API: authenticated GETs
|
|
330
|
+
API-->>Cfg: remaining page responses
|
|
331
|
+
end
|
|
332
|
+
alt every remaining page succeeds
|
|
333
|
+
Cfg->>Cfg: concatenate responses in request order
|
|
334
|
+
Cfg-->>Caller: complete accumulated list
|
|
335
|
+
else any remaining page rejects
|
|
336
|
+
Cfg-->>Caller: reject; do not return a partial list
|
|
337
|
+
end
|
|
338
|
+
else first page rejects
|
|
339
|
+
Cfg-->>Caller: reject
|
|
340
|
+
end
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
### Wellness idle-code lookup
|
|
344
|
+
|
|
345
|
+
`getWellbeingBreakIdleCode(orgId)` requests `endPointMap.systemIdleCodes` pages one at a time (the code comment says pagination is intentionally sequential so the lookup can stop as soon as the code is found) and returns the first entry that is active, a system code, and named exactly `WellbeingBreak`.
|
|
346
|
+
|
|
347
|
+
```mermaid
|
|
348
|
+
sequenceDiagram
|
|
349
|
+
participant CC as ContactCenter
|
|
350
|
+
participant Cfg as AgentConfigService
|
|
351
|
+
participant WR as WebexRequest
|
|
352
|
+
participant API as WCC API
|
|
353
|
+
CC->>Cfg: getWellbeingBreakIdleCode(orgId)
|
|
354
|
+
loop page = 0 while page < totalPages
|
|
355
|
+
Cfg->>WR: request systemIdleCodes(orgId, page, 100)
|
|
356
|
+
WR->>API: authenticated GET
|
|
357
|
+
alt statusCode is not 200
|
|
358
|
+
Cfg-->>CC: reject Error(API call failed with statusCode)
|
|
359
|
+
else exact active system code WellbeingBreak on this page
|
|
360
|
+
Cfg-->>CC: Entity {id, name, isSystem: true, isDefault}
|
|
361
|
+
else no match
|
|
362
|
+
Cfg->>Cfg: totalPages = meta.totalPages ?? 1, page += 1
|
|
363
|
+
end
|
|
364
|
+
end
|
|
365
|
+
Cfg-->>CC: reject Error(WELLBEING_BREAK_IDLE_CODE_NOT_FOUND)
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
## Class and component relationships
|
|
369
|
+
|
|
370
|
+
```mermaid
|
|
371
|
+
classDiagram
|
|
372
|
+
class ContactCenter
|
|
373
|
+
class AgentConfigService
|
|
374
|
+
class WebexRequest
|
|
375
|
+
class parseAgentConfigs
|
|
376
|
+
class Profile
|
|
377
|
+
ContactCenter --> AgentConfigService : getAgentConfig
|
|
378
|
+
AgentConfigService --> WebexRequest : six dependent requests
|
|
379
|
+
AgentConfigService --> parseAgentConfigs : aggregate results
|
|
380
|
+
parseAgentConfigs --> Profile : aiFeature + maskSensitiveData
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
`Services` in `src/services/index.ts` owns the single `AgentConfigService` instance; the service takes
|
|
384
|
+
the `WebexRequest` singleton in its constructor and holds no other state.
|
|
385
|
+
|
|
386
|
+
## Use cases and flows
|
|
387
|
+
|
|
388
|
+
| Use case | Actor or caller | Primary steps and outcome | Failure or boundary behavior | Evidence |
|
|
389
|
+
| -------- | --------------- | ------------------------- | ---------------------------- | -------- |
|
|
390
|
+
| `UC-001` | ContactCenter `connectWebsocket` during `cc.register()` | Two-wave profile aggregation: start the user, organization, and aux-code requests together, then site, teams, and the conditional dial plan once the user aggregate resolves, and parse one complete Profile or reject the whole operation (see Profile aggregation). | Any rejection rejects registration's profile step | `src/services/config/index.ts`, `src/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` |
|
|
391
|
+
| `UC-002` | `getAgentConfig`, or a caller needing custom pagination | Paginated teams/aux codes: follow backend page metadata to completion; auxiliary-code requests include `desktopProfileFilter=true`. | Any page rejection rejects the list | `src/services/config/index.ts`, `test/unit/spec/services/config/index.ts` |
|
|
392
|
+
| `UC-003` | `getAgentConfig` | Dial plan and URL mappings: request dial-plan data only when the agent profile enables it, keep only `active` plans, and map the organization aggregate's `urlMappings` into the profile. | Empty or absent `urlMappings` yield empty Acqueon URLs | `src/services/config/index.ts`, `src/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` |
|
|
393
|
+
| `UC-004` | `cc.getOutdialAniEntries` | Outdial ANI retrieval: return the organization-scoped ANI list (`body.data`) through authenticated WebexRequest and propagate request rejections without a partial substitute. | A resolved non-200 response returns `undefined` | `src/services/config/index.ts`, `src/cc.ts`, `test/unit/spec/services/config/index.ts` |
|
|
394
|
+
| `UC-005` | `parseAgentConfigs`; `cc.getWellbeingBreakIdleCode` | Wellness configuration: produce one fail-closed effective profile flag and retrieve the exact system wellness idle code across pages. | No exact code rejects with `WELLBEING_BREAK_IDLE_CODE_NOT_FOUND` | `src/services/config/Util.ts`, `src/services/config/index.ts`, `test/unit/spec/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` |
|
|
395
|
+
|
|
396
|
+
### Cross-boundary use-case flow
|
|
397
|
+
|
|
398
|
+
| Boundary | Transport and ordering | Compatibility | Timeout, retry, and recovery |
|
|
399
|
+
| -------- | ---------------------- | ------------- | ---------------------------- |
|
|
400
|
+
| Contact Center API gateway (`UC-001` to `UC-005`) | `webex.request` with service `wcc-api-gateway` and method GET; ordering under Profile aggregation | Resource shapes in Protocol and wire format | No timeout or retry in this module; the first rejection rejects the operation |
|
|
401
|
+
| Backend WebSocket notifications (contract `wxcc-websocket-notifications`) | Delivered to `src/cc.ts`, which matches `data.type` against `CC_EVENTS` values | Values must equal the backend strings | Unknown types are dropped by the allow-list |
|
|
402
|
+
|
|
403
|
+
## Business rules and invariants
|
|
404
|
+
|
|
405
|
+
| ID | Invariant | WHY | Enforcement source | Test evidence |
|
|
406
|
+
| --- | --------- | --- | ------------------ | ------------- |
|
|
407
|
+
| `INV-001` | `isWellnessBreakEnabled` is always boolean and defaults false when any gate is absent, disabled, or unlicensed. | Fail-closed gating of a licensed feature. | `src/services/config/Util.ts` | `test/unit/spec/services/config/Util.ts` |
|
|
408
|
+
| `INV-002` | The system wellness code lookup is separate from profile auxiliary-code aggregation and uses `desktopProfileFilter=false`. | The system code need not appear in the agent-selectable idle-code list (JSDoc of `getWellbeingBreakIdleCode`). | `src/services/config/constants.ts`, `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` |
|
|
409
|
+
|
|
410
|
+
## Concurrency and reactive flow
|
|
411
|
+
|
|
412
|
+
- Execution model: one JavaScript event loop; every method is `async`.
|
|
413
|
+
- Ordering guarantees: the initial user desktop-login lookup supplies identifiers for the later requests (order under Profile aggregation). Team and aux-code pagination awaits the first page for `meta.totalPages`, then requests the remaining pages in parallel and concatenates them in request order. Only the wellness idle-code lookup awaits pages in order and stops from returned metadata or at the first match.
|
|
414
|
+
- Idempotency and retry: every method is a read; nothing retries or deduplicates.
|
|
415
|
+
- Shared-state protection: no shared mutable state; `parseAgentConfigs` builds a new object per call.
|
|
416
|
+
- Blocking restrictions: none in this module; the caller in `src/cc.ts` awaits `getAgentConfig` before
|
|
417
|
+
it configures the task manager.
|
|
418
|
+
|
|
419
|
+
## Protocol and wire format
|
|
420
|
+
|
|
421
|
+
All Config operations are authenticated REST calls through WebexRequest. Important current routes include:
|
|
422
|
+
|
|
423
|
+
| Message or frame | Version | Producer or serializer | Consumer or parser | Compatibility and ordering rule |
|
|
424
|
+
| ---------------- | ------- | ---------------------- | ------------------ | ------------------------------- |
|
|
425
|
+
| Organization desktop-login aggregate: `endPointMap.orgDesktopLogin(orgId)` builds `organization/{orgId}/desktop-login`; response `OrgDesktopLoginResponse` | — | Contact Center API gateway | `getOrgDesktopLoginConfig`, `parseAgentConfigs` | Key fields: `organization`: `tenantId`, `timezone`. `organizationSetting`: `webRtcEnabled`, `maskSensitiveData`, `campaignManagerEnabled`, `aiAssistantQuantity`. `tenantConfiguration`: `outdialEnabled`, `forceDefaultDn`, `privacyShieldVisible`, `timeoutDesktopInactivityEnabled`. Optional `urlMappings`, `aiFeature`, `microsoftConfig`, `webexConfig`. All organization-, tenant- and feature-scoped configuration in one call |
|
|
426
|
+
| User desktop-login aggregate: `endPointMap.userDesktopLogin(orgId, ciUserId)` builds `organization/{orgId}/v2/user/by-ci-user-id/{ciUserId}/desktop-login`; response `UserDesktopLoginResponse` | v2 | Contact Center API gateway | `getUserDesktopLoginConfig`, `getAgentConfig`, `parseAgentConfigs` | Key fields: `user`: `ciUserId`, `id`, `dbId`, `firstName`, `lastName`, `email`, `agentProfileId`, `siteId`. `agentProfile`: `dialPlanEnabled`, `accessWrapUpCode`, `accessIdleCode`, `loginVoiceOptions`, `viewableStatistics`. Agent identity, team-filter id, site reference, and desktop settings in one call |
|
|
427
|
+
| Teams: `endPointMap.listTeams(orgId, page, pageSize, userDbId)` builds `organization/{orgId}/v2/team?page={page}&pageSize={pageSize}&agentView=true&filter=userId=={userDbId}`; response `ListTeamsResponse` of `TeamList` records | v2 | Contact Center API gateway | `getListOfTeams`, `getAllTeams` | The wire field is `userId` but the value is the user's database id (`user.dbId`); `meta.totalPages` drives pagination; channel capacities belong to `MultimediaProfileResponse` |
|
|
428
|
+
| Auxiliary codes: `endPointMap.listAuxCodes(orgId, page, pageSize, filter, attributes)` builds `organization/{orgId}/v2/auxiliary-code?page={page}&pageSize={pageSize}`, then `&filter=id=in=({filter})` only when filter has length, then `&attributes={attributes}&desktopProfileFilter=true`; response `ListAuxCodesResponse` | v2 | Contact Center API gateway | `getListOfAuxCodes`, `getAllAuxCodes`, `getFilterAuxCodes` | `getAgentConfig` requests `DEFAULT_AUXCODE_ATTRIBUTES`: `id`, `isSystemCode`, `name`, `defaultCode`, `workTypeCode`, `active` |
|
|
429
|
+
| Wellness system idle code: `endPointMap.systemIdleCodes(orgId, page, pageSize)` builds `organization/{orgId}/v2/auxiliary-code?page={page}&pageSize={pageSize}&workType=IDLE_CODE&customFilter=isSystemCode==true&desktopProfileFilter=false` | v2 | Contact Center API gateway | `getWellbeingBreakIdleCode` | Desktop Profile filtering is bypassed |
|
|
430
|
+
| Multimedia profile: `endPointMap.multimediaProfile(orgId, multimediaProfileId)` builds `organization/{orgId}/multimedia-profile/{multimediaProfileId}`; response `MultimediaProfileResponse` | — | Contact Center API gateway | `getMultimediaProfileById` | Channel capacities and blending settings |
|
|
431
|
+
| Dial plan: `endPointMap.dialPlan(orgId)` builds `organization/{orgId}/dial-plan?agentView=true`; response `DialPlanEntity[]` (`id`, `name`, `regularExpression`, `prefix`, `strippedChars`, `active`) | — | Contact Center API gateway | `getDialPlanData`, `getFilteredDialplanEntries` | Requested only when the agent profile enables dial plans; dial plan rules for outbound calling |
|
|
432
|
+
| Site: `endPointMap.siteInfo(orgId, siteId)` builds `organization/{orgId}/site/{siteId}`; response `SiteInfo` | — | Contact Center API gateway | `getSiteInfo`, `getAgentConfig` | Site details, including the `multimediaProfileId` fallback |
|
|
433
|
+
| Outdial ANI entries: `endPointMap.outdialAniEntries(orgId, outdialANI, queryParams)` builds `organization/{orgId}/v2/outdial-ani/{outdialANI}/entry`, plus `?{queryParams}` only when queryParams is non-empty; response body `data` is `OutdialAniEntriesResponse` | v2 | Contact Center API gateway | `getOutdialAniEntries` | Query parameters only for provided `OutdialAniParams` fields |
|
|
434
|
+
| Builders used by other services: `queueList` (`/organization/{orgId}/v2/contact-service-queue?{queryParams}`), `entryPointDialNumberList` (`/organization/{orgId}/v3/dial-number?{queryParams}`), `addressBookEntries` (`/organization/{orgId}/v2/address-book/{addressBookId}/entry?{queryParams}`), `userPreference` (`organization/{orgId}/user-preference/{userId}`), `userPreferenceCreate` (`organization/{orgId}/user-preference`) | v2, v3 | `src/services/config/constants.ts` | `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts`, `src/services/UserPreference.ts` | Not called by `AgentConfigService`; user preferences also use non-GET verbs |
|
|
435
|
+
| WebSocket message `type` and `data.type` names | — | Contact Center notification socket | `src/cc.ts`, `src/services/core/websocket/WebSocketManager.ts` | Must equal a `CC_EVENTS` value to be re-emitted |
|
|
436
|
+
|
|
437
|
+
All endpoints are relative to the WCC API Gateway base URL. Query parameters like `agentView=true` filter responses to agent-relevant data.
|
|
438
|
+
|
|
439
|
+
Exact resources live in `src/services/config/constants.ts`; response/profile fields live in `src/services/config/types.ts`. These responses are parsed and aggregated into a single `Profile` object by the `parseAgentConfigs` function.
|
|
440
|
+
|
|
441
|
+
## Caller-visible failure modes
|
|
442
|
+
|
|
443
|
+
All API methods within the config service throw errors on failure, except that `getOutdialAniEntries` resolves `undefined` for a non-200 response. A failure in any required request, including `getOrgDesktopLoginConfig`, causes the entire AgentProfile fetch to fail (CONFIG-R-005). There is no partial profile — either all data is successfully fetched and aggregated, or the operation throws.
|
|
444
|
+
|
|
445
|
+
Each method follows consistent error handling:
|
|
446
|
+
|
|
447
|
+
Every single-request method, for example `getUserDesktopLoginConfig(orgId, ciUserId)`, logs `LoggerProxy.info` with `module: CONFIG_FILE_NAME` and its `METHODS` name, builds the resource with `endPointMap` (here `endPointMap.userDesktopLogin(orgId, ciUserId)`), awaits `this.webexReq.request({service: WCC_API_GATEWAY, resource, method: HTTP_METHODS.GET})`, throws `new Error('API call failed with {statusCode}')` when `response.statusCode !== 200`, logs `getUserDesktopLoginConfig api success.` through `LoggerProxy.log`, and resolves `response.body`; its catch logs `getUserDesktopLoginConfig API call failed with {error}` through `LoggerProxy.error` and rethrows the error. `getDialPlanData` skips the info line, and `getOutdialAniEntries` skips the status check.
|
|
448
|
+
|
|
449
|
+
A caller wraps the aggregation the same way; the service has already logged the failure:
|
|
450
|
+
|
|
451
|
+
```typescript
|
|
452
|
+
try {
|
|
453
|
+
const profile = await this.services.config.getAgentConfig(orgId, agentId);
|
|
454
|
+
} catch (error) {
|
|
455
|
+
// getAgentConfig already logged `getAgentConfig call failed with ${error}`
|
|
456
|
+
// with module CONFIG_FILE_NAME and method getAgentConfig, then rethrew.
|
|
457
|
+
throw error;
|
|
458
|
+
}
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
**Log patterns to search for:**
|
|
462
|
+
|
|
463
|
+
```typescript
|
|
464
|
+
// General config failure
|
|
465
|
+
"getAgentConfig call failed"
|
|
466
|
+
"module": "config-index", "method": "getAgentConfig"
|
|
467
|
+
|
|
468
|
+
// Specific API method failures
|
|
469
|
+
"getUserDesktopLoginConfig API call failed"
|
|
470
|
+
"getOrgDesktopLoginConfig API call failed"
|
|
471
|
+
"getAllTeams API call failed"
|
|
472
|
+
"getAllAuxCodes API call failed"
|
|
473
|
+
|
|
474
|
+
// Non-200 responses (thrown as errors)
|
|
475
|
+
"API call failed with 404"
|
|
476
|
+
"API call failed with 500"
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
| Condition | Signal or result | Caller behavior | Retry or recovery | Evidence |
|
|
480
|
+
| --------- | ---------------- | --------------- | ----------------- | -------- |
|
|
481
|
+
| One of the parallel API calls failed (network error, HTTP error, or a non-200 response) | `getAgentConfig` rejects with the original error after logging `getAgentConfig call failed with {error}`; a resolved non-200 response becomes `Error('API call failed with {statusCode}')` | Registration fails at the profile step; check the logs for the specific API that failed (each method logs `{method} API call failed with {error}`) | No retry in this module | `src/services/config/index.ts` |
|
|
482
|
+
| Pagination not completing: a team or aux-code page rejects or is not 200 (for example because filter parameters are incorrect) | `getAllTeams` or `getAllAuxCodes` rejects after `getAllTeams API call failed` or `getAllAuxCodes API call failed` | `getAgentConfig` rejects; no partial list is returned | No retry in this module | `src/services/config/index.ts` |
|
|
483
|
+
| Organization or tenant settings have the feature disabled | No error; `webRtcEnabled` (from `orgSettingsData.webRtcEnabled`) or `isOutboundEnabledForTenant` (from `tenantData.outdialEnabled`, the tenant flag for outbound features) is false | Read the flag before offering the feature | None | `src/services/config/Util.ts` |
|
|
484
|
+
| `dialPlanEnabled` is false in the desktop profile | No dial-plan request is made (the dial plan fetch only happens if `dialPlanEnabled === true`); `Profile.dialPlan` is `undefined` | Dial without transformation rules | None | `src/services/config/index.ts`, `src/services/config/Util.ts` |
|
|
485
|
+
| Expected auxiliary codes missing from the returned pool | `getFilterAuxCodes` applies the full organization pool for every agent; aux codes without `active: true` or with another `workTypeCode` are left out; the "Available" state is always appended to idle codes; `Profile.idleCodesAccess` / `wrapUpData.wrapUpProps.wrapUpCodeAccess` still report `ALL` or `SPECIFIC` from `agentProfileData` | Use `idleCodes` and `wrapupCodes` as returned | None | `src/services/config/Util.ts` |
|
|
486
|
+
| Wellness idle code absent | Rejects with `WELLBEING_BREAK_IDLE_CODE_NOT_FOUND` | `cc.getWellbeingBreakIdleCode` surfaces the error | None | `src/services/config/index.ts` |
|
|
487
|
+
| Outdial ANI response not 200 | Resolves `undefined` | Treat as no entries | None | `src/services/config/index.ts` |
|
|
488
|
+
|
|
489
|
+
## Pitfalls and constraints
|
|
490
|
+
|
|
491
|
+
- The team filter value must stay unquoted (`filter=userId=={dbId}`) — the quoted form returns HTTP 400 — and must not carry an `attributes=` projection, which would strip `multiMediaProfileId`, `teamType` and `siteName`.
|
|
492
|
+
- `AGENT_BUDDY_AGENTS` and `AGENT_BUDDY_AGENTS_SUCCESS` share the value `BuddyAgents`, so a listener
|
|
493
|
+
cannot tell them apart; some task values (`REAL_TIME_TRANSCRIPTION`, `SUGGESTED_RESPONSE`, and others)
|
|
494
|
+
are upper-case strings rather than PascalCase.
|
|
495
|
+
- `queueList`, `entryPointDialNumberList`, and `addressBookEntries` resources start with `/`; the
|
|
496
|
+
config-owned resources do not.
|
|
497
|
+
|
|
498
|
+
## Module-specific rules
|
|
499
|
+
|
|
500
|
+
- DO add a new backend notification type to `CC_AGENT_EVENTS` or `CC_TASK_EVENTS` before relying on
|
|
501
|
+
ContactCenter to re-emit it.
|
|
502
|
+
- DO log through `LoggerProxy` with `module: CONFIG_FILE_NAME` and a `METHODS` name.
|
|
503
|
+
|
|
504
|
+
## Key design trade-off
|
|
505
|
+
|
|
506
|
+
| Chosen trade-off | Preserved invariant or benefit | Cost or limitation | Decision evidence |
|
|
507
|
+
| ---------------- | ------------------------------ | ------------------ | ----------------- |
|
|
508
|
+
| One `Promise.all` over all profile dependencies | Consumers get a complete Profile or an error (CONFIG-R-005) | One failed optional-looking call (for example the dial plan) fails registration's profile step | `src/services/config/index.ts` |
|
|
509
|
+
| Two desktop-login aggregates instead of separate organization, setting, tenant, URL-mapping, AI-feature, user, and agent-profile calls | Fewer requests per registration | Per-agent aux-code and dial-plan selections are not carried, so the full active pools apply | `src/services/config/types.ts`, `src/services/config/Util.ts` |
|
|
510
|
+
|
|
511
|
+
## Verification
|
|
512
|
+
|
|
513
|
+
`test/unit/spec/services/config/index.ts` must cover staged user-first orchestration, five-promise aggregation, AI-feature mapping, conditional dial plan, the `userDbId` team filter, pagination, auxiliary-code URL filtering, real response field names, and whole-profile rejection on any required failure.
|
|
514
|
+
|
|
515
|
+
| Requirement or invariant | Test level | Positive evidence | Negative or boundary evidence | Gap |
|
|
516
|
+
| ------------------------ | ---------- | ----------------- | ----------------------------- | --- |
|
|
517
|
+
| `CONFIG-R-001`, `CONFIG-R-009` | Unit | `test/unit/spec/services/config/index.ts` (getAgentConfig staging, team and site arguments, multimedia fallback cases) | `test/unit/spec/services/config/index.ts` | Call order is asserted through arguments, not timing |
|
|
518
|
+
| `CONFIG-R-002` | Unit | `test/unit/spec/services/config/Util.ts` (aiFeature pass-through, absent section) | `test/unit/spec/services/config/Util.ts` | None |
|
|
519
|
+
| `CONFIG-R-003` | Unit | `test/unit/spec/services/config/index.ts` (getListOfTeams unquoted filter, getListOfAuxCodes URL, getAllTeams, getAllAuxCodes) | `test/unit/spec/services/config/index.ts` (non-200 pages) | None |
|
|
520
|
+
| `CONFIG-R-004` | Unit | `test/unit/spec/services/config/index.ts`, `test/unit/spec/services/config/Util.ts` | None found | Types are compile-time only |
|
|
521
|
+
| `CONFIG-R-005` | Unit | `test/unit/spec/services/config/index.ts` | `test/unit/spec/services/config/index.ts` (five rejecting calls) | Keep an explicit rejection assertion for each required dependency category; the dial-plan rejection is missing |
|
|
522
|
+
| `CONFIG-R-006`, `INV-001` | Unit | `test/unit/spec/services/config/Util.ts` (wellness enabled) | `test/unit/spec/services/config/Util.ts` (missing gate, absent section) | A null `aiAssistantQuantity` is not asserted |
|
|
523
|
+
| `CONFIG-R-007`, `INV-002` | Unit | `test/unit/spec/services/config/index.ts` (system-code query across pages) | `test/unit/spec/services/config/index.ts` (inactive and look-alike codes) | A non-200 page is not asserted |
|
|
524
|
+
| `CONFIG-R-008` | Unit | `test/unit/spec/cc.ts` (known type emitted), `test/unit/spec/index.ts` (exports) | `test/unit/spec/cc.ts` (unknown type not emitted) | None |
|
|
525
|
+
| `CONFIG-R-010` | Unit | `test/unit/spec/services/config/index.ts` (minimal, full, partial parameters) | `test/unit/spec/services/config/index.ts` (rejection, 404, 500, missing body) | None |
|
|
526
|
+
| `CONFIG-R-011`, `CONFIG-R-012` | Unit | `test/unit/spec/services/config/Util.ts` (aux codes, dial plan) | `test/unit/spec/services/config/Util.ts` (no default code, dial planning disabled) | None |
|
|
527
|
+
|
|
528
|
+
Run `yarn workspace @webex/contact-center test:unit` from the workspace root. A module specification is complete only when its public surface,
|
|
529
|
+
invariants, failure modes, and test evidence agree with the implementation; coverage is pending a fresh
|
|
530
|
+
coverage review and independent validation.
|