wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/mappers/base.py

@@ -0,0 +1,190 @@
+"""Base class for all transform mappers.
+
+Provides the Mapper ABC with map() abstract method, decision creation helpers,
+fingerprint generation, and standard decision option builders.
+
+(from 03b-transform-mappers.md, shared patterns section §13)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalUser,
+    Decision,
+    DecisionOption,
+    DecisionType,
+    MapperResult,
+    Provenance,
+)
+from wxcli.migration.store import MigrationStore
+
+
+class Mapper(ABC):
+    """Base class for all transform mappers.
+
+    Each mapper reads CUCM canonical objects from the store, produces
+    Webex canonical objects, and returns decisions for anything it
+    can't cleanly map.
+
+    (from 03b-transform-mappers.md, shared patterns — Mapper base class)
+    """
+
+    name: str = ""
+    depends_on: list[str] = []
+
+    @abstractmethod
+    def map(self, store: MigrationStore) -> MapperResult:
+        """Read CUCM canonical objects, produce Webex canonical objects + decisions."""
+        ...
+
+    def _create_decision(
+        self,
+        store: MigrationStore,
+        decision_type: DecisionType,
+        severity: str,
+        summary: str,
+        context: dict[str, Any],
+        options: list[DecisionOption],
+        affected_objects: list[str],
+    ) -> Decision:
+        """Helper to create a well-formed Decision with auto-generated ID and fingerprint.
+
+        (from 03b-transform-mappers.md, shared patterns — _create_decision helper)
+        """
+        return Decision(
+            decision_id=store.next_decision_id(),
+            type=decision_type,
+            severity=severity,
+            summary=summary,
+            context=context,
+            options=options,
+            affected_objects=affected_objects,
+            fingerprint=self._fingerprint(decision_type, context),
+            run_id=store.current_run_id,
+        )
+
+    def _fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        """Deterministic fingerprint for idempotent decision identity.
+
+        (from 03b-transform-mappers.md, shared patterns — _fingerprint helper)
+        """
+        key_data = json.dumps({"type": decision_type.value, **context}, sort_keys=True)
+        return hashlib.sha256(key_data.encode()).hexdigest()[:16]
+
+
+# ---------------------------------------------------------------------------
+# Decision option builder helpers
+# (from 03b-transform-mappers.md, shared patterns — Decision Option Builder)
+# ---------------------------------------------------------------------------
+
+
+def skip_option(impact: str = "Object not migrated") -> DecisionOption:
+    """Create a 'Skip' decision option."""
+    return DecisionOption(id="skip", label="Skip", impact=impact)
+
+
+def manual_option(impact: str = "Requires manual configuration post-migration") -> DecisionOption:
+    """Create a 'Manual' decision option."""
+    return DecisionOption(id="manual", label="Manual", impact=impact)
+
+
+def accept_option(impact: str) -> DecisionOption:
+    """Create an 'Accept fidelity loss' decision option."""
+    return DecisionOption(id="accept", label="Accept fidelity loss", impact=impact)
+
+
+# ---------------------------------------------------------------------------
+# Store serialization helper
+# ---------------------------------------------------------------------------
+
+
+def decision_to_store_dict(decision: Decision) -> dict[str, Any]:
+    """Convert a Decision Pydantic model to the dict format store.save_decision() expects.
+
+    The store expects:
+    - type as string value (e.g., "LOCATION_AMBIGUOUS"), not the enum member
+    - options as list of dicts (not DecisionOption models)
+    - context as dict (not JSON string — the store handles serialization)
+
+    affected_objects is embedded in context (as _affected_objects) since the
+    decisions table has no dedicated column. merge_decisions() in Phase 10
+    can read it from context when needed.
+    """
+    ctx = dict(decision.context)
+    if decision.affected_objects:
+        ctx["_affected_objects"] = decision.affected_objects
+    return {
+        "decision_id": decision.decision_id,
+        "type": decision.type.value,
+        "severity": decision.severity,
+        "summary": decision.summary,
+        "context": ctx,
+        "options": [opt.model_dump() for opt in decision.options],
+        "chosen_option": decision.chosen_option,
+        "resolved_at": decision.resolved_at,
+        "resolved_by": decision.resolved_by,
+        "fingerprint": decision.fingerprint,
+        "run_id": decision.run_id,
+        "recommendation": decision.recommendation,
+        "recommendation_reasoning": decision.recommendation_reasoning,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Shared mapper utilities (DRY — used by all 9 mappers)
+# ---------------------------------------------------------------------------
+
+
+def extract_provenance(data: dict[str, Any]) -> Provenance:
+    """Extract Provenance from a stored object dict.
+
+    Handles both Pydantic-serialized dicts (from store.get_objects) and
+    raw dicts. Gracefully handles missing or malformed extracted_at.
+    """
+    prov = data.get("provenance", {})
+    extracted_at = prov.get("extracted_at")
+    if isinstance(extracted_at, str):
+        try:
+            extracted_at = datetime.fromisoformat(extracted_at)
+        except (ValueError, TypeError):
+            extracted_at = datetime.now(timezone.utc)
+    elif extracted_at is None:
+        extracted_at = datetime.now(timezone.utc)
+
+    return Provenance(
+        source_system=prov.get("source_system", "cucm"),
+        source_id=prov.get("source_id", ""),
+        source_name=prov.get("source_name", ""),
+        cluster=prov.get("cluster"),
+        extracted_at=extracted_at,
+        cucm_version=prov.get("cucm_version"),
+    )
+
+
+def enrich_user(store: MigrationStore, user_id: str, **fields: Any) -> None:
+    """Update fields on a CanonicalUser in the store.
+
+    Re-reads the user dict, merges the provided fields, reconstructs
+    a CanonicalUser (filtering to known model fields), and upserts.
+    Used by enrichment mappers (VoicemailMapper, CallSettingsMapper).
+    """
+    user_data = store.get_object(user_id)
+    if not user_data:
+        return
+    user_data.update(fields)
+    enriched = CanonicalUser(**{
+        k: v for k, v in user_data.items()
+        if k in CanonicalUser.model_fields
+    })
+    store.upsert_object(enriched)
+
+
+def hash_id(value: str) -> str:
+    """Generate a deterministic short hash for canonical IDs."""
+    return hashlib.sha256(value.encode()).hexdigest()[:12]

wxcli/migration/transform/mappers/button_template_mapper.py

@@ -0,0 +1,186 @@
+"""ButtonTemplateMapper: CUCM Phone Button Templates -> Webex Line Key Templates.
+
+Maps CUCM button feature types to Webex LineKeyType values. Determines KEM
+boundaries from model-specific line key counts. Produces CanonicalLineKeyTemplate
+objects and BUTTON_UNMAPPABLE decisions for unmappable buttons.
+
+(from tier2-phase2-phone-config-design.md S4.1)
+
+Cross-ref reads:
+    phone_uses_button_template  (Phone -> ButtonTemplate)  -- usage count
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalLineKeyTemplate,
+    DecisionOption,
+    DecisionType,
+    MapperResult,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    decision_to_store_dict,
+    extract_provenance,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# CUCM button feature -> Webex LineKeyType
+CUCM_BUTTON_TO_WEBEX: dict[str, str | None] = {
+    "Line": "PRIMARY_LINE",
+    "Speed Dial": "SPEED_DIAL",
+    "Busy Lamp Field": "MONITOR",
+    "Speed Dial BLF": "MONITOR",       # AXL getPhoneButtonTemplate returns this name
+    "Call Park": "CALL_PARK_EXTENSION",
+    "Call Park BLF": "CALL_PARK_EXTENSION",
+    "Abbreviated Dial": "SPEED_DIAL",
+    "None": "OPEN",
+    "Unassigned": "OPEN",
+    # Unmappable -- return None
+    "Intercom": None,
+    "Service URL": None,
+    "Privacy": None,
+    "Malicious Call ID": None,
+    "Quality Report Tool": None,
+    "Do Not Disturb": None,
+    "Feature": None,
+}
+
+# Max line key count per phone model (buttons beyond this are KEM keys)
+from wxcli.migration.phone_models import MODEL_LINE_KEY_COUNTS as _MODEL_LINE_KEY_COUNTS
+
+# Regex to extract 4-digit model number from base template name
+_MODEL_RE = re.compile(r"(\d{4})")
+
+
+def _parse_model_from_base_template(base_template: str | None) -> str | None:
+    """Extract the 4-digit phone model from a CUCM base template name.
+
+    E.g. "Standard 8845" -> "8845", "Universal Phone Template" -> None
+    """
+    if not base_template:
+        return None
+    match = _MODEL_RE.search(base_template)
+    return match.group(1) if match else None
+
+
+class ButtonTemplateMapper(Mapper):
+    """Maps CUCM Phone Button Templates to Webex Line Key Templates."""
+
+    name = "button_template_mapper"
+    depends_on = ["device_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+
+        for tmpl_data in store.get_objects("button_template"):
+            tmpl_id = tmpl_data["canonical_id"]
+            state = tmpl_data.get("pre_migration_state") or {}
+            name = state.get("name", tmpl_id.split(":", 1)[-1])
+            base_template = state.get("base_template")
+            buttons = state.get("buttons", [])
+
+            # Count phones using this template
+            phone_refs = [
+                r["from_id"]
+                for r in store.get_cross_refs(
+                    to_id=tmpl_id, relationship="phone_uses_button_template"
+                )
+            ]
+            phones_using = len(phone_refs)
+
+            # Determine model and max line keys
+            model_num = (
+                _parse_model_from_base_template(base_template)
+                or _parse_model_from_base_template(name)
+            )
+            max_keys = _MODEL_LINE_KEY_COUNTS.get(model_num, 999)
+
+            line_keys: list[dict[str, Any]] = []
+            kem_keys: list[dict[str, Any]] = []
+            unmapped: list[dict[str, Any]] = []
+
+            for btn in buttons:
+                idx = btn.get("index", 0)
+                feature = btn.get("feature", "")
+                webex_type = CUCM_BUTTON_TO_WEBEX.get(feature)
+
+                if webex_type is None and feature:
+                    # Unknown or unmappable feature
+                    unmapped.append({"index": idx, "feature": feature})
+                    continue
+
+                if not webex_type:
+                    webex_type = "OPEN"
+
+                entry = {"index": idx, "key_type": webex_type}
+
+                if idx <= max_keys:
+                    line_keys.append(entry)
+                else:
+                    kem_keys.append(entry)
+
+            # Determine KEM module type from key count
+            kem_module_type = None
+            if kem_keys:
+                kem_count = len(kem_keys)
+                if kem_count <= 14:
+                    kem_module_type = "KEM_14_KEYS"
+                elif kem_count <= 18:
+                    kem_module_type = "KEM_18_KEYS"
+                else:
+                    kem_module_type = "KEM_20_KEYS"
+
+            lkt = CanonicalLineKeyTemplate(
+                canonical_id=f"line_key_template:{name}",
+                provenance=extract_provenance(tmpl_data),
+                status=MigrationStatus.ANALYZED,
+                name=name,
+                cucm_template_name=name,
+                device_model=f"DMS Cisco {model_num}" if model_num else None,
+                line_keys=line_keys,
+                kem_module_type=kem_module_type,
+                kem_keys=kem_keys,
+                unmapped_buttons=unmapped,
+                phones_using=phones_using,
+            )
+            store.upsert_object(lkt)
+            result.objects_created += 1
+
+            # Decision for unmappable buttons (only if phones use this template)
+            if unmapped and phones_using > 0:
+                features = list({u["feature"] for u in unmapped})
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.BUTTON_UNMAPPABLE,
+                    severity="LOW",
+                    summary=(
+                        f"Template '{name}' has {len(unmapped)} button(s) with no Webex "
+                        f"equivalent: {', '.join(features)} ({phones_using} phones affected)"
+                    ),
+                    context={
+                        "template_name": name,
+                        "unmapped_features": features,
+                        "phones_using": phones_using,
+                    },
+                    options=[
+                        DecisionOption(
+                            id="accept_loss",
+                            label="Accept loss",
+                            impact="Accept -- these button types don't exist in Webex",
+                        ),
+                        skip_option("Skip template migration for these phones"),
+                    ],
+                    affected_objects=[lkt.canonical_id],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+
+        return result

wxcli/migration/transform/mappers/call_forwarding_mapper.py

@@ -0,0 +1,228 @@
+"""CallForwardingMapper — CUCM per-line forwarding → Webex per-person call forwarding.
+
+Reads phone objects from the store (which contain enriched line entries with
+call forwarding fields from getLine), resolves user ownership via
+device_owned_by_user cross-ref, and produces CanonicalCallForwarding objects.
+
+CUCM has 10 forwarding variants. Webex supports 3 (CFA, CFB, CFNA).
+The remaining 5 CUCM-only variants (BusyInt, NoAnswerInt, NoCoverage,
+OnFailure, NotRegistered) produce FORWARDING_LOSSY decisions.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalCallForwarding,
+    DecisionType,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.models import MapperResult
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    extract_provenance,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# CUCM-only forwarding variants that have no Webex equivalent
+_LOSSY_VARIANTS = (
+    "callForwardBusyInt",
+    "callForwardNoAnswerInt",
+    "callForwardNoCoverage",
+    "callForwardNoCoverageInt",
+    "callForwardOnFailure",
+    "callForwardNotRegistered",
+    "callForwardNotRegisteredInt",
+)
+
+
+def _is_forwarding_active(fwd: dict | None) -> bool:
+    """Check if a CUCM forwarding setting is actively configured."""
+    if not fwd or not isinstance(fwd, dict):
+        return False
+    dest = fwd.get("destination")
+    fwd_to_vm = fwd.get("forwardToVoiceMail")
+    # Active if there's a non-empty destination or it forwards to voicemail
+    return bool(dest) or (fwd_to_vm in ("true", True))
+
+
+def _duration_to_rings(duration_ms: int | str | None) -> int | None:
+    """Convert CUCM duration (seconds) to Webex ring count.
+
+    CUCM stores call forward no answer timer in seconds.
+    Webex uses ring count: divide by 6, round up, clamp to 2-20.
+    """
+    if duration_ms is None:
+        return None
+    try:
+        val = int(duration_ms)
+    except (ValueError, TypeError):
+        return None
+    if val <= 0:
+        return None
+    rings = math.ceil(val / 6)
+    return max(2, min(20, rings))
+
+
+class CallForwardingMapper(Mapper):
+    """Map CUCM per-line call forwarding to Webex per-person call forwarding.
+
+    Tier 2 expansion: adds CanonicalCallForwarding objects and
+    FORWARDING_LOSSY decisions for CUCM-only variants.
+    """
+
+    name = "call_forwarding_mapper"
+    depends_on = ["user_mapper", "line_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+
+        # Iterate phones (which contain enriched line entries)
+        for phone_data in store.get_objects("phone"):
+            phone_id = phone_data["canonical_id"]
+            state = phone_data.get("pre_migration_state") or {}
+            lines = state.get("lines", [])
+            if not lines:
+                continue
+
+            # Resolve owner user via cross-ref
+            user_refs = store.find_cross_refs(phone_id, "device_owned_by_user")
+            if not user_refs:
+                continue
+            user_id = user_refs[0]
+
+            # Check if we already created forwarding for this user (multi-device)
+            user_name = user_id.split(":", 1)[-1]
+            existing = store.get_object(f"call_forwarding:{user_name}")
+            if existing:
+                continue
+
+            # Use primary line (index 1 or first line)
+            primary_line = self._get_primary_line(lines)
+            if not primary_line:
+                continue
+
+            # Build canonical call forwarding
+            cf = self._build_call_forwarding(store, user_id, phone_data, primary_line)
+            store.upsert_object(cf)
+            result.objects_created += 1
+
+            # Write cross-ref
+            store.add_cross_ref(user_id, cf.canonical_id, "user_has_call_forwarding")
+
+            # Check for lossy CUCM-only variants
+            lossy_variants = self._detect_lossy_variants(primary_line)
+            if lossy_variants:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FORWARDING_LOSSY,
+                    severity="LOW",
+                    summary=(
+                        f"User '{user_name}' has {len(lossy_variants)} "
+                        f"CUCM-only forwarding variant(s): {', '.join(lossy_variants)}"
+                    ),
+                    context={
+                        "user_id": user_id,
+                        "lossy_variants": lossy_variants,
+                    },
+                    options=[
+                        accept_option(f"Accept loss of {len(lossy_variants)} CUCM-only forwarding variant(s)"),
+                        skip_option("Skip call forwarding migration for this user"),
+                    ],
+                    affected_objects=[user_id, cf.canonical_id],
+                )
+                result.decisions.append(decision)
+
+        return result
+
+    def _get_primary_line(self, lines: list | dict) -> dict | None:
+        """Get the primary line (index 1) from a phone's line list or dict."""
+        if not lines:
+            return None
+        # lines may be a list or a dict (integer-keyed) depending on AXL normalization
+        if isinstance(lines, dict):
+            # Integer-keyed dict: try key 1 or "1"
+            first = lines.get(1) or lines.get("1")
+            return first if isinstance(first, dict) else None
+        # List form
+        for line in lines:
+            if isinstance(line, dict):
+                idx = line.get("index")
+                if str(idx) == "1":
+                    return line
+        # Fallback: first line
+        first = lines[0]
+        return first if isinstance(first, dict) else None
+
+    def _build_call_forwarding(
+        self,
+        store: MigrationStore,
+        user_id: str,
+        phone_data: dict,
+        line: dict,
+    ) -> CanonicalCallForwarding:
+        """Build a CanonicalCallForwarding from a phone's primary line."""
+        user_name = user_id.split(":", 1)[-1]
+        prov = extract_provenance(phone_data)
+
+        # CFA (Call Forward All)
+        cfa = line.get("callForwardAll") or {}
+        # CFB (Call Forward Busy)
+        cfb = line.get("callForwardBusy") or {}
+        # CFNA (Call Forward No Answer)
+        cfna = line.get("callForwardNoAnswer") or {}
+        # CUCM-only variants (preserved for decision context)
+        cfb_int = line.get("callForwardBusyInt") or {}
+        cfna_int = line.get("callForwardNoAnswerInt") or {}
+        cfnc = line.get("callForwardNoCoverage") or {}
+        cfnc_int = line.get("callForwardNoCoverageInt") or {}
+        cff = line.get("callForwardOnFailure") or {}
+        cfnr = line.get("callForwardNotRegistered") or {}
+        cfnr_int = line.get("callForwardNotRegisteredInt") or {}
+
+        return CanonicalCallForwarding(
+            canonical_id=f"call_forwarding:{user_name}",
+            provenance=prov,
+            status=MigrationStatus.ANALYZED,
+            user_canonical_id=user_id,
+            # CFA
+            always_enabled=bool(cfa.get("destination") or cfa.get("forwardToVoiceMail") in ("true", True)),
+            always_destination=cfa.get("destination") or None,
+            always_to_voicemail=cfa.get("forwardToVoiceMail") in ("true", True),
+            # CFB
+            busy_enabled=bool(cfb.get("destination") or cfb.get("forwardToVoiceMail") in ("true", True)),
+            busy_destination=cfb.get("destination") or None,
+            busy_to_voicemail=cfb.get("forwardToVoiceMail") in ("true", True),
+            # CFNA
+            no_answer_enabled=bool(cfna.get("destination") or cfna.get("forwardToVoiceMail") in ("true", True)),
+            no_answer_destination=cfna.get("destination") or None,
+            no_answer_to_voicemail=cfna.get("forwardToVoiceMail") in ("true", True),
+            no_answer_ring_count=_duration_to_rings(cfna.get("duration")),
+            # CUCM-only (preserved in canonical for reporting)
+            busy_internal_enabled=_is_forwarding_active(cfb_int),
+            busy_internal_destination=cfb_int.get("destination") or None,
+            no_answer_internal_enabled=_is_forwarding_active(cfna_int),
+            no_answer_internal_destination=cfna_int.get("destination") or None,
+            no_coverage_enabled=_is_forwarding_active(cfnc) or _is_forwarding_active(cfnc_int),
+            no_coverage_destination=cfnc.get("destination") or cfnc_int.get("destination") or None,
+            on_failure_enabled=_is_forwarding_active(cff),
+            on_failure_destination=cff.get("destination") or None,
+            not_registered_enabled=_is_forwarding_active(cfnr) or _is_forwarding_active(cfnr_int),
+            not_registered_destination=cfnr.get("destination") or cfnr_int.get("destination") or None,
+        )
+
+    def _detect_lossy_variants(self, line: dict) -> list[str]:
+        """Detect CUCM-only forwarding variants that are actively configured."""
+        lossy = []
+        for variant in _LOSSY_VARIANTS:
+            fwd = line.get(variant)
+            if _is_forwarding_active(fwd):
+                lossy.append(variant)
+        return lossy