wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/mappers/line_mapper.py

@@ -0,0 +1,310 @@
+"""Line mapper: CUCM Directory Numbers -> Webex Phone Numbers + Extensions.
+
+Maps CUCM DNs (identified from device line appearances) to CanonicalLine objects
+with E.164 normalization. Each unique DN (pattern + partition) becomes one
+CanonicalLine.
+
+(from 03b-transform-mappers.md §3, line_mapper)
+
+Cross-ref reads:
+    device_has_dn          (Device -> DN) — reverse-queried to find devices per DN
+    dn_in_partition        (DN -> Partition)
+    device_in_pool         (Device -> DevicePool) — for location chain
+    device_pool_to_location (DevicePool -> Location) — for country code
+
+Does NOT produce: EXTENSION_CONFLICT (analyzer-owned)
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalLine,
+    DecisionType,
+    LineClassification,
+    MapperResult,
+    MigrationStatus,
+    Provenance,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.e164 import normalize_dn
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    decision_to_store_dict,
+    manual_option,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# Webex extension length constraints
+# (from 03b-transform-mappers.md §3: "Extensions are 2-10 chars in Webex")
+_MIN_EXTENSION_LENGTH = 2
+_MAX_EXTENSION_LENGTH = 10
+
+
+class LineMapper(Mapper):
+    """Maps CUCM Directory Numbers to Webex Phone Numbers and Extensions.
+
+    (from 03b-transform-mappers.md §3)
+    """
+
+    name = "line_mapper"
+    depends_on = ["location_mapper"]
+
+    def __init__(
+        self,
+        default_country_code: str = "US",
+        site_prefix_rules: list[dict] | None = None,
+    ) -> None:
+        """
+        Args:
+            default_country_code: ISO 3166-1 alpha-2 code for E.164 normalization
+                (from 03b-transform-mappers.md §3: country code from location)
+            site_prefix_rules: List of prefix stripping rules from migration config
+        """
+        self.default_country_code = default_country_code
+        self.site_prefix_rules = site_prefix_rules or []
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        """Find all unique DNs from device line appearances and produce CanonicalLine objects."""
+        result = MapperResult()
+
+        # Collect all unique DN IDs from device_has_dn cross-refs
+        all_dn_refs = store.get_cross_refs(relationship="device_has_dn")
+        unique_dn_ids: set[str] = set()
+        # Track which devices reference each DN (for shared line detection)
+        dn_to_devices: dict[str, list[str]] = {}
+        for ref in all_dn_refs:
+            dn_id = ref["to_id"]
+            dev_id = ref["from_id"]
+            unique_dn_ids.add(dn_id)
+            dn_to_devices.setdefault(dn_id, []).append(dev_id)
+
+        # Build index of pre-computed e164_results from device line appearances
+        # (from Phase 04 corrections: CrossReferenceBuilder computes e164_result
+        # on each line appearance — the line_mapper can read this directly)
+        precomputed_e164: dict[str, dict[str, Any]] = {}
+        self._build_precomputed_e164_index(store, dn_to_devices, precomputed_e164)
+
+        for dn_id in sorted(unique_dn_ids):
+            # Parse DN ID format: "dn:pattern:partition"
+            parts = dn_id.split(":", 2)
+            if len(parts) < 2:
+                continue
+            dn_pattern = parts[1]
+            partition = parts[2] if len(parts) > 2 else "<None>"
+            country_code: str | None = None
+
+            # Check for pre-computed e164_result from line appearances
+            # (from Phase 04 corrections: use e164_result when available)
+            cached = precomputed_e164.get(dn_id)
+            if cached:
+                e164_result_data = cached
+                # Build an E164Result-compatible object from the cached dict
+                e164_result = _E164ResultProxy(
+                    e164=e164_result_data.get("e164"),
+                    extension=e164_result_data.get("extension"),
+                    raw=dn_pattern,
+                    classification=e164_result_data.get("classification", "AMBIGUOUS"),
+                )
+            else:
+                # Fallback: resolve country code and run normalize_dn()
+                country_code = self._resolve_country_code(store, dn_id, dn_to_devices)
+                e164_result = normalize_dn(
+                    dn_pattern, country_code, self.site_prefix_rules
+                )
+
+            # Shared line detection
+            # (from 03b-transform-mappers.md §3: tag shared:true when multiple devices)
+            device_list = dn_to_devices.get(dn_id, [])
+            unique_devices = list(set(device_list))
+            shared = len(unique_devices) > 1
+
+            # Map classification string to enum
+            classification = _classify(e164_result.classification)
+
+            # Build extension and e164 fields
+            extension = None
+            e164 = None
+
+            if classification == LineClassification.EXTENSION:
+                extension = e164_result.extension or dn_pattern
+            elif classification in (LineClassification.NATIONAL, LineClassification.E164):
+                e164 = e164_result.e164
+                # For national/E164 numbers, the raw pattern may also serve as extension
+                # if it looks like one. But per the design, extension comes from the
+                # classified result — NATIONAL/E164 numbers don't get an extension field
+                # unless separately configured. The user_mapper gets bare extension from
+                # user_has_primary_dn independently.
+                # However: a 10-digit national number IS the extension in many CUCM deployments
+                # (from 03b-transform-mappers.md §3: "If classified as EXTENSION: stored as bare extension")
+                extension = e164_result.extension
+            elif classification == LineClassification.AMBIGUOUS:
+                # DN can't be classified
+                # (from 03b-transform-mappers.md §3: DN_AMBIGUOUS decision)
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.DN_AMBIGUOUS,
+                    severity="MEDIUM",
+                    summary=f"DN '{dn_pattern}' (partition: {partition}) cannot be classified as extension, national, or E.164",
+                    context={
+                        "dn_id": dn_id,
+                        "dn_pattern": dn_pattern,
+                        "partition": partition,
+                        "country_code": country_code,
+                    },
+                    options=[
+                        manual_option("Admin classifies as extension-only"),
+                        manual_option("Admin provides correct E.164"),
+                        skip_option("Number not migrated"),
+                    ],
+                    affected_objects=[dn_id],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+                continue
+
+            # Validate extension length for Webex
+            # (from 03b-transform-mappers.md §3: "extensions outside 2-10 chars produce MISSING_DATA")
+            if extension and (
+                len(extension) < _MIN_EXTENSION_LENGTH
+                or len(extension) > _MAX_EXTENSION_LENGTH
+            ):
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.MISSING_DATA,
+                    severity="MEDIUM",
+                    summary=f"DN '{dn_pattern}' resolves to extension '{extension}' which is outside Webex's 2-10 char limit",
+                    context={
+                        "dn_id": dn_id,
+                        "dn_pattern": dn_pattern,
+                        "extension": extension,
+                        "extension_length": len(extension),
+                        "partition": partition,
+                    },
+                    options=[
+                        manual_option("Admin provides valid extension (2-10 chars)"),
+                        skip_option("Number not migrated"),
+                    ],
+                    affected_objects=[dn_id],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+                # Still create the line object but flag it
+                # (user can resolve the decision later)
+
+            line = CanonicalLine(
+                canonical_id=f"line:{dn_pattern}:{partition}",
+                provenance=Provenance(
+                    source_system="cucm",
+                    source_id=dn_id,
+                    source_name=dn_pattern,
+                    extracted_at=datetime.now(timezone.utc),
+                ),
+                status=MigrationStatus.ANALYZED,
+                extension=extension,
+                e164=e164,
+                classification=classification,
+                shared=shared,
+                cucm_pattern=dn_pattern,
+                route_partition_name=partition if partition != "<None>" else None,
+            )
+
+            store.upsert_object(line)
+            result.objects_created += 1
+
+        return result
+
+    def _build_precomputed_e164_index(
+        self,
+        store: MigrationStore,
+        dn_to_devices: dict[str, list[str]],
+        precomputed: dict[str, dict[str, Any]],
+    ) -> None:
+        """Build index of pre-computed e164_results from device line appearances.
+
+        After CrossReferenceBuilder runs, each line appearance entry in a device's
+        pre_migration_state has e164_result: {e164, extension, classification}.
+        We index these by DN ID so the mapper can use them directly.
+
+        (from Phase 04 corrections: line appearances have e164_result already computed)
+        """
+        seen_devices: set[str] = set()
+        for dn_id, device_ids in dn_to_devices.items():
+            if dn_id in precomputed:
+                continue
+            for dev_id in device_ids:
+                if dev_id in seen_devices:
+                    continue
+                seen_devices.add(dev_id)
+                # Handle virtual cross-ref IDs gracefully
+                # (from Phase 04 corrections: get_object may return None)
+                dev_data = store.get_object(dev_id)
+                if not dev_data:
+                    continue
+                state = dev_data.get("pre_migration_state") or {}
+                for la in state.get("line_appearances", []):
+                    la_dn_id = la.get("dn_canonical_id")
+                    e164_res = la.get("e164_result")
+                    if la_dn_id and e164_res and la_dn_id not in precomputed:
+                        precomputed[la_dn_id] = e164_res
+
+    def _resolve_country_code(
+        self,
+        store: MigrationStore,
+        dn_id: str,
+        dn_to_devices: dict[str, list[str]],
+    ) -> str:
+        """Resolve country code for a DN by following the location chain.
+
+        Chain: DN -> (reverse device_has_dn) -> device -> device_in_pool
+               -> device_pool_to_location -> location -> address.country
+
+        (from 03b-transform-mappers.md §3: "country_code comes from the DN's resolved location")
+
+        Handles virtual cross-ref IDs gracefully — if get_object returns None
+        for any step, continues to the next device.
+        (from Phase 04 corrections: handle get_object returning None)
+        """
+        device_ids = dn_to_devices.get(dn_id, [])
+        for dev_id in device_ids:
+            # Follow: device -> device_in_pool -> device_pool_to_location
+            location_id = store.resolve_chain(
+                dev_id, "device_in_pool", "device_pool_to_location"
+            )
+            if location_id:
+                loc_data = store.get_object(location_id)
+                if loc_data:
+                    address = loc_data.get("address", {})
+                    country = address.get("country")
+                    if country:
+                        return country
+        return self.default_country_code
+
+
+class _E164ResultProxy:
+    """Lightweight proxy matching E164Result interface for pre-computed values.
+
+    Used when e164_result is already available from CrossReferenceBuilder
+    rather than calling normalize_dn().
+    """
+
+    __slots__ = ("e164", "extension", "raw", "classification")
+
+    def __init__(self, e164: str | None, extension: str | None, raw: str, classification: str):
+        self.e164 = e164
+        self.extension = extension
+        self.raw = raw
+        self.classification = classification
+
+
+def _classify(classification_str: str) -> LineClassification:
+    """Convert E164Result classification string to LineClassification enum."""
+    try:
+        return LineClassification(classification_str)
+    except ValueError:
+        return LineClassification.AMBIGUOUS

wxcli/migration/transform/mappers/location_mapper.py

@@ -0,0 +1,235 @@
+"""Location mapper: CUCM Device Pools -> Webex Calling Locations.
+
+Maps one or more CUCM device pools to a single CanonicalLocation, consolidated
+by the CUCM Location entity they reference. Multiple device pools sharing the
+same CUCM Location produce exactly one Webex location.
+
+(from 03b-transform-mappers.md §1, location_mapper)
+
+Cross-ref reads:
+    device_pool_has_datetime_group (DevicePool -> DateTimeGroup) — timezone
+    device_pool_at_cucm_location   (DevicePool -> CUCM Location) — address
+
+Cross-ref writes:
+    device_pool_to_location (DevicePool canonical_id -> new location canonical_id)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalLocation,
+    DecisionType,
+    LocationAddress,
+    MapperResult,
+    MigrationStatus,
+    Provenance,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    decision_to_store_dict,
+    manual_option,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# Max location name length in Webex
+# (from 03b-transform-mappers.md §1: "truncate to 80 chars")
+_MAX_LOCATION_NAME_LENGTH = 80
+
+
+class LocationMapper(Mapper):
+    """Maps CUCM Device Pools to Webex Calling Locations.
+
+    (from 03b-transform-mappers.md §1)
+    """
+
+    name = "location_mapper"
+    depends_on: list[str] = []
+
+    def __init__(
+        self,
+        default_language: str = "en_us",
+        default_country: str = "US",
+        outside_dial_digit: str = "9",
+        site_prefix_rules: list[dict[str, str]] | None = None,
+    ) -> None:
+        self.default_language = default_language
+        self.default_country = default_country
+        self.outside_dial_digit = outside_dial_digit
+        self.site_prefix_rules = site_prefix_rules or []
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        """Read device pools and produce CanonicalLocation objects.
+
+        Consolidation: device pools that share a CUCM Location entity are merged
+        into a single CanonicalLocation. The first device pool name is used as the
+        location name; all pool names are stored in cucm_device_pool_names.
+
+        (from 03b-transform-mappers.md §1, consolidation edge case)
+        """
+        result = MapperResult()
+
+        # Phase 1: Group device pools by their CUCM Location reference
+        # Key = cucm_location canonical_id, Value = list of device pool dicts
+        location_groups: dict[str, list[dict[str, Any]]] = {}
+        # Track device pools with no CUCM location reference
+        orphan_pools: list[dict[str, Any]] = []
+
+        for dp_data in store.get_objects("device_pool"):
+            dp_id = dp_data["canonical_id"]
+
+            # Resolve CUCM Location via cross-ref
+            loc_refs = store.find_cross_refs(dp_id, "device_pool_at_cucm_location")
+            if loc_refs:
+                cucm_loc_id = loc_refs[0]
+                location_groups.setdefault(cucm_loc_id, []).append(dp_data)
+            else:
+                orphan_pools.append(dp_data)
+
+        # Phase 2: Create one CanonicalLocation per CUCM Location group
+        for cucm_loc_id, dp_list in location_groups.items():
+            location, warnings = self._build_location(store, cucm_loc_id, dp_list)
+            for w in warnings:
+                location.warnings.append(w)
+
+            store.upsert_object(location)
+            result.objects_created += 1
+
+            # Write device_pool_to_location cross-refs for all pools in the group
+            for dp_data in dp_list:
+                store.add_cross_ref(
+                    dp_data["canonical_id"],
+                    location.canonical_id,
+                    "device_pool_to_location",
+                )
+
+        # Phase 3: Handle orphan device pools (no CUCM Location ref)
+        for dp_data in orphan_pools:
+            dp_id = dp_data["canonical_id"]
+            dp_name = dp_data.get("pre_migration_state", {}).get(
+                "device_pool_name", dp_id
+            )
+
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.LOCATION_AMBIGUOUS,
+                severity="HIGH",
+                summary=f"Device pool '{dp_name}' has no CUCM Location reference — cannot determine Webex location",
+                context={
+                    "device_pool_id": dp_id,
+                    "device_pool_name": dp_name,
+                },
+                options=[
+                    manual_option("Admin must provide address and create location manually"),
+                    skip_option("Device pool not migrated; users/devices in this pool need reassignment"),
+                ],
+                affected_objects=[dp_id],
+            )
+            store.save_decision(decision_to_store_dict(decision))
+            result.decisions.append(decision)
+
+        return result
+
+    def _build_location(
+        self,
+        store: MigrationStore,
+        cucm_loc_id: str,
+        dp_list: list[dict[str, Any]],
+    ) -> tuple[CanonicalLocation, list[str]]:
+        """Build a CanonicalLocation from a group of device pools sharing a CUCM Location.
+
+        Returns the location and a list of warning strings.
+        """
+        warnings: list[str] = []
+
+        # Use first device pool as primary (for naming)
+        primary_dp = dp_list[0]
+        primary_dp_state = primary_dp.get("pre_migration_state", {})
+        dp_names = [
+            dp.get("pre_migration_state", {}).get("device_pool_name", dp["canonical_id"])
+            for dp in dp_list
+        ]
+
+        # Location name from primary device pool, truncated to 80 chars
+        # (from 03b-transform-mappers.md §1: "truncate to 80 chars")
+        name = dp_names[0]
+        if len(name) > _MAX_LOCATION_NAME_LENGTH:
+            warnings.append(
+                f"Location name truncated from {len(name)} to {_MAX_LOCATION_NAME_LENGTH} chars: '{name}'"
+            )
+            name = name[:_MAX_LOCATION_NAME_LENGTH]
+
+        # Resolve timezone via device_pool_has_datetime_group cross-ref
+        # (from 03b-transform-mappers.md §1: datetime group -> IANA timezone)
+        time_zone = None
+        dtg_name = None
+        dtg_refs = store.find_cross_refs(
+            primary_dp["canonical_id"], "device_pool_has_datetime_group"
+        )
+        if dtg_refs:
+            dtg_data = store.get_object(dtg_refs[0])
+            if dtg_data:
+                dtg_state = dtg_data.get("pre_migration_state", {})
+                time_zone = dtg_state.get("timezone")
+                dtg_name = dtg_state.get("datetime_group_name")
+
+        # Resolve address from CUCM Location entity
+        # The cucm_loc_id is like "cucm_location:SomeName" — may or may not be in the store
+        address = LocationAddress(country=self.default_country)
+        cucm_loc_data = store.get_object(cucm_loc_id)
+        if cucm_loc_data:
+            loc_state = cucm_loc_data.get("pre_migration_state", {})
+            address = LocationAddress(
+                address1=loc_state.get("address1"),
+                city=loc_state.get("city"),
+                state=loc_state.get("state"),
+                postal_code=loc_state.get("postal_code"),
+                country=loc_state.get("country") or self.default_country,
+            )
+
+        # Canonical ID: single-source if one pool, consolidated hash if multiple
+        # (from 03b-transform-mappers.md §13, Canonical ID Convention)
+        if len(dp_list) == 1:
+            canonical_id = f"location:{primary_dp['canonical_id'].replace('device_pool:', '')}"
+        else:
+            sorted_ids = sorted(dp["canonical_id"] for dp in dp_list)
+            hash_input = "|".join(sorted_ids)
+            hash_val = hashlib.sha256(hash_input.encode()).hexdigest()[:12]
+            canonical_id = f"location:{hash_val}"
+
+        # announcementLanguage must be lowercase
+        # (from 03b-transform-mappers.md §1: "Must be lowercase (en_us not en_US)")
+        # (from docs/reference/location-call-settings-core.md)
+        announcement_language = self.default_language.lower()
+
+        location = CanonicalLocation(
+            canonical_id=canonical_id,
+            provenance=Provenance(
+                source_system="cucm",
+                source_id=primary_dp.get("provenance", {}).get("source_id", ""),
+                source_name=dp_names[0],
+                cluster=primary_dp.get("provenance", {}).get("cluster"),
+                extracted_at=datetime.now(timezone.utc),
+            ),
+            status=MigrationStatus.ANALYZED,
+            name=name,
+            time_zone=time_zone,
+            preferred_language=self.default_language.lower(),
+            announcement_language=announcement_language,
+            address=address,
+            routing_prefix=None,  # Set from config if available
+            outside_dial_digit=str(self.outside_dial_digit) if self.outside_dial_digit is not None else None,
+            calling_enabled=True,
+            cucm_device_pool_names=dp_names,
+            cucm_datetime_group_name=dtg_name,
+            cucm_location_name=cucm_loc_id.replace("cucm_location:", ""),
+        )
+
+        return location, warnings

wxcli/migration/transform/mappers/moh_mapper.py

@@ -0,0 +1,114 @@
+"""MOH mapper: CUCM MOH Audio Sources -> Webex per-location Music On Hold.
+
+Maps CUCM Music On Hold audio sources to Webex Calling per-location MOH
+settings (CanonicalMusicOnHold).
+
+Default MOH sources map automatically. Custom audio sources produce
+AUDIO_ASSET_MANUAL decisions because the WAV file must be manually
+downloaded from CUCM and uploaded to Webex.
+
+(from tier2-enterprise-expansion.md §2.3)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalMusicOnHold,
+    DecisionType,
+    MapperResult,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    extract_provenance,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MOHMapper(Mapper):
+    """Map CUCM MOH audio sources to Webex per-location MOH settings.
+
+    For each moh_source in the store:
+    - Default sources: create CanonicalMusicOnHold, no decision needed
+    - Custom sources: create CanonicalMusicOnHold + AUDIO_ASSET_MANUAL decision
+
+    (from tier2-enterprise-expansion.md §2.3)
+    """
+
+    name = "moh_mapper"
+    depends_on = ["location_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        """Read CUCM MOH sources and produce Webex MOH settings."""
+        result = MapperResult()
+
+        for moh_data in store.get_objects("moh_source"):
+            canonical_id = moh_data["canonical_id"]
+            state = moh_data.get("pre_migration_state") or {}
+
+            name = state.get("name") or ""
+            source_file_name = state.get("source_file_name") or ""
+            is_default = state.get("is_default", False)
+            source_id = state.get("source_id") or ""
+
+            prov = extract_provenance(moh_data)
+
+            moh_obj = CanonicalMusicOnHold(
+                canonical_id=f"music_on_hold:{name}",
+                provenance=prov,
+                status=MigrationStatus.ANALYZED,
+                source_name=name,
+                source_file_name=source_file_name,
+                is_default=is_default,
+                cucm_source_id=source_id,
+            )
+            store.upsert_object(moh_obj)
+            result.objects_created += 1
+
+            # Custom audio sources need manual intervention
+            if not is_default:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.AUDIO_ASSET_MANUAL,
+                    severity="MEDIUM",
+                    summary=(
+                        f"Custom MOH audio source '{name}' "
+                        f"(file: {source_file_name or 'unknown'}) "
+                        f"requires manual download from CUCM and upload to Webex"
+                    ),
+                    context={
+                        "moh_source_name": name,
+                        "source_file_name": source_file_name,
+                        "source_id": source_id,
+                        "canonical_id": f"music_on_hold:{name}",
+                    },
+                    options=[
+                        accept_option(
+                            "Admin downloads WAV from CUCM and uploads to Webex location MOH"
+                        ),
+                        _use_default_option(),
+                        skip_option("Skip MOH migration for this source"),
+                    ],
+                    affected_objects=[f"music_on_hold:{name}"],
+                )
+                result.decisions.append(decision)
+
+        return result
+
+
+def _use_default_option():
+    """Create a 'Use default MOH' decision option."""
+    from wxcli.migration.models import DecisionOption
+
+    return DecisionOption(
+        id="use_default",
+        label="Use Webex default",
+        impact="Accept Webex default MOH instead of custom audio",
+    )