wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/mappers/device_mapper.py

@@ -0,0 +1,227 @@
+"""Device mapper: CUCM Phones -> Webex Calling Devices.
+
+Maps CUCM phone (SEP) devices to CanonicalDevice objects with four-tier
+model compatibility classification. Skips common-area phones (those go to
+workspace_mapper).
+
+(from 03b-transform-mappers.md §4, device_mapper)
+
+Cross-ref reads:
+    device_in_pool          (Device -> DevicePool)         — resolve pool
+    device_pool_to_location (DevicePool -> Location)       — resolve location
+    device_has_dn           (Device -> DN)                 — line appearances
+    device_owned_by_user    (Device -> EndUser)            — owner
+
+Decisions generated:
+    DEVICE_INCOMPATIBLE          — phone model in Incompatible tier
+
+Convertible devices (``DeviceCompatibilityTier.CONVERTIBLE``) do NOT produce a
+decision. Convertibility is a model classification; the planner unconditionally
+emits a ``device:create_activation_code`` op for every convertible device.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalDevice,
+    DecisionType,
+    DeviceCompatibilityTier,
+    MapperResult,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.cross_reference import classify_phone_model
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    decision_to_store_dict,
+    extract_provenance,
+    manual_option,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# PhoneOS phones: 9800-series + 8875 use cloud deviceId ("cloud" surface).
+# Classic MPP (6800-series, 7800-series, 8800-series) use callingDeviceId ("telephony").
+from wxcli.migration.phone_models import PHONEOS_MODEL_NUMBERS as _CLOUD_SURFACE_SUBSTRINGS
+
+
+class DeviceMapper(Mapper):
+    """Maps CUCM Phones to Webex Calling Devices.
+
+    Skips common-area phones (is_common_area=True in pre_migration_state) —
+    those are handled by workspace_mapper.
+
+    (from 03b-transform-mappers.md §4)
+    """
+
+    name = "device_mapper"
+    depends_on = ["location_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        """Read normalized phone objects and produce CanonicalDevice objects."""
+        result = MapperResult()
+
+        for phone_data in store.get_objects("phone"):
+            phone_id = phone_data["canonical_id"]
+            state = phone_data.get("pre_migration_state") or {}
+
+            # Skip common-area phones — workspace_mapper handles those
+            # (from 03b-transform-mappers.md §4: "does NOT process common-area phones")
+            if state.get("is_common_area", False):
+                continue
+
+            # --- Model classification ---
+            # Uses classify_phone_model() from cross_reference.py
+            # (from 03b-transform-mappers.md §4: phone model compatibility table)
+            model = state.get("model")
+            protocol = state.get("protocol", "SIP")
+
+            # SCCP-only phones are classified as Incompatible regardless of model
+            # (from 03b-transform-mappers.md §4: "SCCP-only phones classified as Incompatible")
+            if protocol and protocol.upper() == "SCCP":
+                compatibility_tier = DeviceCompatibilityTier.INCOMPATIBLE
+            else:
+                compatibility_tier = classify_phone_model(model)
+
+            # --- MAC extraction ---
+            # Strip "SEP" prefix from device name to get 12 hex digits
+            # (from 03b-transform-mappers.md §4: "Extract 12 hex digits after SEP prefix")
+            device_name = state.get("name", phone_id.replace("phone:", ""))
+            mac = None
+            if device_name.upper().startswith("SEP"):
+                mac = device_name[3:].upper()
+            elif len(device_name) == 12 and all(c in "0123456789ABCDEFabcdef" for c in device_name):
+                mac = device_name.upper()
+
+            # Cross-refs link device:{name}, not phone:{name}. Derive the device ID.
+            device_id = f"device:{device_name}"
+
+            # --- Location resolution ---
+            # Chain: device -> device_in_pool -> device_pool_to_location
+            # (from 03b-transform-mappers.md §4: cross-ref dependencies)
+            location_canonical_id = store.resolve_chain(
+                device_id, "device_in_pool", "device_pool_to_location"
+            )
+
+            # --- Owner resolution ---
+            # (from 03b-transform-mappers.md §4: "device_owned_by_user")
+            owner_refs = store.find_cross_refs(device_id, "device_owned_by_user")
+            owner_canonical_id = owner_refs[0] if owner_refs else None
+
+            # --- Line appearances ---
+            # (from 03b-transform-mappers.md §4: "line appearances stored for post-creation config")
+            dn_refs = store.find_cross_refs(device_id, "device_has_dn")
+            line_appearances = state.get("line_appearances", [])
+
+            # --- Display name ---
+            display_name = state.get("description") or device_name
+
+            # --- Device ID surface ---
+            # PhoneOS phones (9800-series, 8875) use cloud deviceId; all others use callingDeviceId.
+            device_id_surface = "cloud" if any(s in (model or "") for s in _CLOUD_SURFACE_SUBSTRINGS) else "telephony"
+
+            # --- Build CanonicalDevice ---
+            device = CanonicalDevice(
+                canonical_id=f"device:{device_name}",
+                provenance=extract_provenance(phone_data),
+                status=MigrationStatus.ANALYZED,
+                mac=mac,
+                model=model,
+                compatibility_tier=compatibility_tier,
+                display_name=display_name,
+                owner_canonical_id=owner_canonical_id,
+                location_canonical_id=location_canonical_id,
+                line_appearances=line_appearances,
+                cucm_protocol=protocol,
+                cucm_device_name=device_name,
+                device_id_surface=device_id_surface,
+            )
+
+            store.upsert_object(device)
+            result.objects_created += 1
+
+            # --- Generate decisions for non-native devices ---
+            if compatibility_tier == DeviceCompatibilityTier.INFRASTRUCTURE:
+                # CTI Ports, CER, gateways, media resources — CUCM infrastructure,
+                # not user devices. Noted in inventory but no migration action needed.
+                # No decision generated — these are silently excluded from the plan.
+                pass
+
+            elif compatibility_tier == DeviceCompatibilityTier.DECT:
+                # DECT handset — hardware is Webex-compatible but requires DECT
+                # network provisioning (Phase 2), not standard phone activation.
+                # No decision generated — the hardware itself is fine.
+                pass
+
+            elif compatibility_tier == DeviceCompatibilityTier.WEBEX_APP:
+                # Software phones (Jabber, CSF, Dual Mode, IP Communicator) transition
+                # to Webex App. User keeps their number/extension, no device record needed
+                # in Webex — Webex App just works with a Calling license.
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.DEVICE_INCOMPATIBLE,
+                    severity="INFO",
+                    summary=(
+                        f"Soft client '{device_name}' ({model}) transitions to Webex App — "
+                        f"no device migration needed"
+                    ),
+                    context={
+                        "device_id": device.canonical_id,
+                        "device_name": device_name,
+                        "model": model,
+                        "protocol": protocol,
+                        "compatibility_tier": compatibility_tier.value,
+                        "webex_app_transition": True,
+                    },
+                    options=[
+                        accept_option(
+                            "User gets Webex Calling license — Webex App replaces "
+                            f"{model}. Number/extension preserved for PSTN dialing."
+                        ),
+                        manual_option("User also needs a physical phone (provision separately)"),
+                    ],
+                    affected_objects=[device.canonical_id],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+
+            elif compatibility_tier == DeviceCompatibilityTier.INCOMPATIBLE:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.DEVICE_INCOMPATIBLE,
+                    severity="HIGH",
+                    summary=(
+                        f"Device '{device_name}' (model: {model or 'unknown'}, "
+                        f"protocol: {protocol}) is incompatible with Webex Calling"
+                    ),
+                    context={
+                        "device_id": device.canonical_id,
+                        "device_name": device_name,
+                        "model": model,
+                        "protocol": protocol,
+                        "compatibility_tier": compatibility_tier.value,
+                    },
+                    options=[
+                        skip_option("Migrate user without device — user must use Webex app or get new phone"),
+                        manual_option("Replace with compatible MPP phone (68xx series recommended)"),
+                    ],
+                    affected_objects=[device.canonical_id],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+
+            elif compatibility_tier == DeviceCompatibilityTier.CONVERTIBLE:
+                # No decision produced. Convertibility is a phone model
+                # classification, not an operator choice. The planner
+                # unconditionally emits a device:create_activation_code op
+                # for convertible devices.
+                pass
+
+        return result
+
+

wxcli/migration/transform/mappers/device_profile_mapper.py

@@ -0,0 +1,190 @@
+"""DeviceProfileMapper — CUCM Extension Mobility profiles → Webex hot desking advisory.
+
+Reads device_profile objects from the store, resolves user ownership
+(owner is the user whose default device profile this is), and produces
+CanonicalDeviceProfile objects. If the user has a workspace at the same location,
+the mapper flags it for hot desking enablement. If not, it produces a
+FEATURE_APPROXIMATION decision.
+
+CUCM EM is architecturally richer — profiles carry lines, speed dials, and services.
+Webex hot desking is login/logout with the user's primary line only.
+
+(from tier2-enterprise-expansion.md §5)
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalDeviceProfile,
+    DecisionType,
+    MigrationObject,
+    MigrationStatus,
+    MapperResult,
+    Provenance,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    extract_provenance,
+    manual_option,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class DeviceProfileMapper(Mapper):
+    """Map CUCM Device Profiles to hot desking advisory objects.
+
+    Tier 2 expansion: produces CanonicalDeviceProfile objects and
+    FEATURE_APPROXIMATION decisions for EM → hot desking mapping.
+    """
+
+    name = "device_profile_mapper"
+    depends_on = ["user_mapper", "workspace_mapper", "location_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+        hoteling_locations: dict[str, int] = {}  # loc_cid -> profile count
+
+        for dp_data in store.get_objects("device_profile"):
+            state = dp_data.get("pre_migration_state") or {}
+            profile_name = state.get("profile_name") or ""
+            if not profile_name:
+                continue
+
+            lines = state.get("lines") or []
+            model = state.get("model") or ""
+            protocol = state.get("protocol") or ""
+            device_pool = state.get("device_pool_name") or ""
+            sd_count = state.get("speed_dial_count", 0)
+            blf_count = state.get("blf_count", 0)
+
+            user_cid = self._find_profile_owner(store, profile_name)
+
+            # Resolve location from device pool cross-ref
+            location_cid: str | None = None
+            if device_pool:
+                dp_cid = f"device_pool:{device_pool}"
+                loc_refs = store.find_cross_refs(dp_cid, "device_pool_to_location")
+                if loc_refs:
+                    location_cid = loc_refs[0] if isinstance(loc_refs[0], str) else loc_refs[0].get("target_id")
+
+            prov = extract_provenance(dp_data)
+            dp = CanonicalDeviceProfile(
+                canonical_id=f"device_profile:{profile_name}",
+                provenance=prov,
+                status=MigrationStatus.ANALYZED,
+                profile_name=profile_name,
+                user_canonical_id=user_cid,
+                model=model,
+                protocol=protocol,
+                lines=lines,
+                device_pool_name=device_pool,
+                speed_dial_count=sd_count,
+                blf_count=blf_count,
+                hoteling_guest_enabled=user_cid is not None,
+                auto_logout_minutes=0,
+                location_canonical_id=location_cid,
+            )
+            store.upsert_object(dp)
+            result.objects_created += 1
+
+            # Track locations for hoteling_location object creation
+            if location_cid:
+                hoteling_locations[location_cid] = hoteling_locations.get(location_cid, 0) + 1
+
+            if user_cid:
+                store.add_cross_ref(user_cid, dp.canonical_id, "user_has_device_profile")
+
+            # Decision: EM has features Webex hot desking doesn't support
+            has_multi_line = len(lines) > 1
+            has_extra_features = sd_count > 0 or blf_count > 0
+
+            if has_multi_line or has_extra_features:
+                features_lost = []
+                if has_multi_line:
+                    features_lost.append(f"{len(lines)} line(s) — Webex hot desking uses primary line only")
+                if sd_count > 0:
+                    features_lost.append(f"{sd_count} speed dial(s)")
+                if blf_count > 0:
+                    features_lost.append(f"{blf_count} BLF entr(ies)")
+
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FEATURE_APPROXIMATION,
+                    severity="LOW",
+                    summary=(
+                        f"Device profile '{profile_name}' has features that "
+                        f"Webex hot desking cannot replicate"
+                    ),
+                    context={
+                        "profile_name": profile_name,
+                        "user_id": user_cid,
+                        "features_lost": features_lost,
+                        "line_count": len(lines),
+                        "speed_dial_count": sd_count,
+                        "blf_count": blf_count,
+                        "classification": "EXTENSION_MOBILITY",
+                    },
+                    options=[
+                        accept_option("Enable hot desking — user gets primary line only, loses profile features"),
+                        skip_option("Don't enable hot desking"),
+                        manual_option("Admin creates workspace and configures manually"),
+                    ],
+                    affected_objects=[dp.canonical_id] + ([user_cid] if user_cid else []),
+                )
+                result.decisions.append(decision)
+
+        # Create hoteling_location objects for location-level voice portal config
+        for loc_cid, profile_count in hoteling_locations.items():
+            loc_obj = MigrationObject(
+                canonical_id=f"hoteling_location:{loc_cid}",
+                provenance=Provenance(
+                    source_system="cucm",
+                    source_id=loc_cid,
+                    source_name="hoteling_location",
+                    extracted_at=datetime.now(timezone.utc),
+                ),
+                status=MigrationStatus.ANALYZED,
+                pre_migration_state={
+                    "location_canonical_id": loc_cid,
+                    "em_profile_count": profile_count,
+                },
+            )
+            store.upsert_object(loc_obj)
+            result.objects_created += 1
+
+        return result
+
+    @staticmethod
+    def _find_profile_owner(store: MigrationStore, profile_name: str) -> str | None:
+        """Try to find the user who owns a device profile.
+
+        CUCM device profiles are typically named 'UDP-{userid}' or
+        '{model}-{userid}'. Also check cross-refs for user_has_device_profile
+        if already built.
+        """
+        # Check common naming patterns
+        lower_name = profile_name.lower()
+        for prefix in ("udp-", "dp-", "em-"):
+            if lower_name.startswith(prefix):
+                userid = profile_name[len(prefix):]
+                user_cid = f"user:{userid}"
+                if store.get_object(user_cid):
+                    return user_cid
+
+        # Brute force: check all users for matching profile reference
+        # (expensive but covers non-standard naming)
+        for user_data in store.get_objects("user"):
+            state = user_data.get("pre_migration_state") or {}
+            default_profile = state.get("defaultProfile") or state.get("deviceProfile") or ""
+            if default_profile == profile_name:
+                return user_data["canonical_id"]
+
+        return None