wxcli 1.2.0__py3-none-any.whl

wxcli/migration/cucm/CLAUDE.md

@@ -0,0 +1,74 @@
+# cucm/ — CUCM Extraction Layer (Phase 03)
+
+Connects to CUCM via AXL SOAP and extracts raw configuration into the SQLite store. Output is `DiscoveryResult.raw_data` — a dict of dicts of lists that feeds directly into `transform/pipeline.py:normalize_discovery()`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `connection.py` | `AXLConnection` — zeep SOAP client with certificate handling and retry |
+| `discovery.py` | `run_discovery(store, config)` — orchestrates all extractors in order, writes results to store |
+| `unity_connection.py` | `UnityConnectionClient` — REST client for Unity Connection per-user VM settings |
+| `extractors/base.py` | `BaseExtractor` ABC + `ExtractionResult` dataclass |
+| `extractors/devices.py` | Phones (SEP) and their line appearances |
+| `extractors/features.py` | Hunt pilots/lists/groups, call park, pickup groups, CTI route points, paging groups |
+| `extractors/locations.py` | CUCM locations, device pools, datetime groups |
+| `extractors/routing.py` | Gateways, SIP trunks, route groups, route lists, route patterns, CSS, partitions |
+| `extractors/shared_lines.py` | Shared line detection (post-normalization, not an AXL extractor) |
+| `extractors/templates.py` | Button templates + softkey templates (via SQL — AXL doesn't expose softkey template list) |
+| `extractors/users.py` | EndUsers, lines (DNs), voicemail profiles |
+| `extractors/voicemail.py` | Unity Connection voicemail pilot, voicemail profiles |
+| `extractors/helpers.py` | `to_list()`, zeep response normalization helpers |
+| `extractors/workspaces.py` | Common-area phone workspace classification (post-normalization) |
+| `extractors/informational.py` | Tier 3: 20 informational object types (regions, SRST, MRG, app users, etc.) — report only |
+| `extractors/tier4.py` | Tier 4 feature gaps: recording profiles, remote destinations, transformation patterns, EM device profiles |
+| `extractors/remote_destinations.py` | Remote destinations for SNR |
+| `extractors/e911.py` | ELIN groups, geo locations |
+| `extractors/device_profiles.py` | Extension Mobility device profiles |
+| `extractors/moh.py` | Music on Hold sources |
+| `extractors/announcements.py` | Announcements / media resources |
+
+## Extraction Order
+
+```
+locations → users → devices → features → routing → templates → voicemail → informational → tier4 → remote_destinations → e911 → device_profiles → moh → announcements
+```
+
+Extractors are independent at extraction time — the order is a documentation convention, not a dependency constraint. All raw dicts go into `raw_data` keyed by extractor name.
+
+## raw_data Structure
+
+`raw_data` is a `dict[str, dict[str, list]]`:
+- Top key = extractor group (`"devices"`, `"users"`, `"features"`, etc.)
+- Inner key = object type (`"phones"`, `"users"`, `"button_templates"`, etc.)
+- Value = list of raw CUCM dicts (as returned by zeep, pre-normalized by `to_list()`)
+
+`normalize_discovery()` in `transform/pipeline.py` consumes `raw_data` via `RAW_DATA_MAPPING`.
+
+**Executive/assistant data** is extracted via SQL (no AXL list/get operations exist):
+- `raw_data["features"]["executive_assistant_pairs"]` — pair dicts from `executiveassistant` table join
+- `raw_data["features"]["executive_settings"]` — user service subscription dicts from `endusersubscribedservice` join
+
+**Intercept candidates** are extracted via SQL heuristics:
+- `raw_data["tier4"]["intercept_candidates"]` — heuristically-detected intercept-like configurations (blocked partition DNs, CFA-to-voicemail with no registered device). Uses two SQL queries for partition name pattern matching and call forwarding state detection.
+
+**Standalone extractors** (wired into discovery.py alongside the 9 original extractors):
+- `raw_data["remote_destinations"]["remote_destinations"]` — SNR remote destinations
+- `raw_data["e911"]["elin_groups"]` — ELIN groups for E911
+- `raw_data["e911"]["geo_locations"]` — geo locations for E911
+- `raw_data["device_profiles"]["device_profiles"]` — Extension Mobility device profiles
+- `raw_data["moh"]["moh_sources"]` — Music on Hold audio sources
+- `raw_data["announcements"]["announcements"]` — announcement / media resources
+
+## Key Gotchas
+
+- **Softkey templates require SQL.** `addSoftkeyTemplate`/`listSoftkeyTemplate` don't exist in AXL v15.0. The `TemplateExtractor` uses direct SQL (`executeSQLQuery`) to fetch softkey template data. See `extractors/templates.py`.
+- **Button templates use `<buttonNumber>` not `<index>`** in `addPhoneButtonTemplate`. The extractor normalizes this on the way out.
+- **BLF name mismatch.** The feature is called "Speed Dial BLF" in `addPhone` but appears as "Busy Lamp Field" in `getPhone` responses. Extractors handle both.
+- **Raw phones must be preserved.** `normalize_phone()` creates a `CanonicalDevice` but loses the raw dict. `pipeline.py` re-stores each phone as `MigrationObject(canonical_id="phone:{name}", pre_migration_state=phone)` so mappers can read `store.get_objects("phone")` and access `speeddials`, `busyLampFields`, and per-line call forwarding.
+- **Unity Connection is optional.** If no Unity Connection config is present, `unity_connection.py` is skipped and `raw_data["voicemail"]["unity_user_settings"]` is absent.
+- **Base station MACs require Cisco Bifrost.** DECT base station MAC validation requires the Cisco manufacturing database — fake MACs fail provisioning. Not an extraction issue but affects test beds.
+- **CTI Route Points use protocol "CTI Route Point"** in AXL — different from standard phone protocols. Use that exact string in `addCTIRoutePoint`.
+- **Pickup group members via `updateLine`**, not `addCallPickupGroup`. Creating a pickup group with `<members>` fails on CUCM 15.0 (null priority FK constraint). The extractor reads the existing members; provisioning test bed uses `updateLine` pattern.
+- **`getPhone` now extracts device-settings fields.** `commonPhoneConfigName`, `productSpecificConfiguration`, `userLocale`, `networkLocale`, `dndOption`, `dndStatus`, and `enableExtensionMobility` are all in `PHONE_GET_RETURNED_TAGS` for the DeviceSettingsMapper.
+- **InformationalExtractor fetches CPC details.** After listing Common Phone Configs, the extractor calls `getCommonPhoneConfig` per item to retrieve `vendorConfig` (model-specific XML settings).

wxcli/migration/cucm/__init__.py

@@ -0,0 +1,5 @@
+"""CUCM extraction layer for the migration pipeline.
+
+Connects to CUCM via AXL SOAP (zeep) and optionally to Unity Connection
+via CUPI REST to extract configuration data for migration analysis.
+"""

wxcli/migration/cucm/connection.py

@@ -0,0 +1,265 @@
+"""AXL SOAP client via zeep.
+
+Provides the AXL connection, version detection, and pagination helper
+that all extractors use.
+
+Sources:
+- cucm-wxc-migration.md lines 301-309 (WSDL, auth, pagination)
+- 02b-cucm-extraction.md §1 (connection setup, pagination strategy)
+"""
+
+from __future__ import annotations
+
+import logging
+import urllib3
+from collections import OrderedDict
+from typing import Any
+
+from requests import Session
+from requests.auth import HTTPBasicAuth
+from zeep import Client, Settings
+from zeep.helpers import serialize_object
+from zeep.transports import Transport
+
+# CUCM uses self-signed certs — suppress the noise
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+logger = logging.getLogger(__name__)
+
+
+class AXLConnectionError(Exception):
+    """Raised when the AXL connection cannot be established."""
+
+
+class AXLConnection:
+    """AXL SOAP client using zeep.
+
+    (from 02b §1: connection setup)
+
+    Args:
+        host: CUCM hostname or IP address.
+        username: AXL admin username.
+        password: AXL admin password.
+        version: CUCM AXL schema version (default "14.0").
+        verify_ssl: Whether to verify SSL certificates (default False —
+            CUCM typically uses self-signed certs).
+        timeout: SOAP request timeout in seconds (default 30).
+        wsdl_path: Path to a local AXL WSDL file. If provided, zeep loads
+            the schema locally instead of fetching from the CUCM server.
+            Download from CUCM Admin > Application > Plugins > "Cisco AXL Toolkit".
+        port: CUCM AXL port (default 8443).
+    """
+
+    def __init__(
+        self,
+        host: str,
+        username: str,
+        password: str,
+        version: str = "14.0",
+        verify_ssl: bool = False,
+        timeout: int = 30,
+        wsdl_path: str | None = None,
+        port: int = 8443,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.version = version
+
+        session = Session()
+        session.auth = HTTPBasicAuth(username, password)
+        session.verify = verify_ssl
+        transport = Transport(session=session, timeout=timeout)
+
+        # Use local WSDL if provided, otherwise fetch from CUCM
+        if wsdl_path:
+            self.wsdl_url = wsdl_path
+        else:
+            self.wsdl_url = f"https://{host}:{self.port}/axl/AXLAPIService?wsdl"
+
+        # strict=False: CUCM responses may contain elements not in the WSDL
+        # (e.g. isAnonymous in getSipTrunk on CUCM 15.0). Without this,
+        # zeep raises XMLSyntaxError for any unexpected element.
+        settings = Settings(strict=False, xml_huge_tree=True)
+
+        try:
+            self.client = Client(
+                self.wsdl_url, transport=transport, settings=settings,
+            )
+        except Exception as exc:
+            raise AXLConnectionError(
+                f"Failed to load WSDL from {self.wsdl_url}: {exc}"
+            ) from exc
+
+        # When using a local WSDL, zeep needs the service address pointed at the real CUCM
+        service_url = f"https://{host}:{self.port}/axl/"
+        try:
+            self.service = self.client.create_service(
+                "{http://www.cisco.com/AXLAPIService/}AXLAPIBinding",
+                service_url,
+            )
+        except Exception as exc:
+            raise AXLConnectionError(
+                f"Failed to initialize AXL service at {service_url}: {exc}"
+            ) from exc
+
+    def get_version(self) -> str:
+        """Detect CUCM version via getCCMVersion().
+
+        (from cucm-wxc-migration.md line 309)
+        """
+        response = self._serialize(self.service.getCCMVersion())
+        version_info = response.get("return", {})
+        if isinstance(version_info, dict):
+            comp = version_info.get("componentVersion", {})
+            if isinstance(comp, dict):
+                return comp.get("version", self.version)
+            return str(comp) if comp else self.version
+        return self.version
+
+    # ------------------------------------------------------------------
+    # Pagination helper
+    # ------------------------------------------------------------------
+
+    def paginated_list(
+        self,
+        method_name: str,
+        search_criteria: dict[str, str],
+        returned_tags: dict[str, str],
+        page_size: int = 200,
+    ) -> list[dict[str, Any]]:
+        """Generic paginated AXL list operation.
+
+        (from 02b §1: pagination strategy)
+
+        Args:
+            method_name: AXL method (e.g. 'listEndUser').
+            search_criteria: Filter dict (e.g. {'firstName': '%'} for all).
+            returned_tags: Fields to return (AXL only returns requested fields).
+            page_size: Rows per page (default 200, AXL max for most methods).
+        """
+        all_results: list[dict[str, Any]] = []
+        skip = 0
+        while True:
+            raw = getattr(self.service, method_name)(
+                searchCriteria=search_criteria,
+                returnedTags=returned_tags,
+                first=str(page_size),
+                skip=str(skip),
+            )
+            response = self._serialize(raw)
+            batch = self._extract_rows(response)
+            if not batch:
+                break
+            all_results.extend(batch)
+            if len(batch) < page_size:
+                break  # Last page
+            skip += page_size
+        return all_results
+
+    def get_detail(
+        self, method_name: str, **kwargs: Any
+    ) -> dict[str, Any] | None:
+        """Single-object get operation (e.g. getPhone by name or UUID).
+
+        Returns the inner result dict, or None on error.
+        """
+        try:
+            raw = getattr(self.service, method_name)(**kwargs)
+            response = self._serialize(raw)
+            ret = response.get("return", {})
+            # get responses wrap the object under a single key
+            if isinstance(ret, dict):
+                for key, value in ret.items():
+                    if key != "_value_1" and value is not None:
+                        return self._serialize(value)
+            return ret
+        except Exception as exc:
+            logger.warning("[%s] %s", method_name, exc)
+            return None
+
+    def execute_sql(self, query: str) -> list[dict[str, Any]]:
+        """Run an executeSQLQuery against CUCM's informix database.
+
+        (from 02b §5: performance considerations for large clusters)
+
+        Returns list of row dicts. Each row is a dict mapping column name → value.
+        """
+        raw = self.service.executeSQLQuery(sql=query)
+        response = self._serialize(raw)
+        rows = self._extract_rows(response)
+        # SQL rows may come back as lxml Elements (when using WSDL + zeep).
+        # Convert each row to a plain dict.
+        result: list[dict[str, Any]] = []
+        for row in rows:
+            if isinstance(row, dict):
+                result.append(row)
+            elif isinstance(row, list):
+                # List of lxml Elements: each has .tag and .text
+                row_dict: dict[str, Any] = {}
+                for elem in row:
+                    tag = getattr(elem, "tag", None)
+                    if tag:
+                        # Strip namespace if present
+                        tag = tag.split("}")[-1] if "}" in tag else tag
+                    text = getattr(elem, "text", None)
+                    if tag:
+                        row_dict[tag] = text
+                result.append(row_dict)
+            elif hasattr(row, "__dict__"):
+                result.append(dict(row.__dict__))
+            else:
+                result.append({"_raw": str(row)})
+        return result
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _serialize(obj: Any) -> dict[str, Any]:
+        """Convert zeep typed objects to plain Python dicts.
+
+        Zeep with a local WSDL returns typed objects (e.g. GetPhoneRes)
+        instead of plain dicts. ``serialize_object`` converts them to
+        OrderedDicts recursively. We convert to regular dicts for consistency.
+        """
+        if obj is None:
+            return {}
+        if isinstance(obj, dict):
+            return obj
+        serialized = serialize_object(obj, dict)
+        if isinstance(serialized, dict):
+            return serialized
+        return {"_raw": serialized}
+
+    @staticmethod
+    def _extract_rows(response: Any) -> list[dict[str, Any]]:
+        """Extract the row list from an AXL list/SQL response.
+
+        AXL responses: {'return': {'{objectType}': [rows...]}}
+        Zeep converts this to a dict with one key matching the object type.
+        (from 02b §3: base extractor _extract_rows)
+        """
+        if response is None:
+            return []
+        # Extract the 'return' value from the response.
+        # Zeep response objects support dict-like access.
+        ret: Any = None
+        if hasattr(response, "get"):
+            ret = response.get("return")
+        elif hasattr(response, "__getitem__"):
+            try:
+                ret = response["return"]
+            except (KeyError, TypeError):
+                return []
+        else:
+            return []
+        if not ret:
+            return []
+        if isinstance(ret, dict):
+            for key, value in ret.items():
+                if key != "_value_1" and value is not None:
+                    if isinstance(value, list):
+                        return value
+                    return [value]
+        return []

wxcli/migration/cucm/discovery.py

@@ -0,0 +1,225 @@
+"""Discovery orchestrator — runs all extractors and writes results to store.
+
+Entry point for the extraction phase. Connects to CUCM via AXL SOAP,
+runs each extractor in sequence, and writes raw CUCM dicts into the SQLite
+store for pass 1 normalization.
+
+Sources:
+- 02b-cucm-extraction.md §1 (orchestration, extractor order, summary)
+- 02-normalization-architecture.md (two-pass ELT pattern)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from rich.console import Console
+
+from wxcli.migration.cucm.connection import AXLConnection
+from wxcli.migration.cucm.extractors.base import ExtractionResult
+from wxcli.migration.cucm.extractors.devices import DeviceExtractor
+from wxcli.migration.cucm.extractors.features import FeatureExtractor
+from wxcli.migration.cucm.extractors.locations import LocationExtractor
+from wxcli.migration.cucm.extractors.routing import RoutingExtractor
+from wxcli.migration.cucm.extractors.users import UserExtractor
+from wxcli.migration.cucm.extractors.templates import TemplateExtractor
+from wxcli.migration.cucm.extractors.voicemail import VoicemailExtractor
+from wxcli.migration.cucm.extractors.informational import InformationalExtractor
+from wxcli.migration.cucm.extractors.tier4 import Tier4Extractor
+from wxcli.migration.cucm.extractors.remote_destinations import RemoteDestinationExtractor
+from wxcli.migration.cucm.extractors.e911 import E911Extractor
+from wxcli.migration.cucm.extractors.device_profiles import DeviceProfileExtractor
+from wxcli.migration.cucm.extractors.moh import MOHExtractor
+from wxcli.migration.cucm.extractors.announcements import AnnouncementExtractor
+from wxcli.migration.cucm.unity_connection import UnityConnectionClient
+from wxcli.migration.store import MigrationStore
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+# Extraction order (from 02b §1).
+# Extractors are independent at the extraction phase — order is flexible.
+# shared_lines and workspaces are post-processing steps, not AXL extractors,
+# and run during normalization pass 2.
+EXTRACTOR_ORDER = [
+    "locations",   # Device pools, datetime groups, CUCM locations — no dependencies
+    "users",       # EndUsers — no extraction-phase dependencies
+    "devices",     # Phones — no extraction-phase dependencies
+    "routing",     # Partitions, CSS, route patterns, gateways, trunks — no dependencies
+    "features",    # Hunt pilots, CTI RPs, call park, pickup, schedules — no dependencies
+    "voicemail",   # Voicemail profiles, pilot numbers — no dependencies
+    "templates",   # Button templates, softkey templates — no dependencies
+    "informational",  # Tier 3: report-only informational objects — no dependencies
+    "tier4",  # Tier 4 feature gaps: recording, SNR, transformations, EM profiles
+    "remote_destinations",  # SNR remote destinations
+    "e911",                 # ELIN groups, geo locations
+    "device_profiles",      # EM device profiles
+    "moh",                  # Music on Hold sources
+    "announcements",        # Announcements / media resources
+]
+
+
+class DiscoveryResult:
+    """Aggregate result of a full discovery run.
+
+    (from 02b §1: discovery run summary)
+
+    **Data flow contract for Phase 04 normalizers:**
+
+    Discovery does NOT write raw data to the SQLite store. Raw CUCM dicts
+    live in ``raw_data`` (in-memory). Phase 04 normalizers consume
+    ``raw_data``, transform to canonical models, and write to the store
+    via ``MigrationStore.upsert_object()``.
+
+    **raw_data structure per extractor:**
+
+    - ``raw_data["locations"]``: ``device_pools``, ``datetime_groups``, ``cucm_locations``
+    - ``raw_data["users"]``: ``users``
+    - ``raw_data["devices"]``: ``phones`` (lines pre-filtered: speed dials removed)
+    - ``raw_data["routing"]``: ``partitions``, ``css_list``, ``route_patterns``,
+      ``gateways``, ``sip_trunks``, ``route_groups``, ``route_lists``,
+      ``translation_patterns``
+    - ``raw_data["features"]``: ``hunt_pilots``, ``hunt_lists``, ``line_groups``,
+      ``cti_route_points``, ``call_parks``, ``pickup_groups``, ``time_schedules``,
+      ``time_periods``
+    - ``raw_data["voicemail"]``: ``voicemail_profiles``, ``voicemail_pilots``,
+      and optionally ``unity_user_settings`` (dict keyed by CUCM userid)
+    """
+
+    def __init__(self) -> None:
+        self.run_id: str = ""
+        self.cucm_version: str = ""
+        self.started_at: str = ""
+        self.completed_at: str = ""
+        self.extractor_results: dict[str, ExtractionResult] = {}
+        self.raw_data: dict[str, dict[str, Any]] = {}
+
+    @property
+    def total_objects(self) -> int:
+        return sum(r.total for r in self.extractor_results.values())
+
+    @property
+    def total_failed(self) -> int:
+        return sum(r.failed for r in self.extractor_results.values())
+
+    def to_summary(self) -> dict[str, Any]:
+        """Produce the journal summary dict (from 02b §1)."""
+        return {
+            "run_type": "discovery",
+            "run_id": self.run_id,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "cucm_version": self.cucm_version,
+            "extractors": {
+                name: {"total": r.total, "failed": r.failed}
+                for name, r in self.extractor_results.items()
+            },
+        }
+
+
+def run_discovery(
+    connection: AXLConnection,
+    store: MigrationStore,
+    unity_client: UnityConnectionClient | None = None,
+) -> DiscoveryResult:
+    """Run full CUCM discovery — extract all object types.
+
+    (from 02b §1: discovery orchestration)
+
+    Args:
+        connection: Established AXL SOAP connection.
+        store: Migration store for writing results and journal entries.
+        unity_client: Optional Unity Connection client for voicemail detail.
+
+    Returns:
+        DiscoveryResult with per-extractor counts, errors, and raw data.
+    """
+    result = DiscoveryResult()
+    result.run_id = store.current_run_id
+    result.started_at = datetime.now(timezone.utc).isoformat()
+
+    # Detect CUCM version (from cucm-wxc-migration.md line 309)
+    try:
+        result.cucm_version = connection.get_version()
+        logger.info("CUCM version: %s", result.cucm_version)
+    except Exception as exc:
+        logger.warning("Could not detect CUCM version: %s", exc)
+        result.cucm_version = "unknown"
+
+    # Build extractors in order (from 02b §1: EXTRACTOR_ORDER)
+    extractors: dict[str, Any] = {
+        "locations": LocationExtractor(connection),
+        "users": UserExtractor(connection),
+        "devices": DeviceExtractor(connection),
+        "routing": RoutingExtractor(connection),
+        "features": FeatureExtractor(connection),
+        "voicemail": VoicemailExtractor(connection, unity_client=unity_client),
+        "templates": TemplateExtractor(connection),
+        "informational": InformationalExtractor(connection),
+        "tier4": Tier4Extractor(connection),
+        "remote_destinations": RemoteDestinationExtractor(connection),
+        "e911": E911Extractor(connection),
+        "device_profiles": DeviceProfileExtractor(connection),
+        "moh": MOHExtractor(connection),
+        "announcements": AnnouncementExtractor(connection),
+    }
+
+    # Run each extractor in order
+    for name in EXTRACTOR_ORDER:
+        extractor = extractors[name]
+        logger.info("--- Running extractor: %s ---", name)
+        console.print(f"  Extracting {name}...")
+        try:
+            ext_result = extractor.extract()
+        except Exception as exc:
+            logger.error("[%s] Extraction failed: %s", name, exc)
+            ext_result = ExtractionResult(extractor=name)
+            ext_result.errors.append(f"Unrecoverable error: {exc}")
+
+        result.extractor_results[name] = ext_result
+        result.raw_data[name] = extractor.results
+        console.print(f"  {name}: {ext_result.total} objects")
+        if ext_result.errors:
+            for err in ext_result.errors:
+                console.print(f"  [yellow]{name}: {err}[/yellow]")
+
+    # Extract Unity Connection per-user voicemail settings if client available
+    if unity_client is not None:
+        user_extractor = extractors["users"]
+        user_dicts = user_extractor.results.get("users", [])
+        user_ids = [u.get("userid", "") for u in user_dicts if u.get("userid")]
+        vm_extractor = extractors["voicemail"]
+        unity_settings = vm_extractor.extract_unity_settings(user_ids)
+        # Store Unity settings alongside AXL voicemail data
+        result.raw_data.setdefault("voicemail", {})["unity_user_settings"] = unity_settings
+
+    result.completed_at = datetime.now(timezone.utc).isoformat()
+
+    # Write summary to journal (from 02b §1: discovery run summary)
+    # Ensure the system sentinel object exists so the FK constraint is satisfied
+    store.conn.execute(
+        """INSERT OR IGNORE INTO objects
+           (canonical_id, object_type, status, data, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?)""",
+        ("system:discovery", "system", "discovered", "{}", result.completed_at, result.completed_at),
+    )
+    store.conn.commit()
+    summary = result.to_summary()
+    store.add_journal_entry(
+        entry_type="discovery_complete",
+        canonical_id="system:discovery",
+        resource_type="discovery",
+        request=summary,
+    )
+
+    logger.info(
+        "Discovery complete: %d objects extracted (%d failed) across %d extractors",
+        result.total_objects,
+        result.total_failed,
+        len(result.extractor_results),
+    )
+
+    return result

wxcli/migration/cucm/extractors/__init__.py

@@ -0,0 +1 @@
+"""CUCM AXL extractors — one module per object domain."""

wxcli/migration/cucm/extractors/announcements.py

@@ -0,0 +1,92 @@
+"""Announcement extractor for CUCM AXL.
+
+Pulls Announcements from CUCM AXL for custom audio migration advisory.
+
+Sources:
+- tier2-enterprise-expansion.md §2.4 (announcement extraction)
+- AXL WSDL: listAnnouncement / getAnnouncement
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.cucm.extractors.base import BaseExtractor, ExtractionResult
+
+logger = logging.getLogger(__name__)
+
+# returnedTags for listAnnouncement
+ANNOUNCEMENT_LIST_RETURNED_TAGS = {
+    "name": "",
+    "description": "",
+}
+
+# Additional fields from getAnnouncement
+ANNOUNCEMENT_GET_RETURNED_TAGS = {
+    "name": "",
+    "description": "",
+    "announcementFile": "",
+}
+
+
+class AnnouncementExtractor(BaseExtractor):
+    """Extract Announcements from CUCM AXL.
+
+    Announcements are custom audio files uploaded to CUCM and referenced
+    by Auto Attendants, Call Queues, MOH sources, and other features.
+
+    (from tier2-enterprise-expansion.md §2.4)
+    """
+
+    name = "announcements"
+
+    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["announcements"] = self._extract_announcements(result)
+        return result
+
+    def _extract_announcements(
+        self, result: ExtractionResult
+    ) -> list[dict[str, Any]]:
+        """List all announcements, then get full detail for each."""
+        announcements: list[dict[str, Any]] = []
+        try:
+            summaries = self.paginated_list(
+                "listAnnouncement",
+                {"name": "%"},
+                ANNOUNCEMENT_LIST_RETURNED_TAGS,
+            )
+        except Exception as exc:
+            msg = f"listAnnouncement failed: {exc}"
+            logger.error("[%s] %s", self.name, msg)
+            result.errors.append(msg)
+            return announcements
+
+        for summary in summaries:
+            result.total += 1
+            ann_name = summary.get("name", "")
+            if not ann_name:
+                result.failed += 1
+                continue
+            try:
+                detail = self.get_detail("getAnnouncement", name=ann_name)
+            except Exception as exc:
+                logger.warning(
+                    "[%s] getAnnouncement error for %s: %s",
+                    self.name, ann_name, exc,
+                )
+                announcements.append(summary)
+                continue
+            if detail is None:
+                announcements.append(summary)
+                continue
+            # Merge list-level fields into detail
+            merged = {**summary, **detail}
+            announcements.append(merged)
+
+        return announcements