wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/mappers/snr_mapper.py

@@ -0,0 +1,201 @@
+"""SNRMapper — CUCM Remote Destinations → Webex Single Number Reach.
+
+Reads remote_destination objects from the store, groups by user,
+resolves user ownership, normalizes phone numbers to E.164, and
+produces CanonicalSingleNumberReach objects.
+
+Timer controls (answerTooSoon, answerTooLate) have no Webex equivalent
+and produce SNR_LOSSY decisions.
+
+(from tier2-enterprise-expansion.md §4)
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalSingleNumberReach,
+    DecisionType,
+    MigrationStatus,
+    MapperResult,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    extract_provenance,
+    manual_option,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# CUCM default timer values (milliseconds) — non-default triggers SNR_LOSSY
+CUCM_DEFAULT_ANSWER_TOO_SOON = 1500
+CUCM_DEFAULT_ANSWER_TOO_LATE = 19000
+
+# Basic E.164 check: starts with + and has 8-15 digits
+_E164_RE = re.compile(r"^\+\d{8,15}$")
+
+
+def _is_e164(number: str) -> bool:
+    """Check if a number looks like E.164 format."""
+    return bool(_E164_RE.match(number))
+
+
+def _safe_int(val: Any, default: int | None = None) -> int | None:
+    """Safely coerce a value to int."""
+    if val is None:
+        return default
+    try:
+        return int(val)
+    except (ValueError, TypeError):
+        return default
+
+
+class SNRMapper(Mapper):
+    """Map CUCM Remote Destinations to Webex Single Number Reach.
+
+    Tier 2 expansion: produces CanonicalSingleNumberReach objects and
+    SNR_LOSSY decisions for CUCM-only timer controls.
+    """
+
+    name = "snr_mapper"
+    depends_on = ["user_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+
+        # Group remote destinations by owner user ID
+        user_dests: dict[str, list[dict[str, Any]]] = {}
+        rd_count = 0
+        for rd in store.get_objects("remote_destination"):
+            rd_count += 1
+            state = rd.get("pre_migration_state") or {}
+            owner = state.get("ownerUserId") or ""
+            if not owner:
+                continue
+            user_dests.setdefault(owner, []).append(rd)
+
+        logger.info(
+            "SNR mapping: %d remote_destination objects, %d unique owners",
+            rd_count, len(user_dests),
+        )
+
+        for owner_userid, rd_list in user_dests.items():
+            user_cid = f"user:{owner_userid}"
+            if not store.get_object(user_cid):
+                continue
+
+            # Build numbers list
+            numbers = []
+            lossy_timers = []
+            invalid_numbers = []
+            any_enabled = False
+
+            for rd in rd_list:
+                state = rd.get("pre_migration_state") or {}
+                dest = state.get("destination") or ""
+                name = state.get("name") or ""
+                is_mobile = str(state.get("isMobilePhone") or "").lower() in ("true", "t", "1")
+                mobile_connect = str(state.get("enableMobileConnect") or "").lower() in ("true", "t", "1")
+
+                if mobile_connect:
+                    any_enabled = True
+
+                # Timer values
+                too_soon = _safe_int(state.get("answerTooSoonTimer"), CUCM_DEFAULT_ANSWER_TOO_SOON)
+                too_late = _safe_int(state.get("answerTooLateTimer"), CUCM_DEFAULT_ANSWER_TOO_LATE)
+
+                # Check for non-default timers
+                if too_soon != CUCM_DEFAULT_ANSWER_TOO_SOON or too_late != CUCM_DEFAULT_ANSWER_TOO_LATE:
+                    lossy_timers.append({
+                        "destination": dest,
+                        "answer_too_soon": too_soon,
+                        "answer_too_late": too_late,
+                    })
+
+                # Validate number format
+                if dest and not _is_e164(dest):
+                    if len(dest) >= 10 and dest.isdigit():
+                        # Could be national format — flag for admin validation
+                        invalid_numbers.append(dest)
+
+                label = "Mobile" if is_mobile else name
+                numbers.append({
+                    "phone_number": dest,
+                    "enabled": mobile_connect,
+                    "name": label,
+                    "answer_confirmation": False,
+                    "cucm_answer_too_soon": too_soon,
+                    "cucm_answer_too_late": too_late,
+                })
+
+            if not numbers:
+                continue
+
+            # Build canonical SNR object
+            prov = extract_provenance(rd_list[0])
+            snr = CanonicalSingleNumberReach(
+                canonical_id=f"single_number_reach:{owner_userid}",
+                provenance=prov,
+                status=MigrationStatus.ANALYZED,
+                user_canonical_id=user_cid,
+                enabled=any_enabled,
+                numbers=numbers,
+            )
+            store.upsert_object(snr)
+            result.objects_created += 1
+
+            # Write cross-ref
+            store.add_cross_ref(user_cid, snr.canonical_id, "user_has_snr")
+
+            # Decision: lossy timers
+            if lossy_timers:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.SNR_LOSSY,
+                    severity="LOW",
+                    summary=(
+                        f"User '{owner_userid}' has {len(lossy_timers)} Remote Destination(s) "
+                        f"with custom timer values that Webex SNR does not support"
+                    ),
+                    context={
+                        "user_id": user_cid,
+                        "lossy_timers": lossy_timers,
+                    },
+                    options=[
+                        accept_option("Accept loss — migrate numbers without timer control"),
+                        skip_option("Skip SNR migration for this user"),
+                        manual_option("Admin configures custom behavior in Webex"),
+                    ],
+                    affected_objects=[user_cid, snr.canonical_id],
+                )
+                result.decisions.append(decision)
+
+            # Decision: invalid numbers
+            if invalid_numbers:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.MISSING_DATA,
+                    severity="MEDIUM",
+                    summary=(
+                        f"User '{owner_userid}' has {len(invalid_numbers)} Remote Destination(s) "
+                        f"with non-E.164 numbers"
+                    ),
+                    context={
+                        "user_id": user_cid,
+                        "invalid_numbers": invalid_numbers,
+                    },
+                    options=[
+                        manual_option("Admin provides valid E.164 numbers"),
+                        skip_option("Skip these entries"),
+                    ],
+                    affected_objects=[user_cid, snr.canonical_id],
+                )
+                result.decisions.append(decision)
+
+        return result

wxcli/migration/transform/mappers/softkey_mapper.py

@@ -0,0 +1,205 @@
+"""SoftkeyMapper: CUCM Softkey Templates → Webex PSK config (9800/8875).
+
+Maps CUCM per-call-state softkey assignments to Webex Programmable Softkey
+(PSK) keywords and per-state key lists. Only actionable for 9800/8875
+phones (PhoneOS with PSK support). Classic MPP phones produce report
+entries only (is_psk_target=False).
+
+(from tier2-phase2-phone-config-design.md §4.3)
+
+Cross-ref reads:
+    phone_uses_softkey_template  (Phone → SoftkeyTemplate)  — usage + model
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalSoftkeyConfig,
+    MapperResult,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    extract_provenance,
+)
+
+logger = logging.getLogger(__name__)
+
+# CUCM softkey name → Webex PSK keyword (None = unmappable)
+CUCM_SOFTKEY_TO_PSK: dict[str, str | None] = {
+    "Trnsfer": "xfer",
+    "Confrn": "conf",
+    "Park": "park",
+    "Pickup": "pickup",
+    "GPickUp": "gpickup",
+    "Hold": "hold",
+    "Resume": "resume",
+    "EndCall": "endcall",
+    "NewCall": "newcall",
+    "Redial": "redial",
+    "DND": "dnd",
+    "Barge": "bridgein",
+    "Join": "join",
+    "LiveRcd": "crdstart",
+    "CfwdAll": "cfwd",
+    "Unpark": "unpark",
+    "HLog": "acd_login",
+    "Answer": "answer",
+    # Unmappable
+    "CallBack": None,
+    "iDivert": None,
+    "QRT": None,
+    "MeetMe": None,
+    "Mobility": None,
+    "cBarge": None,
+}
+
+# CUCM call state → Webex PSK state key list name
+CUCM_STATE_TO_PSK_STATE: dict[str, str | None] = {
+    "onHook": "idle",
+    "offHook": "offHook",
+    "ringIn": "ringing",
+    "ringOut": "progressing",  # API key is "progressingKeyList", not "processingKeyList"
+    "connected": "connected",
+    "onHold": "hold",
+    "sharedActive": "sharedActive",
+    "sharedHeld": "sharedHeld",
+    "connectedTransfer": "startTransfer",
+    "connectedConference": "startConference",
+    "transition": "releasing",
+    # Unmappable
+    "remoteInUse": None,
+    "park": None,
+}
+
+# 9800/8875 model number substrings that indicate PSK capability
+from wxcli.migration.phone_models import PHONEOS_MODEL_NUMBERS as _PSK_MODEL_NUMBERS
+
+
+def _is_psk_capable_model(model: str | None) -> bool:
+    """Check if a phone model supports Programmable Softkeys (PSK)."""
+    if not model:
+        return False
+    for num in _PSK_MODEL_NUMBERS:
+        if num in model:
+            return True
+    return False
+
+
+class SoftkeyMapper(Mapper):
+    """Maps CUCM Softkey Templates to Webex PSK config or report flags."""
+
+    name = "softkey_mapper"
+    depends_on = ["device_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+
+        for tmpl_data in store.get_objects("softkey_template"):
+            tmpl_id = tmpl_data["canonical_id"]
+            state = tmpl_data.get("pre_migration_state") or {}
+            name = state.get("name", tmpl_id.split(":", 1)[-1])
+            call_states = state.get("call_states", {})
+
+            # Count phones and determine PSK eligibility
+            phone_refs = [r["from_id"] for r in store.get_cross_refs(to_id=tmpl_id, relationship="phone_uses_softkey_template")]
+            phones_using = len(phone_refs)
+
+            has_psk_phone = False
+            for phone_id in phone_refs:
+                phone = store.get_object(phone_id)
+                if phone:
+                    # Model may be at top level of raw phone dict OR in pre_migration_state
+                    model = phone.get("model")
+                    if not model:
+                        phone_state = phone.get("pre_migration_state") or {}
+                        model = phone_state.get("model") or phone_state.get("cucm_product")
+                    if _is_psk_capable_model(model):
+                        has_psk_phone = True
+                        break
+
+            # Map softkeys per call state
+            psk_slot_counter = 0
+            psk_mappings: list[dict[str, Any]] = []
+            state_key_lists: dict[str, list[str]] = {}
+            unmapped: list[dict[str, Any]] = []
+
+            for cucm_state, softkeys in call_states.items():
+                psk_state = CUCM_STATE_TO_PSK_STATE.get(cucm_state)
+                if psk_state is None:
+                    # Unmappable state — flag all softkeys in it
+                    for sk in softkeys:
+                        unmapped.append({"cucm_name": sk, "call_state": cucm_state})
+                    continue
+
+                mapped_keywords = []
+                for sk_name in softkeys:
+                    psk_keyword = CUCM_SOFTKEY_TO_PSK.get(sk_name)
+                    if psk_keyword is None and sk_name not in CUCM_SOFTKEY_TO_PSK:
+                        # Unknown softkey — treat as unmapped
+                        psk_keyword = None
+                    if psk_keyword is None:
+                        unmapped.append({"cucm_name": sk_name, "call_state": cucm_state})
+                    else:
+                        mapped_keywords.append(psk_keyword)
+                        if has_psk_phone and psk_slot_counter < 16:
+                            psk_slot_counter += 1
+                            psk_mappings.append({
+                                "psk_slot": f"PSK{psk_slot_counter}",
+                                "keyword": psk_keyword,
+                            })
+
+                if mapped_keywords:
+                    state_key_lists[psk_state] = mapped_keywords
+
+            # Per-device fan-out: create one CanonicalSoftkeyConfig per PSK-capable phone.
+            # These per-device objects (is_psk_target=True) drive the execute handler.
+            per_device_count = 0
+            if has_psk_phone and psk_mappings:
+                for phone_id in phone_refs:
+                    phone = store.get_object(phone_id)
+                    if not phone:
+                        continue
+                    model = phone.get("model")
+                    if not model:
+                        phone_state = phone.get("pre_migration_state") or {}
+                        model = phone_state.get("model") or phone_state.get("cucm_product")
+                    if not _is_psk_capable_model(model):
+                        continue
+                    phone_state = phone.get("pre_migration_state") or {}
+                    device_name = phone_state.get("name") or phone_id.replace("phone:", "")
+                    per_device_config = CanonicalSoftkeyConfig(
+                        canonical_id=f"softkey_config:device:{device_name}",
+                        provenance=extract_provenance(tmpl_data),
+                        status=MigrationStatus.ANALYZED,
+                        cucm_template_name=name,
+                        is_psk_target=True,
+                        device_canonical_id=f"device:{device_name}",
+                        psk_mappings=psk_mappings,
+                        state_key_lists=state_key_lists,
+                        unmapped_softkeys=unmapped,
+                        phones_using=1,
+                    )
+                    store.upsert_object(per_device_config)
+                    per_device_count += 1
+
+            # Template-level object: report-only (is_psk_target=False).
+            # Retains PSK mapping data for assessment; execution handled by per-device objects.
+            config = CanonicalSoftkeyConfig(
+                canonical_id=f"softkey_config:{name}",
+                provenance=extract_provenance(tmpl_data),
+                status=MigrationStatus.ANALYZED,
+                cucm_template_name=name,
+                is_psk_target=False,
+                psk_mappings=psk_mappings if has_psk_phone else [],
+                state_key_lists=state_key_lists,
+                unmapped_softkeys=unmapped,
+                phones_using=phones_using,
+            )
+            store.upsert_object(config)
+            result.objects_created += 1 + per_device_count
+
+        return result

wxcli/migration/transform/mappers/user_mapper.py

@@ -0,0 +1,264 @@
+"""User mapper: CUCM End Users -> Webex Calling People.
+
+Maps CUCM end users to CanonicalUser objects with resolved email, location,
+and primary extension. Email resolution uses mailid with userid as fallback.
+Location resolution follows the cross-ref chain:
+    user -> user_has_device -> device -> device_in_pool -> device_pool
+    -> device_pool_to_location -> location
+
+(from 03b-transform-mappers.md §2, user_mapper)
+
+Cross-ref reads:
+    user_has_device        (User -> Device)
+    user_has_primary_dn    (User -> DN)
+    device_in_pool         (Device -> DevicePool)
+    device_pool_to_location (DevicePool -> Location)
+
+Does NOT produce: DUPLICATE_USER, EXTENSION_CONFLICT (analyzer-owned)
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalUser,
+    DecisionType,
+    MapperResult,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    decision_to_store_dict,
+    extract_provenance,
+    manual_option,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# Simple email validation pattern
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+class UserMapper(Mapper):
+    """Maps CUCM End Users to Webex Calling People.
+
+    (from 03b-transform-mappers.md §2)
+    """
+
+    name = "user_mapper"
+    depends_on = ["location_mapper"]
+
+    def __init__(
+        self,
+        create_method: str = "people_api",
+        include_phoneless_users: bool = False,
+        use_device_dn_as_extension: bool = True,
+    ) -> None:
+        """
+        Args:
+            create_method: "scim" or "people_api" — execution strategy
+                (from 03b-transform-mappers.md §2: execution strategy note)
+            include_phoneless_users: If True, map users without phones.
+                (from 03b-transform-mappers.md §2: edge case — users with no phone)
+            use_device_dn_as_extension: If True, fall back to device line 1 DN
+                when primaryExtension is not set on the user record.
+        """
+        self.create_method = create_method
+        self.include_phoneless_users = include_phoneless_users
+        self.use_device_dn_as_extension = use_device_dn_as_extension
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        """Read normalized CUCM users and produce CanonicalUser objects."""
+        result = MapperResult()
+
+        for user_data in store.get_objects("user"):
+            user_id = user_data["canonical_id"]
+            state = user_data.get("pre_migration_state") or {}
+
+            # --- Email resolution ---
+            # (from 03b-transform-mappers.md §2: mailid primary, userid fallback)
+            emails = user_data.get("emails", [])
+            cucm_mailid = user_data.get("cucm_mailid")
+            cucm_userid = user_data.get("cucm_userid", "")
+
+            if not emails:
+                if cucm_mailid and _EMAIL_RE.match(cucm_mailid):
+                    emails = [cucm_mailid.lower()]
+                elif cucm_userid and _EMAIL_RE.match(cucm_userid):
+                    emails = [cucm_userid.lower()]
+
+            if not emails:
+                # No email available
+                # (from 03b-transform-mappers.md §2: MISSING_DATA if no mailid and userid not email)
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.MISSING_DATA,
+                    severity="HIGH",
+                    summary=f"User '{cucm_userid}' has no email address (mailid empty, userid not email format)",
+                    context={
+                        "user_id": user_id,
+                        "cucm_userid": cucm_userid,
+                        "cucm_mailid": cucm_mailid,
+                    },
+                    options=[
+                        manual_option("Admin provides email address"),
+                        skip_option("User not migrated to Webex Calling"),
+                    ],
+                    affected_objects=[user_id],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+                continue
+
+            # --- Device and location resolution ---
+            # Chain: user -> user_has_device -> device -> device_in_pool -> pool -> device_pool_to_location -> location
+            device_refs = store.find_cross_refs(user_id, "user_has_device")
+            location_id = None
+
+            if device_refs:
+                # Try each device until we find one with a location chain
+                for dev_id in device_refs:
+                    loc_id = store.resolve_chain(
+                        dev_id, "device_in_pool", "device_pool_to_location"
+                    )
+                    if loc_id:
+                        location_id = loc_id
+                        break
+
+            if not location_id and not self.include_phoneless_users:
+                # No device -> no location
+                # (from 03b-transform-mappers.md §2: MISSING_DATA if no device/location)
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.MISSING_DATA,
+                    severity="MEDIUM",
+                    summary=f"User '{cucm_userid}' has no associated phone — cannot resolve Webex location",
+                    context={
+                        "user_id": user_id,
+                        "cucm_userid": cucm_userid,
+                        "reason": "no_device_no_location",
+                    },
+                    options=[
+                        manual_option("Admin assigns user to a location manually"),
+                        skip_option("User not migrated to Webex Calling"),
+                    ],
+                    affected_objects=[user_id],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+                continue
+
+            # --- Extension resolution ---
+            # (from 03b-transform-mappers.md §2: primary DN, bare extension without routing prefix)
+            extension = user_data.get("extension")
+            primary_dn_refs = store.find_cross_refs(user_id, "user_has_primary_dn")
+            if primary_dn_refs:
+                dn_id = primary_dn_refs[0]
+                # DN IDs are formatted as "dn:pattern:partition"
+                parts = dn_id.split(":", 2)
+                if len(parts) >= 2:
+                    extension = parts[1]
+
+            # --- Device line 1 DN fallback ---
+            # When CUCM has no primaryExtension set on the user record,
+            # fall back to the DN on line 1 (ordinal 0) of the user's first device.
+            if extension is None and self.use_device_dn_as_extension and device_refs:
+                # Collect ALL line-1 DN candidates across devices so we can warn
+                # on genuine multi-device conflicts. We still pick the first
+                # candidate (legacy selection behaviour) — the warning just
+                # surfaces ambiguity for operator review.
+                line1_candidates: list[str] = []
+                for dev_id in device_refs:
+                    dn_xrefs = store.get_cross_refs(
+                        from_id=dev_id, relationship="device_has_dn"
+                    )
+                    for xref in dn_xrefs:
+                        if xref.get("ordinal") == 0:
+                            dn_target = xref["to_id"]
+                            # DN IDs are formatted as "dn:pattern:partition"
+                            dn_parts = dn_target.split(":", 2)
+                            if len(dn_parts) >= 2:
+                                line1_candidates.append(dn_parts[1])
+                            break
+                if line1_candidates:
+                    extension = line1_candidates[0]
+                    distinct = sorted(set(line1_candidates))
+                    if len(distinct) > 1:
+                        logger.warning(
+                            "Multiple devices report different line-1 DNs for %s: "
+                            "candidates=%s picked=%s (legacy selection: first device). "
+                            "Operator should verify the correct primary extension.",
+                            user_id,
+                            distinct,
+                            extension,
+                        )
+
+            # --- Build display name ---
+            first_name = user_data.get("first_name")
+            last_name = user_data.get("last_name")
+            display_name = user_data.get("display_name")
+            if not display_name:
+                name_parts = [p for p in [first_name, last_name] if p]
+                display_name = " ".join(name_parts) or None
+
+            # --- SQL-extracted user detection ---
+            # Users extracted via SQL fallback have limited fields.
+            # (from Phase 04 corrections: pre_migration_state.extracted_via_sql = true)
+            sql_extracted = state.get("extracted_via_sql", False)
+            if sql_extracted:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.MISSING_DATA,
+                    severity="LOW",
+                    summary=f"User '{cucm_userid}' was extracted via SQL fallback — limited field data available",
+                    context={
+                        "user_id": user_id,
+                        "cucm_userid": cucm_userid,
+                        "reason": "sql_extracted",
+                        "missing_fields": ["cucm_css", "cucm_voicemail_profile", "selfService", "userLocale"],
+                    },
+                    options=[
+                        manual_option("Admin verifies and supplements user data"),
+                        accept_option("Proceed with limited data — CSS and voicemail settings will not be migrated"),
+                    ],
+                    affected_objects=[user_id],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+
+            # --- Build CanonicalUser ---
+            user_obj = CanonicalUser(
+                canonical_id=user_id,
+                provenance=extract_provenance(user_data),
+                status=MigrationStatus.ANALYZED,
+                emails=emails,
+                first_name=first_name,
+                last_name=last_name,
+                display_name=display_name,
+                location_id=location_id,
+                extension=extension,
+                department=user_data.get("department"),
+                title=user_data.get("title"),
+                create_method=self.create_method,
+                calling_data=True,
+                cucm_manager_user_id=user_data.get("cucm_manager_user_id"),
+                cucm_userid=cucm_userid,
+                cucm_mailid=cucm_mailid,
+            )
+
+            store.upsert_object(user_obj)
+            result.objects_updated += 1
+
+            # Fix 8: Write user_in_location cross-ref for dependency graph
+            if location_id:
+                store.add_cross_ref(user_id, location_id, "user_in_location")
+
+        return result
+
+