wxcli 1.2.0__py3-none-any.whl

wxcli/migration/cucm/extractors/voicemail.py

@@ -0,0 +1,243 @@
+"""Voicemail extractor for CUCM AXL.
+
+Pulls Voicemail Profiles and Voicemail Pilots from CUCM AXL.
+Optionally extracts per-user Unity Connection settings via CUPI.
+
+Sources:
+- 02b-cucm-extraction.md §2.6 (voicemail extraction)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+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
+from wxcli.migration.cucm.unity_connection import UnityConnectionClient
+
+logger = logging.getLogger(__name__)
+
+# ------------------------------------------------------------------
+# ReturnedTags constants
+# ------------------------------------------------------------------
+
+# Verified: listVoiceMailProfile does NOT accept voiceMailPilot.
+# Use getVoiceMailProfile for pilot reference.
+VOICEMAIL_PROFILE_LIST_RETURNED_TAGS = {
+    "name": "", "description": "", "voiceMailboxMask": "",
+}
+
+# Verified: listVoiceMailPilot CSS field is 'cssName', NOT 'callingSearchSpaceName'.
+VOICEMAIL_PILOT_LIST_RETURNED_TAGS = {
+    "dirn": "", "description": "",
+}
+
+
+class VoicemailExtractor(BaseExtractor):
+    """Extract voicemail configuration from CUCM AXL.
+
+    Covers Voicemail Profiles and Voicemail Pilots.
+    Optionally fetches per-user voicemail settings from Unity Connection
+    via the CUPI REST API when a ``unity_client`` is provided.
+
+    (from 02b §2.6)
+    """
+
+    name = "voicemail"
+
+    def __init__(
+        self,
+        connection: AXLConnection,
+        unity_client: UnityConnectionClient | None = None,
+    ) -> None:
+        super().__init__(connection)
+        self.unity_client = unity_client
+        self.results: dict[str, list[dict[str, Any]]] = {}
+
+    def extract(self) -> ExtractionResult:
+        """Run voicemail extraction (AXL profiles and pilots).
+
+        Unity Connection per-user settings are extracted separately via
+        ``extract_unity_settings()`` because the user list comes from
+        the discovery extractor.
+
+        Returns an ExtractionResult summarizing total objects and errors.
+        """
+        result = ExtractionResult(extractor=self.name)
+
+        self.results["voicemail_profiles"] = self._extract_voicemail_profiles(
+            result
+        )
+        self.results["voicemail_pilots"] = self._extract_voicemail_pilots(
+            result
+        )
+
+        # Shared/group mailboxes (Unity Connection only — skipped without client)
+        self.results["shared_mailboxes"] = self._extract_shared_mailboxes(result)
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Voicemail Profiles
+    # ------------------------------------------------------------------
+
+    def _extract_voicemail_profiles(
+        self, result: ExtractionResult
+    ) -> list[dict[str, Any]]:
+        """List all voicemail profiles, then get full detail for each.
+
+        Verified against live CUCM 15.0 (2026-03-23):
+        - listVoiceMailProfile method confirmed
+        - voiceMailPilot reference NOT returned by list — requires getVoiceMailProfile
+        """
+        profiles: list[dict[str, Any]] = []
+        try:
+            summaries = self.paginated_list(
+                "listVoiceMailProfile",
+                {"name": "%"},
+                VOICEMAIL_PROFILE_LIST_RETURNED_TAGS,
+            )
+        except Exception as exc:
+            msg = f"listVoiceMailProfile 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("getVoiceMailProfile", name=profile_name)
+            except Exception as exc:
+                logger.warning(
+                    "[%s] getVoiceMailProfile error for %s: %s",
+                    self.name, profile_name, exc,
+                )
+                profiles.append(summary)
+                continue
+            if detail is None:
+                profiles.append(summary)
+                continue
+            profiles.append(detail)
+
+        return profiles
+
+    # ------------------------------------------------------------------
+    # Voicemail Pilots
+    # ------------------------------------------------------------------
+
+    def _extract_voicemail_pilots(
+        self, result: ExtractionResult
+    ) -> list[dict[str, Any]]:
+        """List all voicemail pilots.
+
+        Verified against live CUCM 15.0 2026-03-23: search field is 'dirn'.
+        """
+        pilots: list[dict[str, Any]] = []
+        try:
+            summaries = self.paginated_list(
+                "listVoiceMailPilot",
+                {"dirn": "%"},
+                VOICEMAIL_PILOT_LIST_RETURNED_TAGS,
+            )
+            pilots.extend(summaries)
+            result.total += len(summaries)
+        except Exception as exc:
+            msg = f"listVoiceMailPilot failed: {exc}"
+            logger.error("[%s] %s", self.name, msg)
+            result.errors.append(msg)
+
+        return pilots
+
+    # ------------------------------------------------------------------
+    # Unity Connection shared mailboxes
+    # ------------------------------------------------------------------
+
+    def _extract_shared_mailboxes(
+        self, result: ExtractionResult
+    ) -> list[dict[str, Any]]:
+        """Fetch Unity Connection shared/group call handlers via CUPI.
+
+        Returns an empty list when no Unity Connection client was
+        configured. Errors are logged but do not fail discovery.
+        """
+        if self.unity_client is None:
+            logger.info(
+                "[%s] No Unity Connection client — "
+                "skipping shared mailbox extraction",
+                self.name,
+            )
+            return []
+        try:
+            mailboxes = self.unity_client.extract_shared_mailboxes()
+        except Exception as exc:
+            msg = f"Unity shared mailbox extraction failed: {exc}"
+            logger.error("[%s] %s", self.name, msg)
+            result.errors.append(msg)
+            return []
+        result.total += len(mailboxes)
+        return mailboxes
+
+    # ------------------------------------------------------------------
+    # Unity Connection per-user settings
+    # ------------------------------------------------------------------
+
+    def extract_unity_settings(
+        self, user_ids: list[str]
+    ) -> dict[str, dict[str, Any]]:
+        """Extract per-user voicemail settings from Unity Connection.
+
+        This is called separately from ``extract()`` because the user
+        list comes from the discovery extractor (02b §2.1), not from
+        this extractor.
+
+        Args:
+            user_ids: List of CUCM user IDs (aliases) to look up in
+                Unity Connection.
+
+        Returns:
+            Dict mapping CUCM user ID to their Unity Connection
+            voicemail settings. Users not found in UC are omitted.
+        """
+        if self.unity_client is None:
+            logger.info(
+                "[%s] No Unity Connection client configured — "
+                "skipping per-user VM extraction",
+                self.name,
+            )
+            return {}
+
+        settings: dict[str, dict[str, Any]] = {}
+        for user_id in user_ids:
+            try:
+                user_settings = self.unity_client.extract_user_vm_settings(
+                    user_id
+                )
+                if user_settings is not None:
+                    settings[user_id] = user_settings
+                else:
+                    logger.debug(
+                        "[%s] User %s not found in Unity Connection",
+                        self.name,
+                        user_id,
+                    )
+            except Exception as exc:
+                logger.warning(
+                    "[%s] Unity extraction failed for user %s: %s",
+                    self.name,
+                    user_id,
+                    exc,
+                )
+
+        logger.info(
+            "[%s] Extracted Unity settings for %d/%d users",
+            self.name,
+            len(settings),
+            len(user_ids),
+        )
+        return settings

wxcli/migration/cucm/extractors/workspaces.py

@@ -0,0 +1,88 @@
+"""Workspace (common-area phone) classifier post-processor.
+
+Identifies phones that are common-area devices suitable for Webex Calling
+workspace provisioning. Runs as a pass 2 helper against already-extracted
+phone data -- does NOT make AXL calls.
+
+Sources:
+- 02b-cucm-extraction.md S2.8 (workspace classification)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.cucm.extractors.helpers import ref_value
+
+logger = logging.getLogger(__name__)
+
+
+def is_common_area_device(phone_raw: dict[str, Any]) -> bool:
+    """Determine if a phone dict represents a common-area device.
+
+    Classification logic (from 02b S2.8):
+    - Must have no ownerUserName (unowned device).
+    - Must have device class 'Phone' (excludes CTI ports, route points, etc.).
+
+    Args:
+        phone_raw: Raw phone dict from DeviceExtractor.
+
+    Returns:
+        True if the phone is a common-area device.
+    """
+    # ownerUserName may be a reference dict {'_value_1': 'user', 'uuid': '...'}
+    # or a plain string. Use ref_value to handle both.
+    owner = ref_value(phone_raw.get("ownerUserName"))
+    if owner is not None:
+        return False
+
+    device_class = phone_raw.get("class", "")
+    if device_class not in ("Phone",):
+        return False
+
+    return True
+
+
+class WorkspaceClassifier:
+    """Classify common-area phones from DeviceExtractor phone data.
+
+    This is a pass 2 helper, NOT a BaseExtractor subclass. It operates
+    entirely on in-memory phone dicts and returns the subset that qualify
+    as common-area devices.
+
+    (from 02b S2.8)
+    """
+
+    def __init__(self, phones: list[dict]) -> None:
+        self.phones = phones
+
+    def classify(self) -> list[dict[str, Any]]:
+        """Return the subset of phones that are common-area devices.
+
+        Returns the raw phone dicts unchanged -- transformation is the
+        normalizer's job.
+
+        Note: ATA devices (name starts with 'ATA') pass the classification
+        since they are technically common-area, but may be incompatible with
+        Webex Calling workspaces. Downstream stages should flag these.
+
+        Returns:
+            List of raw phone dicts that are common-area devices.
+        """
+        results = [phone for phone in self.phones if is_common_area_device(phone)]
+
+        ata_count = sum(1 for p in results if p.get("name", "").startswith("ATA"))
+        if ata_count:
+            logger.warning(
+                "Classified %d ATA device(s) as common-area -- these may be "
+                "incompatible with Webex Calling workspaces",
+                ata_count,
+            )
+
+        logger.info(
+            "Workspace classification complete: %d of %d phones are common-area",
+            len(results),
+            len(self.phones),
+        )
+        return results

wxcli/migration/cucm/unity_connection.py

@@ -0,0 +1,304 @@
+"""CUPI REST client for Cisco Unity Connection.
+
+Retrieves per-user voicemail settings that are not available via CUCM AXL.
+
+Sources:
+- 02b-cucm-extraction.md §2.6 (CUPI connection setup, endpoints, field mapping)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import requests
+from requests.auth import HTTPBasicAuth
+
+logger = logging.getLogger(__name__)
+
+
+class UnityConnectionError(Exception):
+    """Raised when the Unity Connection client cannot connect or authenticate."""
+
+
+class UnityConnectionClient:
+    """CUPI REST client for Unity Connection per-user voicemail settings.
+
+    (from 02b §2.6: CUPI connection setup)
+
+    Args:
+        host: Unity Connection hostname or IP.
+        username: Admin username.
+        password: Admin password.
+        verify_ssl: Whether to verify SSL certificates (default False).
+        timeout: Request timeout in seconds (default 30).
+    """
+
+    def __init__(
+        self,
+        host: str,
+        username: str,
+        password: str,
+        verify_ssl: bool = False,
+        timeout: int = 30,
+    ) -> None:
+        self.base_url = f"https://{host}/vmrest"
+        self.session = requests.Session()
+        self.session.auth = HTTPBasicAuth(username, password)
+        self.session.verify = verify_ssl
+        self.session.timeout = timeout
+        self.session.headers.update(
+            {
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            }
+        )
+
+    # ------------------------------------------------------------------
+    # User lookup
+    # ------------------------------------------------------------------
+
+    def get_user_by_alias(self, alias: str) -> dict[str, Any] | None:
+        """Look up UC user by CUCM userid/alias.
+
+        (from 02b §2.6: CUPI user lookup)
+
+        """
+        try:
+            resp = self.session.get(
+                f"{self.base_url}/users",
+                params={"query": f"(alias is {alias})"},
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                users = data.get("User", [])
+                if isinstance(users, dict):
+                    users = [users]
+                return users[0] if users else None
+        except Exception as exc:
+            logger.warning("CUPI user lookup failed for %s: %s", alias, exc)
+        return None
+
+    # ------------------------------------------------------------------
+    # Per-user voicemail settings
+    # ------------------------------------------------------------------
+
+    def get_notification_devices(self, object_id: str) -> list[dict[str, Any]]:
+        """Get notification devices for a user.
+
+        (from 02b §2.6: notifications.enabled, notifications.destination)
+
+        """
+        return self._get_list(
+            f"/users/{object_id}/notificationdevices",
+            "NotificationDevice",
+        )
+
+    def get_call_handler(self, handler_id: str) -> dict[str, Any] | None:
+        """Get call handler (greeting/transfer rules).
+
+        (from 02b §2.6: sendAllCalls, sendBusyCalls, sendUnansweredCalls)
+
+        """
+        return self._get(f"/handlers/callhandlers/{handler_id}")
+
+    def get_message_store_settings(
+        self, object_id: str
+    ) -> dict[str, Any] | None:
+        """Get message store settings for a user.
+
+        (from 02b §2.6: storageType, mwiEnabled, externalEmail)
+
+        """
+        return self._get(f"/users/{object_id}/messagestoresettings")
+
+    def get_transfer_rule_zero(self, object_id: str) -> dict[str, Any] | None:
+        """Get transfer-to-zero rule for a user.
+
+        (from 02b §2.6: transferToNumber settings)
+
+        """
+        return self._get(f"/users/{object_id}/transferrules/transferzero")
+
+    def get_fax_settings(self, object_id: str) -> dict[str, Any] | None:
+        """Get fax server settings for a user.
+
+        (from 02b §2.6: fax message settings)
+
+        """
+        return self._get(f"/users/{object_id}/faxserversettings")
+
+    # ------------------------------------------------------------------
+    # Aggregate extraction
+    # ------------------------------------------------------------------
+
+    def extract_user_vm_settings(
+        self, cucm_userid: str
+    ) -> dict[str, Any] | None:
+        """Extract all voicemail settings for one user.
+
+        Looks up the user by alias, then fetches all per-user settings.
+        Returns a consolidated dict, or None if user not found in UC.
+
+        (from 02b §2.6: extraction flow steps 3-4)
+        """
+        uc_user = self.get_user_by_alias(cucm_userid)
+        if uc_user is None:
+            return None
+
+        object_id = uc_user.get("ObjectId", "")
+        call_handler_id = uc_user.get("CallhandlerObjectId", "")
+
+        result: dict[str, Any] = {
+            "uc_object_id": object_id,
+            "vm_enabled": True,
+            "call_handler_id": call_handler_id,
+        }
+
+        # Notification devices
+        notif_devices = self.get_notification_devices(object_id)
+        result["notification_enabled"] = any(
+            d.get("Enabled", False) for d in notif_devices
+        )
+        email_devices = [
+            d for d in notif_devices if d.get("SmtpAddress")
+        ]
+        result["notification_destination"] = (
+            email_devices[0].get("SmtpAddress") if email_devices else None
+        )
+
+        # Call handler transfer rules
+        if call_handler_id:
+            handler = self.get_call_handler(call_handler_id)
+            if handler:
+                result["send_all_calls"] = _to_bool(
+                    handler.get("PlayTransferPrompt")
+                )
+                result["send_busy_calls"] = _to_bool(
+                    handler.get("SendBusyCalls")
+                )
+                result["send_unanswered_calls"] = _to_bool(
+                    handler.get("SendUnansweredCalls")
+                )
+                result["unanswered_rings"] = handler.get("RingsToWait")
+                result["busy_greeting_type"] = (
+                    "CUSTOM"
+                    if handler.get("PlayPostGreetingRecording")
+                    else "DEFAULT"
+                )
+
+        # Message store settings
+        msg_store = self.get_message_store_settings(object_id)
+        if msg_store:
+            result["storage_type"] = msg_store.get("StorageType", "INTERNAL")
+            result["mwi_enabled"] = _to_bool(msg_store.get("MwiEnabled"))
+            result["external_email"] = msg_store.get("ExternalEmail")
+            result["email_copy_enabled"] = _to_bool(
+                msg_store.get("SendCopyToEmail")
+            )
+
+        # Transfer to zero
+        t_zero = self.get_transfer_rule_zero(object_id)
+        if t_zero:
+            result["transfer_to_zero_enabled"] = _to_bool(
+                t_zero.get("Enabled")
+            )
+            result["transfer_to_zero_destination"] = t_zero.get(
+                "Extension"
+            ) or t_zero.get("PhoneNumber")
+
+        # Fax settings
+        fax = self.get_fax_settings(object_id)
+        if fax:
+            result["fax_enabled"] = _to_bool(fax.get("Enabled"))
+            result["fax_number"] = fax.get("FaxNumber")
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Shared/group mailbox discovery
+    # ------------------------------------------------------------------
+
+    def extract_shared_mailboxes(self) -> list[dict[str, Any]]:
+        """Extract Unity Connection shared/group call handlers.
+
+        Queries /vmrest/handlers/callhandlers and filters to non-primary
+        handlers (IsPrimary=false). Primary handlers are per-user mailboxes
+        already covered by extract_user_vm_settings. Non-primary handlers
+        are shared/group mailboxes (sales@, support@, etc.).
+
+        Returns an empty list on error or when CUPI is unreachable —
+        callers should treat absence as "Unity Connection not available"
+        rather than "no shared mailboxes exist".
+        """
+        try:
+            resp = self.session.get(
+                f"{self.base_url}/handlers/callhandlers",
+            )
+        except Exception as exc:
+            logger.warning("CUPI shared-mailbox query failed: %s", exc)
+            return []
+
+        if resp.status_code != 200:
+            logger.warning(
+                "CUPI shared-mailbox query returned %s", resp.status_code
+            )
+            return []
+
+        data = resp.json() if callable(getattr(resp, "json", None)) else {}
+        handlers = data.get("Callhandler", [])
+        # CUPI returns a bare dict when exactly one handler exists.
+        if isinstance(handlers, dict):
+            handlers = [handlers]
+
+        # Filter out primary (per-user) handlers — we only want shared ones.
+        shared: list[dict[str, Any]] = []
+        for h in handlers:
+            if not isinstance(h, dict):
+                continue
+            is_primary = str(h.get("IsPrimary", "false")).lower() == "true"
+            if is_primary:
+                continue
+            shared.append(h)
+
+        logger.info(
+            "Extracted %d Unity Connection shared mailbox(es)", len(shared)
+        )
+        return shared
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str) -> dict[str, Any] | None:
+        """GET a single CUPI resource."""
+        try:
+            resp = self.session.get(f"{self.base_url}{path}")
+            if resp.status_code == 200:
+                return resp.json()
+        except Exception as exc:
+            logger.warning("CUPI GET %s failed: %s", path, exc)
+        return None
+
+    def _get_list(
+        self, path: str, key: str
+    ) -> list[dict[str, Any]]:
+        """GET a CUPI collection resource."""
+        data = self._get(path)
+        if data is None:
+            return []
+        items = data.get(key, [])
+        if isinstance(items, dict):
+            items = [items]
+        return items
+
+
+def _to_bool(value: Any) -> bool | None:
+    """Convert CUPI response values to bool."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.lower() in ("true", "1", "yes")
+    return bool(value)