wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/mappers/monitoring_mapper.py

@@ -0,0 +1,221 @@
+"""MonitoringMapper — CUCM BLF → Webex per-person monitoring list.
+
+Reads phone objects from the store (which contain busyLampFields from getPhone),
+resolves user ownership via device_owned_by_user cross-ref, resolves BLF
+targets to user canonical IDs via line cross-refs, and produces
+CanonicalMonitoringList objects.
+
+Speed dials are NOT mapped — they stay in phone metadata for reporting.
+Webex monitoring list max is 50 entries; overflow produces FEATURE_APPROXIMATION.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalMonitoringList,
+    DecisionType,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.models import MapperResult
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    extract_provenance,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+WEBEX_MONITORING_MAX = 50
+
+
+def _extract_blf_entries(state: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract BLF entries from phone pre_migration_state.
+
+    Handles both raw AXL format (nested dict) and pre-normalized list.
+    """
+    blf = state.get("busyLampFields")
+    if blf is None:
+        return []
+    if isinstance(blf, list):
+        return blf
+    if isinstance(blf, dict):
+        entries = blf.get("busyLampField", [])
+        if isinstance(entries, list):
+            return entries
+        if isinstance(entries, dict):
+            return [entries]
+    return []
+
+
+def _extract_speed_dials(state: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract speed dial entries from phone pre_migration_state."""
+    sd = state.get("speeddials")
+    if sd is None:
+        return []
+    if isinstance(sd, list):
+        return sd
+    if isinstance(sd, dict):
+        entries = sd.get("speeddial", [])
+        if isinstance(entries, list):
+            return entries
+        if isinstance(entries, dict):
+            return [entries]
+    return []
+
+
+class MonitoringMapper(Mapper):
+    """Map CUCM BLF entries to Webex per-person monitoring lists.
+
+    Tier 2 expansion: produces CanonicalMonitoringList objects and
+    FEATURE_APPROXIMATION decisions for overflow (>50 entries).
+    """
+
+    name = "monitoring_mapper"
+    depends_on = ["user_mapper", "line_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+
+        for phone_data in store.get_objects("phone"):
+            phone_id = phone_data["canonical_id"]
+            state = phone_data.get("pre_migration_state") or {}
+
+            blf_entries = _extract_blf_entries(state)
+            if not blf_entries:
+                continue
+
+            # Resolve owner user
+            user_refs = store.find_cross_refs(phone_id, "device_owned_by_user")
+            if not user_refs:
+                continue
+            user_id = user_refs[0]
+            user_name = user_id.split(":", 1)[-1]
+
+            # Skip if already created for this user (multi-device)
+            existing = store.get_object(f"monitoring_list:{user_name}")
+            if existing:
+                continue
+
+            # Resolve BLF targets
+            monitored_members = []
+            for entry in blf_entries:
+                if not isinstance(entry, dict):
+                    continue
+                blf_dest = entry.get("blfDest") or entry.get("blfDirn") or ""
+                label = entry.get("label") or blf_dest
+
+                # Try to resolve BLF destination to a user
+                target_id = self._resolve_blf_target(store, blf_dest)
+                if target_id:
+                    monitored_members.append({
+                        "target_canonical_id": target_id,
+                        "display_label": label,
+                    })
+                else:
+                    # Still add with unresolved marker
+                    monitored_members.append({
+                        "target_canonical_id": None,
+                        "display_label": label,
+                        "unresolved_dn": blf_dest,
+                    })
+
+            # Check overflow
+            truncated = False
+            total_count = len(monitored_members)
+            if total_count > WEBEX_MONITORING_MAX:
+                truncated = True
+                monitored_members = monitored_members[:WEBEX_MONITORING_MAX]
+
+            # Build canonical monitoring list
+            prov = extract_provenance(phone_data)
+            ml = CanonicalMonitoringList(
+                canonical_id=f"monitoring_list:{user_name}",
+                provenance=prov,
+                status=MigrationStatus.ANALYZED,
+                user_canonical_id=user_id,
+                monitored_members=monitored_members,
+            )
+            store.upsert_object(ml)
+            result.objects_created += 1
+
+            # Write cross-refs
+            store.add_cross_ref(user_id, ml.canonical_id, "user_has_monitoring_list")
+            for member in monitored_members:
+                target = member.get("target_canonical_id")
+                if target:
+                    store.add_cross_ref(ml.canonical_id, target, "monitoring_watches")
+
+            # Decision: unresolved BLF targets
+            unresolved = [m for m in monitored_members if m.get("target_canonical_id") is None]
+            if unresolved:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.MISSING_DATA,
+                    severity="LOW",
+                    summary=(
+                        f"User '{user_name}' has {len(unresolved)} BLF "
+                        f"target(s) that cannot be resolved to a Webex user"
+                    ),
+                    context={
+                        "user_id": user_id,
+                        "unresolved_dns": [m.get("unresolved_dn", "") for m in unresolved],
+                        "total_blf_entries": total_count,
+                    },
+                    options=[
+                        accept_option("Skip unresolved entries — exclude from monitoring list"),
+                        skip_option("Skip entire monitoring list migration for this user"),
+                    ],
+                    affected_objects=[user_id, ml.canonical_id],
+                )
+                result.decisions.append(decision)
+
+            # Decision: overflow
+            if truncated:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FEATURE_APPROXIMATION,
+                    severity="MEDIUM",
+                    summary=(
+                        f"User '{user_name}' has {total_count} BLF entries, "
+                        f"exceeding Webex monitoring list max of {WEBEX_MONITORING_MAX}"
+                    ),
+                    context={
+                        "user_id": user_id,
+                        "total_blf_entries": total_count,
+                        "max_allowed": WEBEX_MONITORING_MAX,
+                        "truncated_count": total_count - WEBEX_MONITORING_MAX,
+                    },
+                    options=[
+                        accept_option(f"Truncate to first {WEBEX_MONITORING_MAX} entries"),
+                        skip_option("Skip monitoring list migration for this user"),
+                    ],
+                    affected_objects=[user_id, ml.canonical_id],
+                )
+                result.decisions.append(decision)
+
+        return result
+
+    def _resolve_blf_target(self, store: MigrationStore, dn: str) -> str | None:
+        """Try to resolve a BLF DN to a user canonical_id via line cross-refs."""
+        if not dn:
+            return None
+        # Look for a line object matching this DN
+        for line_data in store.get_objects("line"):
+            line_state = line_data.get("pre_migration_state") or {}
+            line_ext = (
+                line_data.get("extension")
+                or line_state.get("extension")
+                or line_state.get("pattern")
+            )
+            if line_ext == dn:
+                # Found the line — now find its owner via cross-ref
+                line_id = line_data["canonical_id"]
+                user_refs = store.find_cross_refs(line_id, "line_assigned_to_user")
+                if user_refs:
+                    return user_refs[0]
+        return None

wxcli/migration/transform/mappers/receptionist_mapper.py

@@ -0,0 +1,245 @@
+"""ReceptionistMapper — detect CUCM receptionist users from phone layout signals.
+
+Scores each phone owner for receptionist likelihood using 4 signals:
+  1. BLF count (10+ = 2pts, 20+ = 3pts)
+  2. KEM presence (2pts)
+  3. Template name keywords (2pts)
+  4. Main number assignment (1pt)
+
+Users scoring >= 3 produce a CanonicalReceptionistConfig object. The mapper
+reads the existing MonitoringMapper output to populate monitored_members and
+DeviceLayoutMapper output to detect KEM presence.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalReceptionistConfig,
+    MapperResult,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    extract_provenance,
+)
+
+logger = logging.getLogger(__name__)
+
+RECEPTIONIST_THRESHOLD = 3
+
+_TEMPLATE_KEYWORDS = ("attendant", "reception", "lobby", "operator", "front desk")
+
+
+def _extract_blf_entries(state: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract BLF entries from phone pre_migration_state."""
+    blf = state.get("busyLampFields")
+    if blf is None:
+        return []
+    if isinstance(blf, list):
+        return blf
+    if isinstance(blf, dict):
+        entries = blf.get("busyLampField", [])
+        if isinstance(entries, list):
+            return entries
+        if isinstance(entries, dict):
+            return [entries]
+    return []
+
+
+class ReceptionistMapper(Mapper):
+    """Detect CUCM receptionist users and produce CanonicalReceptionistConfig."""
+
+    name = "receptionist_mapper"
+    depends_on = [
+        "monitoring_mapper",
+        "device_layout_mapper",
+        "location_mapper",
+        "line_mapper",
+        "user_mapper",
+    ]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+        seen_users: set[str] = set()
+
+        for phone_data in store.get_objects("phone"):
+            phone_id = phone_data["canonical_id"]
+            state = phone_data.get("pre_migration_state") or {}
+
+            # Resolve owner
+            user_refs = store.find_cross_refs(phone_id, "device_owned_by_user")
+            if not user_refs:
+                continue
+            user_id = user_refs[0]
+            user_name = user_id.split(":", 1)[-1]
+
+            # Skip duplicate (multi-device)
+            if user_name in seen_users:
+                continue
+            seen_users.add(user_name)
+
+            # Score receptionist likelihood
+            score, reasons = self._score(store, user_id, phone_id, state)
+            if score < RECEPTIONIST_THRESHOLD:
+                continue
+
+            blf_entries = _extract_blf_entries(state)
+            blf_count = len(blf_entries)
+
+            # Get KEM info from device layout
+            phone_name = phone_id.split(":", 1)[-1]
+            layout = store.get_object(f"device_layout:{phone_name}")
+            layout_data = layout or {}
+            kem_keys = (
+                layout_data.get("resolved_kem_keys")
+                or (layout_data.get("pre_migration_state") or {}).get("resolved_kem_keys")
+                or []
+            )
+
+            # Get monitored members from existing monitoring list
+            monitored_members = self._get_monitored_members(store, user_name)
+
+            # Check main number
+            is_main = self._is_main_number_holder(store, user_id)
+
+            # Get location
+            user_obj = store.get_object(user_id)
+            user_data = user_obj or {}
+            location_cid = (
+                user_data.get("location_id")
+                or (user_data.get("pre_migration_state") or {}).get("location_id")
+                or ""
+            )
+
+            template_name = state.get("phoneTemplateName") or ""
+
+            prov = extract_provenance(phone_data)
+            config = CanonicalReceptionistConfig(
+                canonical_id=f"receptionist_config:{user_name}",
+                provenance=prov,
+                status=MigrationStatus.ANALYZED,
+                user_canonical_id=user_id,
+                location_canonical_id=location_cid,
+                blf_count=blf_count,
+                has_kem=bool(kem_keys),
+                kem_key_count=len(kem_keys),
+                template_name=template_name,
+                detection_score=score,
+                detection_reasons=reasons,
+                monitored_members=monitored_members,
+                is_main_number_holder=is_main,
+            )
+            store.upsert_object(config)
+            result.objects_created += 1
+
+            # Cross-refs
+            store.add_cross_ref(user_id, config.canonical_id, "user_has_receptionist_config")
+
+        return result
+
+    def _score(
+        self,
+        store: MigrationStore,
+        user_id: str,
+        phone_id: str,
+        state: dict[str, Any],
+    ) -> tuple[int, list[str]]:
+        """Score a phone owner for receptionist likelihood."""
+        score = 0
+        reasons: list[str] = []
+
+        # Signal 1: BLF count
+        blf_entries = _extract_blf_entries(state)
+        blf_count = len(blf_entries)
+        if blf_count >= 20:
+            score += 3
+            reasons.append(f"{blf_count} BLF entries (20+)")
+        elif blf_count >= 10:
+            score += 2
+            reasons.append(f"{blf_count} BLF entries (10+)")
+
+        # Signal 2: KEM presence (via device layout)
+        phone_name = phone_id.split(":", 1)[-1]
+        layout = store.get_object(f"device_layout:{phone_name}")
+        if layout:
+            kem_keys = (
+                layout.get("resolved_kem_keys")
+                or (layout.get("pre_migration_state") or {}).get("resolved_kem_keys")
+                or []
+            )
+            if kem_keys:
+                score += 2
+                reasons.append(f"KEM with {len(kem_keys)} keys")
+
+        # Signal 3: Template name keywords
+        # AXL returns reference fields as dicts with _value_1 + uuid keys
+        raw_template = state.get("phoneTemplateName")
+        if isinstance(raw_template, dict):
+            raw_template = raw_template.get("_value_1", "")
+        template_name = (raw_template or "").lower()
+        for keyword in _TEMPLATE_KEYWORDS:
+            if keyword in template_name:
+                score += 2
+                reasons.append(f"Template name contains '{keyword}'")
+                break
+
+        # Signal 4: Main number assignment
+        if self._is_main_number_holder(store, user_id):
+            score += 1
+            reasons.append("Holds location main number")
+
+        return score, reasons
+
+    def _is_main_number_holder(self, store: MigrationStore, user_id: str) -> bool:
+        """Check if the user holds a line matching their location's main number."""
+        loc_refs = store.find_cross_refs(user_id, "user_in_location")
+        if not loc_refs:
+            return False
+        loc_id = loc_refs[0]
+        loc_obj = store.get_object(loc_id)
+        if not loc_obj:
+            return False
+        main_number = (
+            loc_obj.get("main_number")
+            or (loc_obj.get("pre_migration_state") or {}).get("main_number")
+            or ""
+        )
+        if not main_number:
+            return False
+        # Check via user's own extension first
+        user_obj = store.get_object(user_id)
+        if user_obj:
+            user_state = user_obj.get("pre_migration_state") or {}
+            user_ext = user_state.get("extension") or ""
+            if user_ext == main_number:
+                return True
+        # Fallback: check via line cross-refs
+        for line_data in store.get_objects("line"):
+            line_state = line_data.get("pre_migration_state") or {}
+            line_ext = line_state.get("extension") or line_state.get("pattern") or ""
+            if line_ext == main_number:
+                line_id = line_data["canonical_id"]
+                user_refs = store.find_cross_refs(line_id, "line_assigned_to_user")
+                if user_id in user_refs:
+                    return True
+        return False
+
+    def _get_monitored_members(self, store: MigrationStore, user_name: str) -> list[str]:
+        """Get resolved monitored member canonical IDs from the monitoring list."""
+        ml = store.get_object(f"monitoring_list:{user_name}")
+        if not ml:
+            return []
+        members = (
+            ml.get("monitored_members")
+            or (ml.get("pre_migration_state") or {}).get("monitored_members")
+            or []
+        )
+        return [
+            m["target_canonical_id"]
+            for m in members
+            if isinstance(m, dict) and m.get("target_canonical_id")
+        ]