wxcli 1.2.0__py3-none-any.whl

wxcli/migration/cucm/extractors/base.py

@@ -0,0 +1,90 @@
+"""Base extractor class and ExtractionResult.
+
+All AXL extractors (§2.1-2.6 of 02b) inherit from BaseExtractor.
+
+Sources:
+- 02b-cucm-extraction.md §3 (base extractor class, ExtractionResult)
+- 02b-cucm-extraction.md §1 (error handling strategy)
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from wxcli.migration.cucm.connection import AXLConnection
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ExtractionResult:
+    """Summary of one extractor's run.
+
+    (from 02b §3)
+    """
+
+    extractor: str
+    total: int = 0
+    failed: int = 0
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def success_count(self) -> int:
+        return self.total - self.failed
+
+
+class ExtractionError(Exception):
+    """Raised when an extractor encounters an unrecoverable error.
+
+    (from 02b §1: error handling)
+    """
+
+    def __init__(self, extractor: str, method: str, message: str) -> None:
+        self.extractor = extractor
+        self.method = method
+        super().__init__(f"[{extractor}] {method}: {message}")
+
+
+class BaseExtractor(ABC):
+    """Base class for all CUCM AXL extractors.
+
+    (from 02b §3)
+    """
+
+    name: str = ""
+    page_size: int = 200  # Default AXL page size (from cucm-wxc-migration.md line 307)
+
+    def __init__(self, connection: AXLConnection) -> None:
+        self.conn = connection
+
+    @abstractmethod
+    def extract(self) -> ExtractionResult:
+        """Run extraction. Returns count of objects extracted and any errors."""
+        ...
+
+    def paginated_list(
+        self,
+        method_name: str,
+        search_criteria: dict[str, str],
+        returned_tags: dict[str, str],
+        page_size: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Generic paginated AXL list operation.
+
+        Uses first/skip pagination (from cucm-wxc-migration.md line 307).
+        (from 02b §3)
+        """
+        effective_page_size = page_size or self.page_size
+        return self.conn.paginated_list(
+            method_name, search_criteria, returned_tags, effective_page_size
+        )
+
+    def get_detail(self, method_name: str, **kwargs: Any) -> dict[str, Any] | None:
+        """Single-object get operation (e.g. getPhone by name or UUID).
+
+        (from 02b §3)
+        """
+        return self.conn.get_detail(method_name, **kwargs)

wxcli/migration/cucm/extractors/device_profiles.py

@@ -0,0 +1,98 @@
+"""Device Profile extractor for CUCM AXL.
+
+Pulls Extension Mobility Device Profiles from CUCM.
+
+Sources:
+- tier2-enterprise-expansion.md §5 (Extension Mobility extraction)
+- AXL WSDL: listDeviceProfile / getDeviceProfile
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.cucm.extractors.base import BaseExtractor, ExtractionResult
+from wxcli.migration.cucm.extractors.helpers import to_list
+
+logger = logging.getLogger(__name__)
+
+DEVICE_PROFILE_LIST_RETURNED_TAGS = {
+    "name": "",
+    "product": "",
+    "protocol": "",
+    "class": "",
+    "phoneTemplateName": "",
+}
+
+
+class DeviceProfileExtractor(BaseExtractor):
+    """Extract Extension Mobility Device Profiles from CUCM AXL.
+
+    Device Profiles are virtual phone configurations that users log into.
+    When a user logs into a physical phone, the device profile's lines/settings
+    replace the phone's default config.
+
+    (from tier2-enterprise-expansion.md §5)
+    """
+
+    name = "device_profiles"
+
+    def __init__(self, connection) -> None:
+        super().__init__(connection)
+        self.results: dict[str, list[dict[str, Any]]] = {}
+
+    def extract(self) -> ExtractionResult:
+        result = ExtractionResult(extractor=self.name)
+        self.results["device_profiles"] = self._extract_device_profiles(result)
+        return result
+
+    def _extract_device_profiles(
+        self, result: ExtractionResult
+    ) -> list[dict[str, Any]]:
+        """List all device profiles, then get full detail for each."""
+        profiles: list[dict[str, Any]] = []
+        try:
+            summaries = self.paginated_list(
+                "listDeviceProfile",
+                {"name": "%"},
+                DEVICE_PROFILE_LIST_RETURNED_TAGS,
+            )
+        except Exception as exc:
+            msg = f"listDeviceProfile failed: {exc}"
+            logger.error("[%s] %s", self.name, msg)
+            result.errors.append(msg)
+            return profiles
+
+        for summary in summaries:
+            result.total += 1
+            profile_name = summary.get("name", "")
+            if not profile_name:
+                result.failed += 1
+                continue
+            try:
+                detail = self.get_detail("getDeviceProfile", name=profile_name)
+            except Exception as exc:
+                logger.warning(
+                    "[%s] getDeviceProfile error for %s: %s",
+                    self.name, profile_name, exc,
+                )
+                profiles.append(summary)
+                continue
+            if detail is None:
+                profiles.append(summary)
+                continue
+
+            # Normalize lines
+            lines_raw = detail.get("lines") or {}
+            detail["lines"] = to_list(lines_raw, "line")
+
+            # Count speed dials and BLF entries
+            sd_raw = detail.get("speeddials") or {}
+            detail["speeddials"] = to_list(sd_raw, "speeddial")
+            blf_raw = detail.get("busyLampFields") or {}
+            detail["busyLampFields"] = to_list(blf_raw, "busyLampField")
+
+            profiles.append(detail)
+
+        return profiles

wxcli/migration/cucm/extractors/devices.py

@@ -0,0 +1,193 @@
+"""Device extractor — phones with line appearances.
+
+Two-step extraction: listPhone discovers devices, then getPhone fetches
+full detail including nested line/speed-dial data per device.
+
+Sources:
+- 02b-cucm-extraction.md §2.3 (device extraction, line appearances)
+- 02b-cucm-extraction.md §3 (base extractor, pagination)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from rich.console import Console
+
+from wxcli.migration.cucm.connection import AXLConnection
+from wxcli.migration.cucm.extractors.base import BaseExtractor, ExtractionResult
+from wxcli.migration.cucm.extractors.helpers import ref_value, to_list
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+# Step 1: listPhone — lightweight discovery
+PHONE_LIST_RETURNED_TAGS = {
+    'name': '', 'model': '', 'ownerUserName': '', 'devicePoolName': '',
+    'protocol': '', 'description': '',
+}
+
+# Step 2: getPhone — full detail per device
+PHONE_GET_RETURNED_TAGS = {
+    'name': '', 'model': '', 'description': '', 'ownerUserName': '',
+    'devicePoolName': '', 'protocol': '', 'callingSearchSpaceName': '',
+    'phoneTemplateName': '', 'softkeyTemplateName': '', 'deviceMobilityMode': '',
+    'product': '', 'class': '', 'lines': '',
+    'speeddials': '', 'busyLampFields': '',
+    # Device settings fields (for DeviceSettingsMapper)
+    'commonPhoneConfigName': '', 'productSpecificConfiguration': '',
+    'userLocale': '', 'networkLocale': '',
+    'dndOption': '', 'dndStatus': '', 'enableExtensionMobility': '',
+}
+
+
+class DeviceExtractor(BaseExtractor):
+    """Extract phones and their line appearances from CUCM.
+
+    (from 02b §2.3)
+    """
+
+    name = "devices"
+
+    def __init__(self, connection: AXLConnection) -> None:
+        super().__init__(connection)
+        self.results: dict[str, list[dict[str, Any]]] = {}
+
+    def extract(self) -> ExtractionResult:
+        """Run two-step phone extraction.
+
+        Step 1: listPhone with pagination to discover all devices.
+        Step 2: getPhone per device for full line appearance data.
+        """
+        result = ExtractionResult(extractor=self.name)
+
+        # Step 1: discover all phones
+        logger.info("[%s] Listing phones...", self.name)
+        try:
+            phone_summaries = self.paginated_list(
+                method_name="listPhone",
+                search_criteria={"name": "%"},
+                returned_tags=PHONE_LIST_RETURNED_TAGS,
+            )
+        except Exception as exc:
+            msg = f"listPhone failed: {exc}"
+            logger.error("[%s] %s", self.name, msg)
+            result.errors.append(msg)
+            self.results["phones"] = []
+            return result
+        logger.info("[%s] Found %d phones", self.name, len(phone_summaries))
+        result.total = len(phone_summaries)
+
+        # Step 2: get full detail per phone
+        phones: list[dict[str, Any]] = []
+        total = len(phone_summaries)
+        for i, summary in enumerate(phone_summaries, 1):
+            if i % 200 == 0:
+                console.print(f"    phones: {i}/{total}...")
+            phone_name = ref_value(summary.get("name")) or summary.get("name")
+            if not phone_name:
+                result.failed += 1
+                result.errors.append("Phone with no name in listPhone result")
+                continue
+
+            detail = self._get_phone_detail(phone_name)
+            if detail is None:
+                result.failed += 1
+                result.errors.append(f"getPhone failed for {phone_name}")
+                continue
+
+            phones.append(detail)
+
+        self.results["phones"] = phones
+        logger.info(
+            "[%s] Extracted %d/%d phones (%d failed)",
+            self.name, result.success_count, result.total, result.failed,
+        )
+        return result
+
+    def _get_phone_detail(self, phone_name: str) -> dict[str, Any] | None:
+        """Fetch full phone detail and normalize line appearances.
+
+        Handles edge cases:
+        - lines may be empty dict or None
+        - lines.line may be a single dict, not a list
+        - Speed dials are interleaved with lines — filter to entries with ``dirn``
+        """
+        try:
+            detail = self.get_detail("getPhone", name=phone_name)
+        except Exception as exc:
+            logger.warning("[%s] getPhone error for %s: %s", self.name, phone_name, exc)
+            return None
+
+        if detail is None:
+            return None
+
+        # Normalize lines — may be None, empty dict, or populated
+        raw_lines = detail.get("lines")
+        line_entries = to_list(raw_lines, "line")
+
+        # Filter: only entries with a ``dirn`` key are real line appearances.
+        # Speed dial entries are interleaved but lack ``dirn``.
+        line_appearances = []
+        for entry in line_entries:
+            if not isinstance(entry, dict):
+                continue
+            if entry.get("dirn") is not None:
+                line_appearances.append(entry)
+
+        detail["lines"] = line_appearances
+
+        # Enrich each line with call forwarding settings from getLine.
+        # getPhone line entries do NOT include callForwardAll/Busy/NoAnswer —
+        # those are only on the Line AXL object. The voicemail_mapper needs
+        # these to determine sendAllCalls/sendBusyCalls/sendUnansweredCalls.
+        # Verified against live CUCM 15.0 (2026-03-23): getLine response
+        # includes callForwardAll, callForwardBusy, callForwardNoAnswer with
+        # forwardToVoiceMail, destination, and duration fields.
+        for line_entry in line_appearances:
+            dirn = line_entry.get("dirn")
+            if not isinstance(dirn, dict):
+                continue
+            pattern = dirn.get("pattern")
+            partition = ref_value(dirn.get("routePartitionName"))
+            if not pattern:
+                continue
+            self._enrich_line_with_forwarding(line_entry, pattern, partition)
+
+        return detail
+
+    def _enrich_line_with_forwarding(
+        self, line_entry: dict[str, Any], pattern: str, partition: str | None,
+    ) -> None:
+        """Fetch getLine for a DN and merge call forwarding settings into the line entry."""
+        try:
+            kwargs: dict[str, Any] = {"pattern": pattern}
+            if partition:
+                kwargs["routePartitionName"] = partition
+            line_detail = self.get_detail("getLine", **kwargs)
+        except Exception as exc:
+            logger.debug(
+                "[%s] getLine(%s/%s) failed: %s", self.name, pattern, partition, exc,
+            )
+            return
+        if line_detail is None:
+            return
+        # Merge forwarding fields into the line entry
+        for fwd_key in (
+            "callForwardAll", "callForwardBusy", "callForwardBusyInt",
+            "callForwardNoAnswer", "callForwardNoAnswerInt",
+            "callForwardNoCoverage", "callForwardNoCoverageInt",
+            "callForwardNotRegistered", "callForwardNotRegisteredInt",
+            "callForwardOnFailure",
+        ):
+            if fwd_key in line_detail:
+                line_entry[fwd_key] = line_detail[fwd_key]
+        # Also grab voiceMailProfileName if present on the Line
+        if "voiceMailProfileName" in line_detail:
+            line_entry["voiceMailProfileName"] = line_detail["voiceMailProfileName"]
+        # Grab recording fields if present on the Line
+        if "recordingProfileName" in line_detail:
+            line_entry["recordingProfileName"] = line_detail["recordingProfileName"]
+        if "recordingFlag" in line_detail:
+            line_entry["recordingFlag"] = line_detail["recordingFlag"]

wxcli/migration/cucm/extractors/e911.py

@@ -0,0 +1,103 @@
+"""E911 extractor for CUCM AXL.
+
+Pulls ELIN groups and geographic locations from CUCM for E911 advisory.
+
+Sources:
+- tier2-enterprise-expansion.md §6 (E911/ELIN extraction)
+- AXL WSDL: listElinGroup / getElinGroup, listGeoLocation / getGeoLocation
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.cucm.extractors.base import BaseExtractor, ExtractionResult
+
+logger = logging.getLogger(__name__)
+
+ELIN_GROUP_LIST_RETURNED_TAGS = {
+    "name": "",
+    "elinNumbers": "",
+}
+
+GEO_LOCATION_LIST_RETURNED_TAGS = {
+    "name": "",
+    "description": "",
+    "country": "",
+}
+
+
+class E911Extractor(BaseExtractor):
+    """Extract E911 ELIN groups and geographic locations from CUCM AXL.
+
+    ELIN groups define E.164 numbers reserved for E911 callback.
+    Geographic locations define E911 routing by country/region.
+    CER (Cisco Emergency Responder) is out of scope — it has its own DB.
+
+    (from tier2-enterprise-expansion.md §6)
+    """
+
+    name = "e911"
+
+    def __init__(self, connection) -> None:
+        super().__init__(connection)
+        self.results: dict[str, list[dict[str, Any]]] = {}
+
+    def extract(self) -> ExtractionResult:
+        result = ExtractionResult(extractor=self.name)
+        self.results["elin_groups"] = self._extract_elin_groups(result)
+        self.results["geo_locations"] = self._extract_geo_locations(result)
+        return result
+
+    def _extract_elin_groups(self, result: ExtractionResult) -> list[dict[str, Any]]:
+        """List all ELIN groups."""
+        groups: list[dict[str, Any]] = []
+        try:
+            summaries = self.paginated_list(
+                "listElinGroup",
+                {"name": "%"},
+                ELIN_GROUP_LIST_RETURNED_TAGS,
+            )
+        except Exception as exc:
+            msg = f"listElinGroup failed: {exc}"
+            logger.error("[%s] %s", self.name, msg)
+            result.errors.append(msg)
+            return groups
+
+        for summary in summaries:
+            result.total += 1
+            name = summary.get("name", "")
+            if not name:
+                result.failed += 1
+                continue
+            try:
+                detail = self.get_detail("getElinGroup", name=name)
+            except Exception as exc:
+                logger.warning("[%s] getElinGroup error for %s: %s", self.name, name, exc)
+                groups.append(summary)
+                continue
+            if detail is None:
+                groups.append(summary)
+                continue
+            groups.append({**summary, **detail})
+
+        return groups
+
+    def _extract_geo_locations(self, result: ExtractionResult) -> list[dict[str, Any]]:
+        """List all geographic locations."""
+        locations: list[dict[str, Any]] = []
+        try:
+            summaries = self.paginated_list(
+                "listGeoLocation",
+                {"name": "%"},
+                GEO_LOCATION_LIST_RETURNED_TAGS,
+            )
+            locations.extend(summaries)
+            result.total += len(summaries)
+        except Exception as exc:
+            msg = f"listGeoLocation failed: {exc}"
+            logger.error("[%s] %s", self.name, msg)
+            result.errors.append(msg)
+
+        return locations