docs(ai-docs): task refactor migration overview (PR 1/4) #644
+179
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,177 @@ | ||
| # Task Refactor Migration Overview | ||
|
|
||
| ## Purpose | ||
|
|
||
| Guide for migrating CC Widgets from ad-hoc task state management to the new SDK state-machine-driven architecture (`task-refactor` branch). This is the single entry point — it tells you what changed, which docs to follow in what order, and what to watch out for. | ||
|
|
||
| --- | ||
|
|
||
| ## Architectural Change: Old vs New | ||
|
|
||
| ``` | ||
| ┌─────────────────────────────────────────────────────────────────────────────────┐ | ||
| │ OLD (Current Widgets) │ NEW (After Migration) │ | ||
| │ │ │ | ||
| │ SDK emits 27 task events │ SDK state machine transitions │ | ||
| │ │ │ │ │ | ||
| │ ▼ │ ▼ │ | ||
| │ Store: refreshTaskList() │ SDK: computes TaskUIControls │ | ||
| │ + update observables manually │ from (TaskState + TaskContext) │ | ||
| │ │ │ │ │ | ||
| │ ▼ │ ▼ │ | ||
| │ Hooks: getControlsVisibility( │ SDK emits │ | ||
| │ deviceType, featureFlags, │ 'task:ui-controls-updated' │ | ||
| │ task, agentId, conferenceEnabled) │ │ │ | ||
| │ │ │ ▼ │ | ||
| │ ▼ │ Widgets read task.uiControls │ | ||
| │ Components: flat ControlVisibility │ │ │ | ||
| │ (22 controls + 7 state flags) │ ▼ │ | ||
| │ │ Components: TaskUIControls │ | ||
| │ Logic spread across: │ (17 controls, each │ | ||
| │ task-util.ts, task-utils.ts, │ { isVisible, isEnabled }) │ | ||
| │ timer-utils.ts, component utils │ │ | ||
| │ │ Single source of truth: │ | ||
| │ │ task.uiControls │ | ||
| └─────────────────────────────────────────────────────────────────────────────────┘ | ||
| ``` | ||
|
|
||
| > The events themselves have not changed — they are the same events, now emitted via the SDK state machine. The key difference is that task state updates (including UI control computation) are handled by the SDK, not by widgets. | ||
|
|
||
| ### What Gets Removed (Dead Code) | ||
|
|
||
| The following widget-side logic is entirely replaced by `task.uiControls` and `task.data`: | ||
|
|
||
| - **`getControlsVisibility()`** (task-util.ts) + all 22 `get*ButtonVisibility` helper functions — replaced by `task.uiControls` | ||
| - **`getConsultStatus()`, `getTaskStatus()`, `getConsultMPCState()`** (store/task-utils.ts) — dead code. These are only called inside `getControlsVisibility()`. Once it is removed, the entire chain is unused and should be deleted. If consult status is needed for display, use `task.data.consultStatus` (SDK provides directly). | ||
| - **`findHoldStatus()`** (store/task-utils.ts) — removed. The SDK state machine tracks hold state internally; widgets get hold state from the task object. Do NOT derive from `controls.hold.isEnabled` (that is an action flag — disabled during conference/consulting even when call is held). | ||
|
|
||
| ### Task Object as Source of Truth for State Flags | ||
|
|
||
| After migration, state flags come from the task object (`ITask`), not from widget-side helper functions: | ||
|
|
||
| | State | Source | Do NOT use | | ||
| |-------|--------|------------| | ||
| | Control visibility/enablement | `task.uiControls` (17 controls, each `{ isVisible, isEnabled }`) | `getControlsVisibility()`, `deviceType`, `featureFlags` | | ||
| | Hold state (`isHeld`) | Task object (SDK tracks internally) | `findHoldStatus()`, `controls.hold.isEnabled` | | ||
| | Conference in progress | `task.data.isConferenceInProgress` | `controls.exitConference.isVisible` (can be false during consult even if conference is active) | | ||
| | Consult status (display) | `task.data.consultStatus` (e.g. `consultInitiated`, `consultAccepted`) | `getConsultStatus()`, `getTaskStatus()` | | ||
|
|
||
| --- | ||
|
|
||
| ## CC Widgets Files Affected | ||
|
|
||
| | Area | Path | | ||
| |------|------| | ||
| | Store event wrapper | `packages/contact-center/store/src/storeEventsWrapper.ts` | | ||
| | Store task utils | `packages/contact-center/store/src/task-utils.ts` | | ||
| | Store constants | `packages/contact-center/store/src/constants.ts` | | ||
| | Store types | `packages/contact-center/store/src/store.types.ts` | | ||
| | Task hooks | `packages/contact-center/task/src/helper.ts` | | ||
| | Task UI utils (to be removed) | `packages/contact-center/task/src/Utils/task-util.ts` | | ||
| | Task types | `packages/contact-center/task/src/task.types.ts` | | ||
| | CC Components — CallControl | `packages/contact-center/cc-components/src/components/task/CallControl/` | | ||
| | CC Components — CallControlCAD | `packages/contact-center/cc-components/src/components/task/CallControlCAD/` | | ||
| | CC Components types | `packages/contact-center/cc-components/src/components/task/task.types.ts` | | ||
| | CC Components — WC wrapper | `packages/contact-center/cc-components/src/wc.ts` | | ||
|
|
||
| > **Not listed:** `timer-utils.ts` and `useHoldTimer.ts` are not directly affected by the task-refactor SDK changes. Timer signature updates (if any) are tracked separately in the hook migration doc. | ||
|
|
||
| --- | ||
|
|
||
| ## Execution Order | ||
|
|
||
| Follow these docs in order. Each doc has old vs new code, before/after examples, and files to modify. | ||
|
|
||
| | Order | Document | What to Do | | ||
| |-------|----------|------------| | ||
| | 1 | [store-event-wiring-migration.md](./store-event-wiring-migration.md) | Update 27 event handlers — switch to SDK `TASK_EVENTS` enum, keep `refreshTaskList()`, add `TASK_UI_CONTROLS_UPDATED` subscription, fix `handleConsultEnd` wiring, replace `isDeclineButtonEnabled` with `task.uiControls.decline.isEnabled` | | ||
| | 2 | [store-task-utils-migration.md](./store-task-utils-migration.md) | Remove dead code (`getControlsVisibility` chain, `findHoldStatus`), delete associated constants; keep `findHoldTimestamp` (timers) and `isIncomingTask` | | ||
| | 3 | [call-control-hook-migration.md](./call-control-hook-migration.md) | Replace `getControlsVisibility()` with `task.uiControls` in `useCallControl` + update timer utils | | ||
| | 4 | [incoming-task-migration.md](./incoming-task-migration.md) | Use `task.uiControls.accept/decline` instead of visibility functions | | ||
| | 5 | [task-list-migration.md](./task-list-migration.md) | Per-task `uiControls` for accept/decline | | ||
| | 6 | [component-layer-migration.md](./component-layer-migration.md) | Update `cc-components` props — `ControlVisibility` → `TaskUIControls`, rename control props | | ||
|
|
||
| --- | ||
|
|
||
| ## SDK Pending Exports (Prerequisites) | ||
|
|
||
| **What the SDK does not export today** (from the package entry point `src/index.ts`): the items in the table below. They exist in SDK source but are not re-exported from the public package, so widget code cannot import them until they are added to the package. | ||
|
|
||
| **Before implementing:** Check whether each required export is available from the SDK — i.e. whether you can import it from the package. If an item is not yet exported, delay the work that depends on it or implement only the parts that do not need it. Full completion of the migration requires these exports. | ||
|
|
||
| | Item | SDK Change Needed | | ||
| |------|---| | ||
| | `TaskUIControls` type | Add to `src/index.ts` | | ||
| | `getDefaultUIControls()` | Add to `src/index.ts` | | ||
| | `TaskState` enum | Add to `src/index.ts` (needed for consult timer labeling) | | ||
| | `uiControls` on `ITask` | Add getter to `ITask` interface (currently only on concrete `Task` class) | | ||
| | `IVoice`, `IDigital`, `IWebRTC` | Add to `src/index.ts` (optional — for type narrowing) | | ||
|
|
||
| --- | ||
|
|
||
| ## Key Types from SDK | ||
|
|
||
| | Type | Purpose | | ||
| |------|---------| | ||
| | `TaskUIControls` | Pre-computed control states (17 controls, each `{ isVisible, isEnabled }`) | | ||
| | `TaskUIControlState` | Shape: `{ isVisible: boolean; isEnabled: boolean }` | | ||
| | `getDefaultUIControls()` | Fallback when no task: `task?.uiControls ?? getDefaultUIControls()` | | ||
| | `TASK_EVENTS` | Import from SDK — delete local enum in `store.types.ts` | | ||
| | `TaskState` | SDK state machine states — needed for consult timer labeling | | ||
|
|
||
| ### `TaskUIControls` Structure | ||
|
|
||
| ```typescript | ||
| type TaskUIControlState = { isVisible: boolean; isEnabled: boolean }; | ||
|
|
||
| type TaskUIControls = { | ||
| accept: TaskUIControlState; | ||
| decline: TaskUIControlState; | ||
| hold: TaskUIControlState; | ||
| transfer: TaskUIControlState; | ||
| consult: TaskUIControlState; | ||
| end: TaskUIControlState; | ||
| recording: TaskUIControlState; | ||
| mute: TaskUIControlState; | ||
| consultTransfer: TaskUIControlState; | ||
| endConsult: TaskUIControlState; | ||
| conference: TaskUIControlState; | ||
| exitConference: TaskUIControlState; | ||
| transferConference: TaskUIControlState; | ||
| mergeToConference: TaskUIControlState; | ||
| wrapup: TaskUIControlState; | ||
| switchToMainCall: TaskUIControlState; | ||
| switchToConsult: TaskUIControlState; | ||
| }; | ||
| ``` | ||
|
|
||
| Widgets no longer compute control visibility — `task.uiControls` is the single source of truth. | ||
|
|
||
| > Specific constants to delete/keep, event name mappings, and ordering constraints (e.g. "do not delete constant X until helper Y is rewritten") are documented in each migration doc listed in the [Execution Order](#execution-order) table. | ||
|
|
||
| --- | ||
|
|
||
| ## SDK Public Method Changes | ||
|
|
||
| | Old | New | Notes | | ||
| |-----|-----|-------| | ||
| | `task.consultTransfer()` | `task.transfer()` | `consultTransfer` is no longer a separate public method; a single `.transfer()` is used for all transfer types | | ||
|
|
||
| --- | ||
|
|
||
| ## CC SDK Reference | ||
|
|
||
| > **Repo:** [webex/webex-js-sdk (task-refactor)](https://github.com/webex/webex-js-sdk/tree/task-refactor) | ||
|
Contributor
There was a problem hiding this comment. Local path should not be put here because this will be different from each person cloning the repo and using this file. For now just add a TODO not that we need to provide local SDK code reference. Rankush has already done some invetsigation in this area so once we have some finalized approach, we shoyld provide the details of that approach to be able to read other repos locally
Contributor
Author
There was a problem hiding this comment. Removed the hardcoded local path. Added a TODO comment: "Provide local SDK cross-repo reference approach once finalized (Rankush is investigating). Do not use hardcoded local paths." |
||
|
|
||
| <!-- TODO: Provide local SDK cross-repo reference approach once finalized (Rankush is investigating). Do not use hardcoded local paths. --> | ||
|
|
||
| | File | Purpose | | ||
| |------|---------| | ||
| | `uiControlsComputer.ts` | Computes `TaskUIControls` from `TaskState` + `TaskContext` — the single source of truth | | ||
| | `Task.ts` | Task service exposing `task.uiControls` getter and `task:ui-controls-updated` event | | ||
| | `constants.ts` | `TaskState` and `TaskEvent` enums | | ||
|
|
||
| --- | ||
|
|
||
| _Created: 2026-03-09_ | ||
| _Updated: 2026-03-24 (added dead code removal and task-object source of truth sections; aligned with PR #648 decisions)_ | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This overview is positioned as the migration entry point, but the
CC Widgets Files Affectedtable omits IncomingTask/TaskList surfaces that still use legacy accept/decline inputs (for examplepackages/contact-center/task/src/helper.ts,cc-components/src/components/task/IncomingTask/incoming-task.utils.tsx, andcc-components/src/components/task/TaskList/task-list.utils.ts). Because the same document’s execution order includes dedicated IncomingTask and TaskList migration steps, leaving these paths out here can cause teams to scope work from this table and miss required updates, leaving oldisBrowser/isDeclineButtonEnabledlogic after switching totask.uiControls.Useful? React with 👍 / 👎.