wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/engine.py

@@ -0,0 +1,256 @@
+"""TransformEngine — orchestrates all 21 mappers in dependency order.
+
+Runs each mapper sequentially in MAPPER_ORDER (tier-sorted), aggregates
+decisions and errors into a single TransformResult. If a mapper raises
+an exception, the engine logs the error, records a MapperError, and
+continues to the next mapper. Downstream mappers that depend on the
+failed mapper's output will find no objects and produce MISSING_DATA
+decisions naturally.
+
+(from 03b-transform-mappers.md section 13, TransformEngine)
+"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+from typing import Any
+
+from wxcli.migration.models import (
+    MapperError,
+    TransformResult,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    decision_to_store_dict,
+)
+from wxcli.migration.transform.mappers.css_mapper import CSSMapper
+from wxcli.migration.transform.mappers.device_mapper import DeviceMapper
+from wxcli.migration.transform.mappers.feature_mapper import FeatureMapper
+from wxcli.migration.transform.mappers.line_mapper import LineMapper
+from wxcli.migration.transform.mappers.location_mapper import LocationMapper
+from wxcli.migration.transform.mappers.routing_mapper import RoutingMapper
+from wxcli.migration.transform.mappers.user_mapper import UserMapper
+from wxcli.migration.transform.mappers.call_forwarding_mapper import CallForwardingMapper
+from wxcli.migration.transform.mappers.monitoring_mapper import MonitoringMapper
+from wxcli.migration.transform.mappers.voicemail_mapper import VoicemailMapper
+from wxcli.migration.transform.mappers.button_template_mapper import ButtonTemplateMapper
+from wxcli.migration.transform.mappers.device_layout_mapper import DeviceLayoutMapper
+from wxcli.migration.transform.mappers.device_profile_mapper import DeviceProfileMapper
+from wxcli.migration.transform.mappers.e911_mapper import E911Mapper
+from wxcli.migration.transform.mappers.ecbn_mapper import EcbnMapper
+from wxcli.migration.transform.mappers.announcement_mapper import AnnouncementMapper
+from wxcli.migration.transform.mappers.moh_mapper import MOHMapper
+from wxcli.migration.transform.mappers.snr_mapper import SNRMapper
+from wxcli.migration.transform.mappers.softkey_mapper import SoftkeyMapper
+from wxcli.migration.transform.mappers.workspace_mapper import WorkspaceMapper
+from wxcli.migration.transform.mappers.call_settings_mapper import CallSettingsMapper
+from wxcli.migration.transform.mappers.executive_assistant_mapper import ExecutiveAssistantMapper
+from wxcli.migration.transform.mappers.device_settings_mapper import DeviceSettingsMapper
+from wxcli.migration.transform.mappers.receptionist_mapper import ReceptionistMapper
+from wxcli.migration.transform.mappers.voicemail_group_mapper import VoicemailGroupMapper
+from wxcli.migration.transform.mappers.dect_mapper import DECTMapper
+
+logger = logging.getLogger(__name__)
+
+# Dependency-sorted execution order.
+# (from 03b-transform-mappers.md section 13: MAPPER_ORDER)
+#
+# Tier 0: LocationMapper, RoutingMapper (no upstream dependencies)
+# Tier 2: UserMapper, LineMapper, WorkspaceMapper (depend on locations)
+# Tier 3: DeviceMapper (depends on users, lines)
+# Tier 4: FeatureMapper (depends on users, lines, locations)
+# Tier 5: CSSMapper (depends on routing_mapper output), VoicemailMapper (depends on users)
+MAPPER_ORDER: list[type[Mapper]] = [
+    LocationMapper,       # Tier 0 — produces locations
+    RoutingMapper,        # Tier 0-2 (trunks, route groups, dial plans)
+    UserMapper,           # Tier 2 (depends on locations)
+    LineMapper,           # Tier 2 (depends on locations for country code)
+    WorkspaceMapper,      # Tier 2 (depends on locations)
+    DeviceMapper,         # Tier 3 (depends on users, lines)
+    DeviceSettingsMapper, # Tier 3: after DeviceMapper, before other dependent mappers
+    DECTMapper,           # Tier 3: after device/location/user mappers — enriches DECT networks
+    FeatureMapper,        # Tier 4 (depends on users, lines, locations)
+    VoicemailGroupMapper, # Tier 4 (depends on locations + features — runs after FeatureMapper)
+    CSSMapper,            # Tier 5 (depends on routing_mapper output)
+    VoicemailMapper,      # Tier 5 (depends on users)
+    CallForwardingMapper, # Tier 6 (depends on users, phones/device cross-refs)
+    MonitoringMapper,     # Tier 6 (depends on users, phones, lines)
+    SNRMapper,            # Tier 6 (depends on users — remote destinations)
+    DeviceProfileMapper,  # Tier 6 (depends on users, workspaces — EM/hot desking)
+    E911Mapper,           # Tier 6 (depends on locations — E911 advisory)
+    EcbnMapper,          # Tier 6 (depends on users, workspaces, locations, lines, devices)
+    MOHMapper,            # Tier 6 (depends on locations — MOH audio sources)
+    AnnouncementMapper,   # Tier 6 (depends on locations, features — announcements)
+    SoftkeyMapper,        # Tier 6 (depends on devices for phone model info)
+    ButtonTemplateMapper, # Tier 6 (depends on devices for phone→template cross-refs)
+    CallSettingsMapper,   # Tier 6 (depends on users — call settings enrichment)
+    ExecutiveAssistantMapper,  # Tier 6 (depends on users — executive/assistant pairings)
+    DeviceLayoutMapper,   # Tier 7 (depends on button_template, monitoring, line, device mappers)
+    ReceptionistMapper,   # Tier 8 (depends on monitoring, device_layout, location, line, user)
+]
+
+
+class TransformEngine:
+    """Orchestrates all 20 transform mappers in dependency order.
+
+    (from 03b-transform-mappers.md section 13)
+    """
+
+    def __init__(self, config: dict[str, Any] | None = None) -> None:
+        """
+        Args:
+            config: Optional configuration dict passed to mappers that need it.
+                Keys used:
+                    default_language        -> LocationMapper
+                    default_country         -> LocationMapper, LineMapper
+                    outside_dial_digit      -> LocationMapper, RoutingMapper, CSSMapper
+                    site_prefix_rules       -> LocationMapper, LineMapper
+                    create_method           -> UserMapper
+                    include_phoneless_users -> UserMapper
+                    country_code            -> RoutingMapper, CSSMapper
+                    category_rules          -> CSSMapper
+        """
+        self.config = config or {}
+
+    def run(self, store: MigrationStore) -> TransformResult:
+        """Run all 21 mappers in dependency order.
+
+        Failure handling: if a mapper raises an exception, log the error,
+        record a MapperError, and continue to the next mapper. Downstream
+        mappers that depend on the failed mapper's output will find no objects
+        and produce MISSING_DATA decisions naturally.
+
+        Returns TransformResult with aggregated decisions and any mapper errors.
+        """
+        result = TransformResult()
+
+        for mapper_cls in MAPPER_ORDER:
+            mapper = self._instantiate_mapper(mapper_cls)
+            mapper_name = mapper.name or mapper_cls.__name__
+
+            logger.info("Running mapper: %s", mapper_name)
+            try:
+                mapper_result = mapper.map(store)
+
+                # Save decisions to store and aggregate into result
+                for decision in mapper_result.decisions:
+                    store.save_decision(decision_to_store_dict(decision))
+                    result.decisions.append(decision)
+
+                logger.info(
+                    "Mapper %s complete: %d created, %d updated, %d decisions",
+                    mapper_name,
+                    mapper_result.objects_created,
+                    mapper_result.objects_updated,
+                    len(mapper_result.decisions),
+                )
+
+            except Exception as exc:
+                tb = traceback.format_exc()
+                logger.error(
+                    "Mapper %s failed with %s: %s",
+                    mapper_name,
+                    type(exc).__name__,
+                    exc,
+                )
+                result.errors.append(
+                    MapperError(
+                        mapper_name=mapper_name,
+                        error_message=str(exc),
+                        traceback=tb,
+                    )
+                )
+                # Continue to next mapper — do NOT abort
+
+        return result
+
+    def _instantiate_mapper(self, mapper_cls: type[Mapper]) -> Mapper:
+        """Create a mapper instance with the appropriate config subset.
+
+        Each mapper's __init__ takes different keyword arguments.  We inspect
+        the mapper class and pass the relevant keys from self.config.
+        """
+        cfg = self.config
+
+        if mapper_cls is LocationMapper:
+            return LocationMapper(
+                default_language=cfg.get("default_language", "en_us"),
+                default_country=cfg.get("default_country", "US"),
+                outside_dial_digit=str(cfg.get("outside_dial_digit", "9")),
+                site_prefix_rules=cfg.get("site_prefix_rules"),
+            )
+
+        if mapper_cls is RoutingMapper:
+            return RoutingMapper(
+                country_code=cfg.get("country_code", "+1"),
+                outside_dial_digit=str(cfg.get("outside_dial_digit", "9")),
+            )
+
+        if mapper_cls is UserMapper:
+            return UserMapper(
+                create_method=cfg.get("create_method", "people_api"),
+                include_phoneless_users=cfg.get("include_phoneless_users", False),
+            )
+
+        if mapper_cls is LineMapper:
+            return LineMapper(
+                default_country_code=cfg.get("default_country", "US"),
+                site_prefix_rules=cfg.get("site_prefix_rules"),
+            )
+
+        if mapper_cls is WorkspaceMapper:
+            return WorkspaceMapper()
+
+        if mapper_cls is DeviceMapper:
+            return DeviceMapper()
+
+        if mapper_cls is DeviceSettingsMapper:
+            return DeviceSettingsMapper()
+
+        if mapper_cls is FeatureMapper:
+            return FeatureMapper()
+
+        if mapper_cls is CSSMapper:
+            return CSSMapper(
+                category_rules=cfg.get("category_rules"),
+                country_code=cfg.get("country_code", "+1"),
+                outside_dial_digit=str(cfg.get("outside_dial_digit", "9")),
+            )
+
+        if mapper_cls is VoicemailMapper:
+            return VoicemailMapper()
+
+        if mapper_cls is CallForwardingMapper:
+            return CallForwardingMapper()
+
+        if mapper_cls is MonitoringMapper:
+            return MonitoringMapper()
+
+        if mapper_cls is SoftkeyMapper:
+            return SoftkeyMapper()
+
+        if mapper_cls is ButtonTemplateMapper:
+            return ButtonTemplateMapper()
+
+        if mapper_cls is MOHMapper:
+            return MOHMapper()
+
+        if mapper_cls is AnnouncementMapper:
+            return AnnouncementMapper()
+
+        if mapper_cls is DeviceLayoutMapper:
+            return DeviceLayoutMapper()
+
+        if mapper_cls is CallSettingsMapper:
+            return CallSettingsMapper()
+
+        if mapper_cls is EcbnMapper:
+            return EcbnMapper()
+
+        if mapper_cls is DECTMapper:
+            return DECTMapper()
+
+        # Fallback: attempt no-arg construction
+        return mapper_cls()  # type: ignore[call-arg]

wxcli/migration/transform/mappers/CLAUDE.md

@@ -0,0 +1,123 @@
+# mappers/ — CUCM-to-Webex Transform Mappers (Phase 05)
+
+26 mapper classes that read normalized CUCM objects from the store, resolve cross-references, and produce Webex-ready canonical objects. Each mapper extends `Mapper` (base.py) and implements `map(store) -> MapperResult`.
+
+## Mapper Contract
+
+```python
+class Mapper(ABC):
+    name: str = ""                 # unique name used in depends_on lists
+    depends_on: list[str] = []    # other mapper names that must run first
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        """Read CUCM objects, produce Webex canonical objects + decisions."""
+```
+
+Mappers are run by `transform/engine.py` in topological order. Each mapper:
+1. Reads objects from the store (`store.get_objects(object_type)`)
+2. Resolves cross-refs (`store.find_cross_refs(canonical_id, relationship)`)
+3. Calls `store.upsert_object(canonical_obj)` for each output object
+4. Calls `store.save_decision(decision_to_store_dict(d))` for unresolvable cases
+5. Returns `MapperResult(objects_created=N, decisions_created=M, ...)`
+
+**base.py utilities:**
+- `extract_provenance(data)` — reconstructs `Provenance` from a stored object dict
+- `hash_id(value)` — deterministic 12-char hex ID from SHA256
+- `decision_to_store_dict(decision)` — converts `Decision` model to store-ready dict (embeds `affected_objects` into `context._affected_objects`)
+- `skip_option()`, `manual_option()`, `accept_option()` — standard decision option builders
+
+## Mapper Inventory
+
+Execution order determined by `depends_on` (topological sort):
+
+### Tier 1 — No dependencies
+
+| Mapper | `name` | Produces | Source objects |
+|--------|--------|---------|----------------|
+| `LocationMapper` | `location_mapper` | `CanonicalLocation`, `CanonicalSchedule` (operating hours) | `device_pool`, `datetime_group`, `cucm_location` |
+| `RoutingMapper` | `routing_mapper` | `CanonicalTrunk`, `CanonicalRouteGroup`, `CanonicalRouteList`, `CanonicalTranslationPattern`, `CanonicalOperatingMode` | `gateway`, `sip_trunk`, `route_group`, `route_list`, `route_pattern`, `time_schedule`, `time_period` |
+
+### Tier 2 — Depends on location/routing
+
+| Mapper | `name` | Depends on | Produces | Source objects |
+|--------|--------|-----------|---------|----------------|
+| `LineMapper` | `line_mapper` | `location_mapper` | `CanonicalLine` (data-only, consumed by user:create / workspace:assign_number) | `dn` (directory number) |
+| `UserMapper` | `user_mapper` | `location_mapper` | `CanonicalUser` | `user` |
+| `DeviceMapper` | `device_mapper` | `location_mapper` | `CanonicalDevice` (5-tier: NATIVE_MPP / CONVERTIBLE / WEBEX_APP / INCOMPATIBLE / DECT) | `phone` (raw) |
+| `DECTMapper` | `dect_mapper` | `location_mapper`, `device_mapper`, `user_mapper` | `CanonicalDECTNetwork` (enriched with resolved location, model, handset assignments, base stations) | `dect_network` (normalized by `normalize_dect_group`) |
+
+### Tier 3 — Depends on users/lines/devices
+
+| Mapper | `name` | Depends on | Produces | Source objects |
+|--------|--------|-----------|---------|----------------|
+| `DeviceSettingsMapper` | `device_settings_mapper` | `device_mapper`, `location_mapper` | `device_settings_template` | `phone`, `device` | Groups phones by (model_family, location), maps CUCM device settings to Webex, generates templates with per-device overrides |
+| `FeatureMapper` | `feature_mapper` | `location_mapper`, `line_mapper`, `user_mapper` | `CanonicalHuntGroup`, `CanonicalCallQueue`, `CanonicalAutoAttendant`, `CanonicalCallPark`, `CanonicalPickupGroup`, `CanonicalPagingGroup`, `CanonicalLocationSchedule`, `CanonicalOperatingMode` | `hunt_pilot`, `hunt_list`, `line_group`, `call_park`, `pickup_group`, `time_schedule`, `time_period` |
+| `WorkspaceMapper` | `workspace_mapper` | `location_mapper` | `CanonicalWorkspace` (common-area phones) with `call_settings` populated from raw phone state | `phone` (raw, `ownerUserName=None`) |
+| `MonitoringMapper` | `monitoring_mapper` | `user_mapper`, `line_mapper` | `CanonicalMonitoringList` | `phone` (raw, `busyLampFields`) |
+| `CallForwardingMapper` | `call_forwarding_mapper` | `user_mapper`, `line_mapper` | `CanonicalCallForwarding` | `phone` (raw, per-line forwarding) |
+| `CallSettingsMapper` | `call_settings_mapper` | `user_mapper` | (call settings enrichment) | `user` | Also detects intercept candidates via `user_has_intercept_signal` cross-ref (Pass 2 — independent of phone iteration) |
+| `CSSMapper` | `css_mapper` | `routing_mapper`, `user_mapper`, `line_mapper`, `device_mapper` | `CanonicalCallingPermission`, `CanonicalDialPlan` | `css`, `partition`, `route_pattern` |
+| `ButtonTemplateMapper` | `button_template_mapper` | `device_mapper` | `CanonicalLineKeyTemplate` | `button_template` (raw) |
+| `ExecutiveAssistantMapper` | `executive_assistant_mapper` | `user_mapper` | `CanonicalExecutiveAssistant` | `exec_asst_pair`, `exec_setting` |
+| `EcbnMapper` | `ecbn_mapper` | `user_mapper`, `workspace_mapper`, `location_mapper`, `line_mapper`, `device_mapper` | `CanonicalEcbnConfig` | `user`, `workspace`, `line`, `device` (cross-refs) |
+
+### Tier 4 — Phase 3 mappers (depend on button templates + device layout inputs)
+
+| Mapper | `name` | Depends on | Produces | Source objects |
+|--------|--------|-----------|---------|----------------|
+| `DeviceLayoutMapper` | `device_layout_mapper` | `button_template_mapper`, `monitoring_mapper`, `line_mapper`, `device_mapper` | `CanonicalDeviceLayout` | `phone` (raw) + `CanonicalLineKeyTemplate` |
+| `SoftkeyMapper` | `softkey_mapper` | `device_mapper` | `CanonicalSoftkeyConfig` (2 per template: 1 template-level + N per-device) | `button_template` (raw softkey data), `phone` (raw) |
+| `VoicemailMapper` | `voicemail_mapper` | `user_mapper` | (voicemail config enrichment) | `voicemail_profile`, `user` |
+| `VoicemailGroupMapper` | `voicemail_group_mapper` | `location_mapper`, `feature_mapper` | `CanonicalVoicemailGroup` (Unity Connection shared mailboxes) | `voicemail_group` (raw Unity Connection CallHandlers) |
+
+---
+
+## Phase 3 Mappers in Detail
+
+### ButtonTemplateMapper
+
+Reads `button_template` raw objects, resolves model-specific line key counts, produces `CanonicalLineKeyTemplate`. Filters UNMAPPED keys before writing. Only produces templates where `phones_using > 0` (dead templates are skipped by the planner).
+
+Key fields on output: `name`, `device_model`, `line_keys` (list of `{index, key_type, label?, value?}`), `kem_keys`, `kem_module_type`, `phones_using`.
+
+### DeviceLayoutMapper
+
+Merges `CanonicalLineKeyTemplate` key structure with per-phone line appearances from raw phone objects. Detects shared lines via `CanonicalSharedLine` objects.
+
+Reads raw phone via `store.get_objects("phone")`, looks up the phone's button template via cross-ref, resolves line members from `busyLampFields` and `lines`.
+
+Key fields on `CanonicalDeviceLayout`: `device_canonical_id`, `device_id_surface` (`"cloud"` or `"telephony"`), `template_canonical_id`, `owner_canonical_id`, `line_members` (list of `{port, member_canonical_id, line_type}`), `resolved_line_keys`, `resolved_kem_keys`.
+
+**`member_canonical_id`** on `line_members` is what `handle_device_layout_configure` uses to resolve Webex IDs from `deps`. It's the canonical_id of the user or workspace assigned to that port.
+
+**Convertible-device skip.** Devices classified as `DeviceCompatibilityTier.CONVERTIBLE` do not get a `CanonicalDeviceLayout` emitted. The mapper checks the device's `compatibility_tier` and continues past the phone silently. Rationale: these phones use activation-code registration (`POST /devices/activationCode`) and auto-configure post-registration, so applying line key templates during the main execution pipeline would race registration. Post-registration bulk layout application is tracked as future work.
+
+### SoftkeyMapper
+
+Reads softkey template data (via SQL — not AXL) and PSK-capable phone references. Produces **two kinds** of `CanonicalSoftkeyConfig`:
+
+1. **Template-level** (`is_psk_target=False`) — `canonical_id=f"softkey_config:{template_name}"`. Report-only. The planner's `_expand_softkey_config` returns `[]` for these — no execution ops produced.
+2. **Per-device** (`is_psk_target=True`) — `canonical_id=f"softkey_config:device:{device_name}"`. One per PSK-capable phone referencing the template. These drive `handle_softkey_config_configure`.
+
+Key fields: `is_psk_target`, `device_canonical_id` (set only for per-device objects), `psk_mappings` (list of `{psk_slot, keyword}`), `state_key_lists` (`{webex_state: [keywords]}`), `cucm_template_name`, `phones_using`.
+
+**PSK-capable models:** 9861 (with 120 KEM buttons), 8875. The mapper checks `_is_psk_capable_model(model)` before creating per-device objects.
+
+---
+
+## Key Gotchas
+
+- **Raw phones vs CanonicalDevice.** Mappers that need `speeddials`, `busyLampFields`, or per-line forwarding call `store.get_objects("phone")` to get raw phone dicts (object_type="phone", canonical_id="phone:{name}"). Do NOT call `store.get_objects("device")` for this — that returns `CanonicalDevice` objects which have already lost the raw AXL fields.
+- **DeviceSettingsMapper requires raw phone data.** Reads `product_specific_config`, `cucm_common_phone_config`, `cucm_user_locale`, etc. from `pre_migration_state` — these fields come from the normalized phone objects, not CanonicalDevice.
+- **`device_id_surface` field.** Added to `CanonicalDevice` and `CanonicalDeviceLayout` in Phase 3. Values: `"cloud"` (9800-series + 8875 PhoneOS phones using cloud `deviceId`) or `"telephony"` (classic MPP phones using `callingDeviceId`). The execute handler uses this to decide which API surface to call.
+- **`device_canonical_id` field on `CanonicalSoftkeyConfig`.** Only set on per-device objects (`is_psk_target=True`). The planner checks `device_canonical_id` presence before adding dependency edges.
+- **PSK slot lowercasing.** The mapper stores `psk_slot` as uppercase (e.g., `"PSK1"`). The execute handler lowercases it when building `softKeyLayout.psk.psk1` keys. The state key list state names in `state_key_lists` are already in Webex format (e.g., `"idle"`, `"progressing"` — NOT CUCM names).
+- **`ringOut` → `progressing`.** `CUCM_STATE_TO_PSK_STATE` maps CUCM's `ringOut` to Webex's `progressing`, producing key `softKeyLayout.softKeyMenu.progressingKeyList`. The incorrect value `"processing"` was fixed — see comment in `softkey_mapper.py`.
+- **DECT handsets (6823/6825/6825ip) are classified as `DECT` tier** — compatible hardware that needs DECT network provisioning, not standard phone activation. No decision is generated by the mapper or analyzer.
+- **DECTMapper auto-selects network model.** DBS-110 is chosen when handset_count ≤ 30; DBS-210 for >30. This selection is overridable by the operator via `DECT_NETWORK_DESIGN` decision. Without a `--dect-inventory` CSV (columns: `coverage_zone`, `base_station_mac`, `base_station_model`), base_stations stays empty and the mapper raises `DECT_NETWORK_DESIGN` at MEDIUM severity.
+- **DECT networks group by CUCM device pool.** `normalize_dect_group()` groups all DECT-tier devices that share a device pool into one `dect_network:` object. DECTMapper then resolves that pool to a Webex location via `device_pool_to_location` cross-refs. Multi-zone ambiguity (same location, multiple pools) produces a `DECT_NETWORK_DESIGN` HIGH decision.
+- **CSSMapper produces both permissions AND dial plans.** It reads the full CSS→partition→route-pattern graph to classify calling permissions (international/national/local) and generate `CanonicalDialPlan` objects from blocking/non-blocking route patterns.
+- **FeatureMapper converts CUCM hunt pilots → hunt groups.** CUCM's hunt pilot → hunt list → line group chain collapses into a single `CanonicalHuntGroup`. Agent resolution goes via DN → user cross-refs.
+- **LocationMapper writes `device_pool_to_location` cross-refs.** This is the only cross-ref NOT written by `CrossReferenceBuilder` — it requires a decision when device pool → location mapping is ambiguous.
+- **FeatureMapper extracts forwarding/overflow.** `_map_hunt_pilots()` reads `forwardHuntNoAnswer.destination`, `forwardHuntBusy.destination`, and `queueCalls.{queueFullDestination,maxWaitTimeDestination,maxWaitTime,noAgentDestination}` from the hunt pilot AXL state and writes them onto `CanonicalHuntGroup` / `CanonicalCallQueue`. `_map_cti_route_points()` reads `callForwardAll.destination` from the CTI RP and writes it onto `CanonicalAutoAttendant`. The planner emits tier-5 `configure_*` ops only when these fields are non-empty.
+- **FeatureMapper writes `feature_forwards_to_voicemail_group` cross-refs.** When a hunt group/call queue forwarding destination matches a voicemail group extension, the mapper writes a cross-ref from the feature's canonical_id to the voicemail group's canonical_id. This drives a dependency edge in the execution graph: `voicemail_group:create` must complete before `hunt_group:configure_forwarding` / `call_queue:configure_forwarding` / `call_queue:configure_stranded_calls` can run (Phase C overflow linkage).

wxcli/migration/transform/mappers/__init__.py

@@ -0,0 +1,76 @@
+"""Transform mappers — CUCM canonical objects to Webex canonical objects.
+
+Each mapper reads resolved canonical objects (post-normalization, post-cross-reference)
+from the MigrationStore and produces Webex-ready canonical objects plus decisions for
+anything that can't be cleanly mapped.
+
+(from 03b-transform-mappers.md, mapper contract and execution order)
+"""
+
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    decision_to_store_dict,
+    manual_option,
+    skip_option,
+)
+from wxcli.migration.transform.mappers.button_template_mapper import ButtonTemplateMapper
+from wxcli.migration.transform.mappers.call_forwarding_mapper import CallForwardingMapper
+from wxcli.migration.transform.mappers.css_mapper import CSSMapper
+from wxcli.migration.transform.mappers.monitoring_mapper import MonitoringMapper
+from wxcli.migration.transform.mappers.device_mapper import DeviceMapper
+from wxcli.migration.transform.mappers.feature_mapper import FeatureMapper
+from wxcli.migration.transform.mappers.line_mapper import LineMapper
+from wxcli.migration.transform.mappers.location_mapper import LocationMapper
+from wxcli.migration.transform.mappers.routing_mapper import RoutingMapper
+from wxcli.migration.transform.mappers.user_mapper import UserMapper
+from wxcli.migration.transform.mappers.voicemail_mapper import VoicemailMapper
+from wxcli.migration.transform.mappers.voicemail_group_mapper import VoicemailGroupMapper
+from wxcli.migration.transform.mappers.device_layout_mapper import DeviceLayoutMapper
+from wxcli.migration.transform.mappers.softkey_mapper import SoftkeyMapper
+from wxcli.migration.transform.mappers.device_profile_mapper import DeviceProfileMapper
+from wxcli.migration.transform.mappers.e911_mapper import E911Mapper
+from wxcli.migration.transform.mappers.moh_mapper import MOHMapper
+from wxcli.migration.transform.mappers.snr_mapper import SNRMapper
+from wxcli.migration.transform.mappers.announcement_mapper import AnnouncementMapper
+from wxcli.migration.transform.mappers.workspace_mapper import WorkspaceMapper
+from wxcli.migration.transform.mappers.executive_assistant_mapper import ExecutiveAssistantMapper
+from wxcli.migration.transform.mappers.receptionist_mapper import ReceptionistMapper
+from wxcli.migration.transform.mappers.device_settings_mapper import DeviceSettingsMapper
+from wxcli.migration.transform.mappers.call_settings_mapper import CallSettingsMapper
+from wxcli.migration.transform.mappers.ecbn_mapper import EcbnMapper
+from wxcli.migration.transform.mappers.dect_mapper import DECTMapper
+
+__all__ = [
+    "Mapper",
+    "LocationMapper",
+    "UserMapper",
+    "LineMapper",
+    "DeviceMapper",
+    "WorkspaceMapper",
+    "RoutingMapper",
+    "FeatureMapper",
+    "CSSMapper",
+    "VoicemailMapper",
+    "VoicemailGroupMapper",
+    "CallForwardingMapper",
+    "MonitoringMapper",
+    "ButtonTemplateMapper",
+    "DeviceLayoutMapper",
+    "SoftkeyMapper",
+    "SNRMapper",
+    "E911Mapper",
+    "MOHMapper",
+    "AnnouncementMapper",
+    "DeviceProfileMapper",
+    "ExecutiveAssistantMapper",
+    "ReceptionistMapper",
+    "DeviceSettingsMapper",
+    "CallSettingsMapper",
+    "EcbnMapper",
+    "DECTMapper",
+    "skip_option",
+    "manual_option",
+    "accept_option",
+    "decision_to_store_dict",
+]

wxcli/migration/transform/mappers/announcement_mapper.py

@@ -0,0 +1,122 @@
+"""AnnouncementMapper — CUCM Announcements → audio asset advisory.
+
+This mapper is advisory-only — there is no automated audio file transfer
+from CUCM to Webex. Every announcement produces an AUDIO_ASSET_MANUAL
+decision requiring the admin to manually download and re-upload audio.
+
+(from tier2-enterprise-expansion.md §2.4)
+"""
+
+from __future__ import annotations
+
+import logging
+
+from wxcli.migration.models import (
+    CanonicalAnnouncement,
+    DecisionOption,
+    DecisionType,
+    MigrationStatus,
+    MapperResult,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    extract_provenance,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# File extension → media type mapping
+_EXT_TO_MEDIA_TYPE: dict[str, str] = {
+    ".wav": "WAV",
+    ".wma": "WMA",
+    ".mp3": "MP3",
+    ".au": "AU",
+}
+
+
+def _detect_media_type(file_name: str | None) -> str:
+    """Detect media type from file extension."""
+    if not file_name:
+        return "UNKNOWN"
+    lower = file_name.lower()
+    for ext, media_type in _EXT_TO_MEDIA_TYPE.items():
+        if lower.endswith(ext):
+            return media_type
+    return "UNKNOWN"
+
+
+class AnnouncementMapper(Mapper):
+    """Map CUCM Announcements to CanonicalAnnouncement objects with decisions.
+
+    Every announcement produces an AUDIO_ASSET_MANUAL decision because
+    there is no automated audio transfer path from CUCM to Webex.
+
+    Tier 2 expansion: depends on location_mapper and feature_mapper
+    for cross-reference context.
+    """
+
+    name = "announcement_mapper"
+    depends_on = ["location_mapper", "feature_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+
+        announcements = store.get_objects("announcement")
+        if not announcements:
+            return result
+
+        for ann_data in announcements:
+            state = ann_data.get("pre_migration_state") or {}
+            name = state.get("name") or ""
+            description = state.get("description") or ""
+            file_name = state.get("file_name") or ""
+            media_type = _detect_media_type(file_name)
+
+            prov = extract_provenance(ann_data)
+            canonical = CanonicalAnnouncement(
+                canonical_id=f"announcement:{name}",
+                provenance=prov,
+                status=MigrationStatus.ANALYZED,
+                name=name,
+                file_name=file_name,
+                media_type=media_type,
+                source_system="cucm",
+            )
+            store.upsert_object(canonical)
+            result.objects_created += 1
+
+            # Every announcement needs manual audio migration
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.AUDIO_ASSET_MANUAL,
+                severity="MEDIUM",
+                summary=(
+                    f"Announcement '{name}' requires manual audio migration"
+                    f"{f' ({media_type} file: {file_name})' if file_name else ''}"
+                ),
+                context={
+                    "announcement_name": name,
+                    "file_name": file_name,
+                    "media_type": media_type,
+                    "description": description,
+                    "advisory_type": "audio_asset_manual",
+                },
+                options=[
+                    accept_option(
+                        "Admin downloads audio from CUCM and uploads to Webex announcement repository"
+                    ),
+                    DecisionOption(
+                        id="use_default",
+                        label="Use Webex default",
+                        impact="Feature uses Webex default greeting instead of custom audio",
+                    ),
+                    skip_option("Feature configured without custom audio"),
+                ],
+                affected_objects=[f"announcement:{name}"],
+            )
+            result.decisions.append(decision)
+
+        return result