midpoint-cli 1.6.0.dev3__py3-none-any.whl

midpoint_cli/client/objects.py

@@ -0,0 +1,814 @@
+import itertools
+import re
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import Enum
+from typing import TypeVar
+from xml.etree.ElementTree import Element
+
+from rich.console import Group
+from rich.table import Table
+from rich.text import Text
+from unidecode import unidecode
+
+from midpoint_cli.client.constants import AUDIT_NS, COMMON_NS, ResultStatus, TaskExecutionState
+from midpoint_cli.client.server_version import MidpointVersion, task_uses_execution_state
+
+
+def safe_get_text(element: Element | None, default: str = '') -> str:
+    """Safely get text from an XML element, returning default if element is None."""
+    return element.text if element is not None and element.text is not None else default
+
+
+def safe_get_int(element: Element | None, default: int = 0) -> int:
+    """Safely get integer from an XML element text, returning default if element is None or text is not a valid int."""
+    if element is None or element.text is None:
+        return default
+    try:
+        return int(element.text)
+    except (ValueError, TypeError):
+        return default
+
+
+namespaces = {
+    'c': COMMON_NS,
+    'aud': AUDIT_NS,
+}
+
+
+_T = TypeVar('_T', bound='MidpointObject')
+
+
+class MidpointObject(OrderedDict):
+    """A Midpoint object parsed for display: an ordered mapping of column names to values.
+
+    Every subclass sets at least ``OID`` and ``Name``; the other keys are the columns of its
+    listing, in display order.
+    """
+
+    def get_oid(self) -> str | None:
+        """The object's OID as a string, or None when the parsed object has none."""
+        oid = self.get('OID')
+        return str(oid) if oid is not None else None
+
+    def get_name(self) -> str | None:
+        """The object's name (``c:name``) as a string, or None when it has none."""
+        name = self.get('Name')
+        return str(name) if name is not None else None
+
+    @classmethod
+    def error_stub(cls: type[_T], oid: str) -> _T:
+        """A placeholder for an object of this class that could not be read.
+
+        Only the OID is set, with ``Status`` 'fetch error', so a listing shows the failure in place of the object.
+        """
+        obj = cls.__new__(cls)
+        OrderedDict.__init__(obj)
+        obj['OID'] = oid
+        obj['Status'] = 'fetch error'
+        return obj
+
+
+class MidpointObjectList(list[MidpointObject]):
+    """A list of parsed Midpoint objects, as returned by the MidpointClient listing and search methods."""
+
+    def find_object(self, search_reference) -> MidpointObject | None:
+        """The first object whose OID or name equals search_reference exactly, or None."""
+        for mp_obj in self:
+            if search_reference in [mp_obj.get_oid(), mp_obj.get_name()]:
+                return mp_obj
+
+        return None
+
+    def filter(self, queryterms: list[str]) -> 'MidpointObjectList':
+        """A new MidpointObjectList of the objects whose values contain the query terms.
+
+        Matching is case- and accent-insensitive on every value. A term prefixed with ``+`` is
+        mandatory; among the other terms at least one must match (none is needed when every
+        term is mandatory).
+        """
+        selected_objects = MidpointObjectList()
+
+        mandatory_terms = [t[1:] for t in queryterms if t.startswith('+')]
+        optional_terms = [t for t in queryterms if not t.startswith('+')]
+
+        for obj in self:
+            values = [unidecode(str(v)).casefold() for v in obj.values() if v is not None]
+
+            mandatory_match = all(any(unidecode(term).casefold() in v for v in values) for term in mandatory_terms)
+            optional_match = not optional_terms or any(
+                unidecode(term).casefold() in v for term in optional_terms for v in values
+            )
+
+            if mandatory_match and optional_match:
+                selected_objects.append(obj)
+
+        return selected_objects
+
+
+RUNNING_EXECUTION_STATES = frozenset({TaskExecutionState.RUNNING, TaskExecutionState.RUNNABLE})
+
+
+def _utc_now() -> datetime:
+    """Current time as an aware UTC datetime; isolated so tests can freeze it."""
+    return datetime.now(UTC)
+
+
+def _task_execution_state(xml_entity: Element, server_version: MidpointVersion | None) -> str:
+    """Read the task state under the name the server version uses; unknown versions try both names."""
+    if server_version is not None:
+        field = 'c:executionState' if task_uses_execution_state(server_version) else 'c:executionStatus'
+        state = xml_entity.find(field, namespaces)
+    else:
+        state = xml_entity.find('c:executionState', namespaces)
+        if state is None:
+            state = xml_entity.find('c:executionStatus', namespaces)
+    return state.text if state is not None and state.text is not None else 'n/a'
+
+
+def _task_result_status(xml_entity: Element, server_version: MidpointVersion | None) -> str:
+    """Read the result of the task's last run, empty for a task that never ran.
+
+    On every supported version this is TaskType/resultStatus. operationExecution/status is the
+    result of the last change made to the task object, not of a run, so it is only a guess kept
+    for servers whose version is unknown or older than 4.4.
+    """
+    rs = xml_entity.find('c:resultStatus', namespaces)
+    if rs is None and (server_version is None or not task_uses_execution_state(server_version)):
+        rs = xml_entity.find('c:operationExecution/c:status', namespaces)
+    return rs.text if rs is not None and rs.text is not None else ''
+
+
+def _holds_statistics(statistics: Element) -> bool:
+    return (
+        statistics.find('c:synchronization', namespaces) is not None
+        or statistics.find('c:actionsExecuted', namespaces) is not None
+    )
+
+
+def _activity_statistics(activity: Element) -> list[Element]:
+    """Statistics of an activity state, or of its child activities when it holds none itself.
+
+    A reconciliation or composite activity keeps no synchronization or action statistics of
+    its own: each child activity (resourceObjects, remainingShadows, ...) has its own, as seen
+    on Midpoint 4.8.14 and 4.10.1. Reading a parent's statistics when it has some, and its
+    children's only otherwise, never counts an item twice.
+    """
+    statistics = activity.find('c:statistics', namespaces)
+    if statistics is not None and _holds_statistics(statistics):
+        return [statistics]
+    collected: list[Element] = []
+    for child in activity.findall('c:activity', namespaces):
+        collected.extend(_activity_statistics(child))
+    return collected
+
+
+def _sum_transitions(statistics_list: list[Element]) -> list[tuple[str, str, int]]:
+    """Synchronization transitions as (from, to, count), summed over activities and outcomes.
+
+    An exclusion is listed as (reason, '', count).
+    """
+    totals: dict[tuple[str, str], int] = {}
+    for statistics in statistics_list:
+        for transition in statistics.findall('c:synchronization/c:transition', namespaces):
+            # One counter per outcome (success, failure, skip)
+            count = sum(
+                safe_get_int(c.find('c:count', namespaces)) for c in transition.findall('c:counter', namespaces)
+            )
+            keys = []
+            if transition.find('c:onSynchronizationStart', namespaces) is not None:
+                keys.append(
+                    (
+                        safe_get_text(transition.find('c:onSynchronizationStart', namespaces)),
+                        safe_get_text(transition.find('c:onSynchronizationEnd', namespaces)),
+                    )
+                )
+            if transition.find('c:exclusionReason', namespaces) is not None:
+                keys.append((safe_get_text(transition.find('c:exclusionReason', namespaces)), ''))
+            for key in keys:
+                totals[key] = totals.get(key, 0) + count
+    return [(start, end, count) for (start, end), count in totals.items()]
+
+
+def _sum_actions(statistics_list: list[Element]) -> list[tuple[str, str, int, int]]:
+    """Executed actions as (object type, operation, successes, failures), summed over activities.
+
+    Only objectActionsEntry (all actions) is read: resultingObjectActionsEntry summarises the
+    same actions per object, so counting both would count them twice.
+    """
+    totals: dict[tuple[str, str], tuple[int, int]] = {}
+    for statistics in statistics_list:
+        for entry in statistics.findall('c:actionsExecuted/c:objectActionsEntry', namespaces):
+            key = (
+                safe_get_text(entry.find('c:objectType', namespaces)),
+                safe_get_text(entry.find('c:operation', namespaces)),
+            )
+            success, failure = totals.get(key, (0, 0))
+            totals[key] = (
+                success + safe_get_int(entry.find('c:totalSuccessCount', namespaces)),
+                failure + safe_get_int(entry.find('c:totalFailureCount', namespaces)),
+            )
+    return [(object_type, operation, s, f) for (object_type, operation), (s, f) in totals.items()]
+
+
+# Task detail tables follow the look of the list tables (prompt.console.create_table).
+_TABLE_BORDER_STYLE = 'blue'
+_TABLE_HEADER_STYLE = 'bold cyan'
+# Colors of a task result status (OperationResultStatusType values).
+_RESULT_STATUS_STYLES = {
+    ResultStatus.SUCCESS: 'green',
+    ResultStatus.WARNING: 'yellow',
+    ResultStatus.PARTIAL_ERROR: 'yellow',
+    ResultStatus.HANDLED_ERROR: 'yellow',
+    ResultStatus.FATAL_ERROR: 'bold red',
+    ResultStatus.IN_PROGRESS: 'cyan',
+}
+
+
+# Timestamp elements of a task's last run, by preference: the names vary across Midpoint versions.
+_TASK_START_FIELDS = ('c:lastRunStartTimestamp', 'c:startTimestamp')
+_TASK_END_FIELDS = ('c:lastRunFinishTimestamp', 'c:endTimestamp', 'c:completionTimestamp')
+
+
+def _first_text(xml_entity: Element, paths: tuple[str, ...]) -> str | None:
+    """The text of the first of paths present with a non-empty text in xml_entity, or None."""
+    for path in paths:
+        elem = xml_entity.find(path, namespaces)
+        if elem is not None and elem.text:
+            return elem.text
+    return None
+
+
+class MidpointTask(MidpointObject):
+    def __init__(self, xml_entity: Element, server_version: MidpointVersion | None = None):
+        super().__init__()
+        # The keys are set in display order: identity, states, progress, then Duration.
+        self['OID'] = xml_entity.attrib['oid']
+        name_element = xml_entity.find('c:name', namespaces)
+        self['Name'] = name_element.text if name_element is not None else None
+        self['Execution Status'] = _task_execution_state(xml_entity, server_version)
+        self['Result Status'] = _task_result_status(xml_entity, server_version)
+        self._parse_progress(xml_entity)
+
+        # taskIdentifier is the join key into audit records — distinct from OID,
+        # regenerated per run. Not surfaced in the dict to keep the table view tidy.
+        task_identifier_el = xml_entity.find('c:taskIdentifier', namespaces)
+        self._task_identifier: str | None = task_identifier_el.text if task_identifier_el is not None else None
+
+        self._parse_timestamps(xml_entity)
+        self._parse_statistics(xml_entity)
+
+    def _parse_progress(self, xml_entity: Element) -> None:
+        """Set Progress and Expected Total, empty when the task does not report them."""
+        progress = xml_entity.find('c:progress', namespaces)
+        self['Progress'] = progress.text if progress is not None else ''
+        total = xml_entity.find('c:expectedTotal', namespaces)
+        self['Expected Total'] = total.text if total is not None else ''
+
+    def _parse_statistics(self, xml_entity: Element) -> None:
+        """Collect the transitions and actions of the task statistics, summed over the activities that hold them."""
+        root_activity = xml_entity.find('c:activityState/c:activity', namespaces)
+        statistics = _activity_statistics(root_activity) if root_activity is not None else []
+        self._transitions: list[tuple[str, str, int]] = _sum_transitions(statistics)
+        self._actions: list[tuple[str, str, int, int]] = _sum_actions(statistics)
+
+    def _parse_timestamps(self, xml_entity: Element) -> None:
+        """Read the start and end of the last run, and set Duration from them."""
+        start_timestamp = _first_text(xml_entity, _TASK_START_FIELDS)
+        end_timestamp = _first_text(xml_entity, _TASK_END_FIELDS)
+
+        # Store the parsed start datetime for use by get_start_time()
+        self._start_datetime: datetime | None = None
+        if start_timestamp:
+            self._start_datetime = self._parse_datetime(start_timestamp)
+
+        # Calculate duration if we have both timestamps
+        duration = self._calculate_duration(start_timestamp, end_timestamp)
+        self['Duration'] = duration if duration else ''
+
+    def _parse_datetime(self, timestamp: str) -> datetime | None:
+        """Parse a timestamp string into a datetime object."""
+        if not timestamp:
+            return None
+
+        # Parse timestamps - handle both with and without microseconds
+        timestamp_formats = [
+            '%Y-%m-%dT%H:%M:%S.%fZ',
+            '%Y-%m-%dT%H:%M:%SZ',
+            '%Y-%m-%dT%H:%M:%S.%f%z',
+            '%Y-%m-%dT%H:%M:%S%z',
+        ]
+
+        for fmt in timestamp_formats:
+            try:
+                return datetime.strptime(timestamp, fmt)
+            except ValueError:
+                continue
+
+        return None
+
+    def _calculate_duration(self, start_timestamp: str | None, end_timestamp: str | None) -> str | None:
+        """Calculate duration between two timestamps, or elapsed time for running tasks"""
+        if not start_timestamp:
+            return None
+
+        try:
+            start_dt = self._parse_datetime(start_timestamp)
+            if not start_dt:
+                return None
+
+            end_dt = self._parse_datetime(end_timestamp) if end_timestamp else None
+            running = self._is_running()
+
+            # Use the end timestamp when it belongs to the current run. A running task may still
+            # carry the finish timestamp of a previous run, which is earlier than the current start.
+            if end_dt is not None and (end_dt >= start_dt or not running):
+                return self._format_duration((end_dt - start_dt).total_seconds())
+
+            # Running task without a usable end timestamp: elapsed time since start
+            if running:
+                now = _utc_now()
+                if start_dt.tzinfo is None or start_dt.tzinfo.utcoffset(start_dt) is None:
+                    now = now.replace(tzinfo=None)
+                return self._format_duration((now - start_dt).total_seconds())
+
+        except (ValueError, TypeError):
+            pass
+
+        return None
+
+    def _is_running(self) -> bool:
+        """Whether the execution state denotes a running task (Midpoint sends lowercase values)."""
+        status = self.get('Execution Status')
+        return isinstance(status, str) and status.lower() in RUNNING_EXECUTION_STATES
+
+    def _format_duration(self, seconds: float) -> str:
+        """Format duration in a human-readable format"""
+        if seconds < 0:
+            return '0s'
+
+        hours = int(seconds // 3600)
+        minutes = int((seconds % 3600) // 60)
+        remaining_seconds = int(seconds % 60)
+
+        if hours > 0:
+            return f'{hours}h {minutes}m {remaining_seconds}s'
+        elif minutes > 0:
+            return f'{minutes}m {remaining_seconds}s'
+        else:
+            return f'{remaining_seconds}s'
+
+    def get_task_identifier(self) -> str | None:
+        """Return the task's `taskIdentifier`, the field stamped on every audit event the task emits."""
+        return self._task_identifier
+
+    def get_start_time(self) -> datetime | None:
+        """Get the task's start time as a datetime object, if available."""
+        return getattr(self, '_start_datetime', None)
+
+    def get_transitions(self) -> list[tuple[str, str, int]]:
+        """Synchronization transitions in the task statistics, as (from situation, to situation, count) tuples.
+
+        Counts are summed over the task's activities and outcomes; an exclusion is listed as
+        (reason, '', count). Empty when the task holds no statistics.
+        """
+        return self._transitions
+
+    def get_actions(self) -> list[tuple[str, str, int, int]]:
+        """Executed actions in the task statistics, as (object type, operation, successes, failures) tuples.
+
+        Counts are summed over the task's activities. Empty when the task holds no statistics.
+        """
+        return self._actions
+
+    def get_success_count(self) -> int:
+        """Get the total count of successful operations from task statistics."""
+        return sum(count_success for _, _, count_success, _ in self._actions)
+
+    def get_failure_count(self) -> int:
+        """Get the total count of failed operations from task statistics."""
+        return sum(count_failure for _, _, _, count_failure in self._actions)
+
+    def get_full_description(self):
+        """Return a Rich renderable group containing task details as formatted tables.
+
+        Styled like the list tables (blue borders, bold cyan headers); the result status is
+        colored by outcome and failure counts stand out. Colors only, so the text is the
+        same on a terminal and in a pipe.
+        """
+        # Task Properties Table
+        properties_table = Table(title='Task Properties', show_header=False, border_style=_TABLE_BORDER_STYLE)
+        properties_table.add_column('Property', style='bold cyan', no_wrap=True)
+        properties_table.add_column('Value', style='white')
+        for key, value in self.items():
+            style = _RESULT_STATUS_STYLES.get(str(value)) if key == 'Result Status' else None
+            properties_table.add_row(Text(key), Text(str(value), style=style or ''))
+
+        # Transitions Table
+        transitions_table = Table(
+            title='Transitions', border_style=_TABLE_BORDER_STYLE, show_header=True, header_style=_TABLE_HEADER_STYLE
+        )
+        transitions_table.add_column('From State', style='yellow')
+        transitions_table.add_column('To State', style='yellow')
+        transitions_table.add_column('Count', style='white', justify='right')
+        for from_state, to_state, count in self.get_transitions():
+            transitions_table.add_row(Text(from_state or ''), Text(to_state or ''), str(count))
+
+        # Actions Table
+        actions_table = Table(
+            title='Actions', border_style=_TABLE_BORDER_STYLE, show_header=True, header_style=_TABLE_HEADER_STYLE
+        )
+        actions_table.add_column('Type', style='bright_cyan')
+        actions_table.add_column('Action', style='white')
+        actions_table.add_column('Success', style='green', justify='right')
+        actions_table.add_column('Failure', justify='right')
+        for obj_type, operation, count_success, count_failure in self.get_actions():
+            failure = Text(str(count_failure), style='bold red' if count_failure else 'dim')
+            actions_table.add_row(Text(obj_type or ''), Text(operation or ''), str(count_success), failure)
+
+        # Return a Group containing all tables
+        return Group(properties_table, transitions_table, actions_table)
+
+
+class MidpointResource(MidpointObject):
+    def __init__(self, xml_entity: Element):
+        super().__init__()
+        self['OID'] = xml_entity.attrib['oid']
+        self['Name'] = safe_get_text(xml_entity.find('c:name', namespaces))
+        self['Availability Status'] = optional_text(
+            xml_entity.find('c:operationalState/c:lastAvailabilityStatus', namespaces)
+        )
+        connector_ref = xml_entity.find('c:connectorRef', namespaces)
+        self['connectorRef'] = connector_ref.attrib['oid'] if connector_ref is not None else None
+
+
+class MidpointConnector(MidpointObject):
+    def __init__(self, xml_entity: Element):
+        super().__init__()
+        self['OID'] = xml_entity.attrib['oid']
+        self['Name'] = safe_get_text(xml_entity.find('c:name', namespaces))
+        self['Connector type'] = safe_get_text(xml_entity.find('c:connectorType', namespaces))
+        self['Version'] = safe_get_text(xml_entity.find('c:connectorVersion', namespaces))
+        self['Bundle'] = safe_get_text(xml_entity.find('c:connectorBundle', namespaces))
+
+
+class MidpointUser(MidpointObject):
+    @staticmethod
+    def strip_namespace(tag: str) -> str:
+        """An ElementTree tag without its ``{namespace}`` prefix, e.g. 'fullName'."""
+        return re.sub(r'{.*}', '', tag)
+
+    def __init__(self, xml_entity: Element):
+        super().__init__()
+        self['OID'] = xml_entity.attrib['oid']
+        self['Name'] = safe_get_text(xml_entity.find('c:name', namespaces))
+        self['Title'] = optional_text(xml_entity.find('c:title', namespaces))
+        self['FullName'] = optional_text(xml_entity.find('c:fullName', namespaces))
+        self['Status'] = safe_get_text(xml_entity.find('c:activation/c:effectiveStatus', namespaces))
+        self['EmpNo'] = optional_text(xml_entity.find('c:employeeNumber', namespaces))
+        self['Email'] = optional_text(xml_entity.find('c:emailAddress', namespaces))
+        self['OU'] = optional_text(xml_entity.find('c:organizationalUnit', namespaces))
+
+        activation = xml_entity.find('c:activation', namespaces)
+        extfields = xml_entity.find('c:extension', namespaces)
+
+        self._all_attributes: list[tuple[str, str]] = []
+
+        for child in itertools.chain(
+            xml_entity,
+            activation if activation is not None else [],
+            extfields if extfields is not None else [],
+        ):
+            # Check if the child has no children and contains non-empty text
+            if len(child) == 0 and (child.text is not None and child.text.strip()):
+                self._all_attributes.append((self.strip_namespace(child.tag), child.text))
+
+        self._role_assignment_oids: list[str] = []
+        self._role_assignment_id_map: dict[str, str] = {}
+        self._org_assignment_oids: list[str] = []
+        for assignment in xml_entity.findall('c:assignment', namespaces):
+            target_ref = assignment.find('c:targetRef', namespaces)
+            if target_ref is not None:
+                ref_oid = target_ref.attrib.get('oid')
+                ref_type = target_ref.attrib.get('type', '')
+                if ref_oid:
+                    if 'RoleType' in ref_type:
+                        self._role_assignment_oids.append(ref_oid)
+                        assignment_id = assignment.attrib.get('id')
+                        if assignment_id:
+                            self._role_assignment_id_map[ref_oid] = assignment_id
+                    elif 'OrgType' in ref_type:
+                        self._org_assignment_oids.append(ref_oid)
+
+        self._link_ref_oids: list[str] = []
+        for link_ref in xml_entity.findall('c:linkRef', namespaces):
+            ref_oid = link_ref.attrib.get('oid')
+            if ref_oid:
+                self._link_ref_oids.append(ref_oid)
+
+    def get_all_attributes(self) -> list[tuple[str, str]]:
+        """Every simple property of the user as (local name, text) pairs, in document order.
+
+        Includes the leaf elements with text directly under the user, under ``activation`` and
+        under ``extension``; structured items (assignments, credentials, ...) are left out.
+        """
+        return self._all_attributes
+
+    def get_role_assignment_oids(self) -> list[str]:
+        """OIDs of the roles the user is directly assigned (assignments targeting a RoleType)."""
+        return self._role_assignment_oids
+
+    def get_role_assignment_id(self, role_oid: str) -> str | None:
+        """The container id of the user's assignment of role_oid, or None if not assigned or without id."""
+        return self._role_assignment_id_map.get(role_oid)
+
+    def get_org_assignment_oids(self) -> list[str]:
+        """OIDs of the organizations the user is directly assigned (assignments targeting an OrgType)."""
+        return self._org_assignment_oids
+
+    def get_link_ref_oids(self) -> list[str]:
+        """OIDs of the user's projections: the shadows referenced by ``linkRef``."""
+        return self._link_ref_oids
+
+
+class MidpointOrganization(MidpointObject):
+    def __init__(self, xml_entity: Element):
+        super().__init__()
+        self['OID'] = xml_entity.attrib['oid']
+        self['Name'] = safe_get_text(xml_entity.find('c:name', namespaces))
+        self['DisplayName'] = optional_text(xml_entity.find('c:displayName', namespaces))
+        self['Status'] = safe_get_text(xml_entity.find('c:activation/c:effectiveStatus', namespaces))
+        parentorg = xml_entity.find('c:parentOrgRef', namespaces)
+        self['Parent'] = None if parentorg is None else parentorg.attrib['oid']
+
+
+class MidpointRole(MidpointObject):
+    def __init__(self, xml_entity: Element):
+        super().__init__()
+        self['OID'] = xml_entity.attrib['oid']
+        self['Name'] = safe_get_text(xml_entity.find('c:name', namespaces))
+        self['DisplayName'] = optional_text(xml_entity.find('c:displayName', namespaces))
+        self['Description'] = optional_text(xml_entity.find('c:description', namespaces))
+        self['Status'] = safe_get_text(xml_entity.find('c:activation/c:effectiveStatus', namespaces))
+
+
+class MidpointAuditEvent(MidpointObject):
+    """One Midpoint AuditEventRecord, parsed for tabular display.
+
+    Raw <delta> XML elements are kept available via :meth:`get_deltas` so
+    callers can render them only when the user explicitly asks (e.g. with
+    ``--show-deltas``).
+    """
+
+    def __init__(self, xml_entity: Element):
+        super().__init__()
+        self['EventIdentifier'] = self._find_text(xml_entity, 'eventIdentifier')
+        self['Timestamp'] = self._find_text(xml_entity, 'timestamp')
+        self['Stage'] = self._find_text(xml_entity, 'eventStage')
+        self['EventType'] = self._find_text(xml_entity, 'eventType')
+        self['Initiator'] = self._format_ref(self._find(xml_entity, 'initiatorRef'))
+        self['Target'] = self._format_ref(self._find(xml_entity, 'targetRef'))
+        self['Channel'] = self._short_channel(self._find_text(xml_entity, 'channel'))
+        self['Outcome'] = self._find_text(xml_entity, 'outcome')
+        self['Message'] = self._find_text(xml_entity, 'message')
+
+        self._initiator_oid = self._ref_oid(self._find(xml_entity, 'initiatorRef'))
+        self._target_oid = self._ref_oid(self._find(xml_entity, 'targetRef'))
+        self._task_identifier = self._find_text(xml_entity, 'taskIdentifier')
+        self._session_identifier = self._find_text(xml_entity, 'sessionIdentifier')
+        self._request_identifier = self._find_text(xml_entity, 'requestIdentifier')
+        self._parameter = self._find_text(xml_entity, 'parameter')
+
+        self._deltas: list[Element] = self._find_all(xml_entity, 'delta')
+
+    @staticmethod
+    def _find(parent: Element, local_name: str) -> Element | None:
+        """Find a child element by local name across both audit-3 and common-3 namespaces."""
+        node = parent.find(f'aud:{local_name}', namespaces)
+        if node is None:
+            node = parent.find(f'c:{local_name}', namespaces)
+        return node
+
+    @classmethod
+    def _find_all(cls, parent: Element, local_name: str) -> list[Element]:
+        nodes = parent.findall(f'aud:{local_name}', namespaces)
+        if not nodes:
+            nodes = parent.findall(f'c:{local_name}', namespaces)
+        return list(nodes)
+
+    @classmethod
+    def _find_text(cls, parent: Element, local_name: str) -> str:
+        return safe_get_text(cls._find(parent, local_name))
+
+    @staticmethod
+    def _ref_oid(node: Element | None) -> str | None:
+        if node is None:
+            return None
+        return node.attrib.get('oid')
+
+    @staticmethod
+    def _format_ref(node: Element | None) -> str:
+        """Render a *Ref node as ``name (oid)`` when both are present, else whichever exists."""
+        if node is None:
+            return ''
+        oid = node.attrib.get('oid', '')
+        # Audit refs store the human-readable name in <aud:description>, regular
+        # object refs use <c:name>. Fall back through both.
+        name = ''
+        for path in ('aud:description', 'c:description', 'aud:name', 'c:name'):
+            child = node.find(path, namespaces)
+            if child is not None and child.text:
+                name = child.text
+                break
+        if name and oid:
+            return f'{name} ({oid})'
+        return name or oid
+
+    @staticmethod
+    def _short_channel(channel: str) -> str:
+        """Drop the URI prefix from a channel URI, keep just the trailing fragment."""
+        if not channel:
+            return ''
+        if '#' in channel:
+            return channel.rsplit('#', 1)[-1]
+        return channel.rsplit('/', 1)[-1]
+
+    def get_initiator_oid(self) -> str | None:
+        """OID of the object that initiated the event (``initiatorRef``), or None."""
+        return self._initiator_oid
+
+    def get_target_oid(self) -> str | None:
+        """OID of the event's target object (``targetRef``), or None."""
+        return self._target_oid
+
+    def get_task_identifier(self) -> str | None:
+        """The ``taskIdentifier`` of the task that emitted the event, or None."""
+        return self._task_identifier or None
+
+    def get_session_identifier(self) -> str | None:
+        """The event's ``sessionIdentifier``, or None when it has none."""
+        return self._session_identifier or None
+
+    def get_request_identifier(self) -> str | None:
+        """The event's ``requestIdentifier``, shared by the events of one operation, or None."""
+        return self._request_identifier or None
+
+    def get_parameter(self) -> str | None:
+        """The event's free-form ``parameter``, or None when it has none."""
+        return self._parameter or None
+
+    def get_deltas(self) -> list[Element]:
+        """The event's raw ``<delta>`` elements (ObjectDeltaOperationType), empty when it has none."""
+        return self._deltas
+
+
+class MidpointShadow(MidpointObject):
+    def __init__(self, xml_entity: Element):
+        super().__init__()
+        self['OID'] = xml_entity.attrib['oid']
+        self['Name'] = safe_get_text(xml_entity.find('c:name', namespaces))
+        resource_ref = xml_entity.find('c:resourceRef', namespaces)
+        self['ResourceOID'] = resource_ref.attrib['oid'] if resource_ref is not None else None
+        self['Kind'] = optional_text(xml_entity.find('c:kind', namespaces))
+        self['Intent'] = optional_text(xml_entity.find('c:intent', namespaces))
+        self['Status'] = safe_get_text(xml_entity.find('c:activation/c:effectiveStatus', namespaces))
+        self['Situation'] = safe_get_text(xml_entity.find('c:synchronizationSituation', namespaces))
+        # A dead shadow stands for an object deleted from the resource, kept for a while by Midpoint.
+        self['Dead'] = safe_get_text(xml_entity.find('c:dead', namespaces))
+
+
+@dataclass
+class MidpointObjectType:
+    object_type: str | None
+    endpoint: str | None
+    tagname: str
+
+
+class MidpointTypeNotFound(Exception):
+    pass
+
+
+class MidpointObjectTypes(Enum):
+    CONNECTOR = MidpointObjectType('ConnectorType', 'connectors', 'connector')
+    CONNECTOR_HOST = MidpointObjectType('ConnectorHostType', 'connectorHosts', 'connectorHost')
+    GENERIC_OBJECT = MidpointObjectType('GenericObjectType', 'genericObjects', 'genericObject')
+    RESOURCE = MidpointObjectType('ResourceType', 'resources', 'resource')
+    USER = MidpointObjectType('UserType', 'users', 'user')
+    OBJECT_TEMPLATE = MidpointObjectType('ObjectTemplateType', 'objectTemplates', 'objectTemplate')
+    SYSTEM_CONFIGURATION = MidpointObjectType('SystemConfigurationType', 'systemConfigurations', 'systemConfiguration')
+    TASK = MidpointObjectType('TaskType', 'tasks', 'task')
+    SHADOW = MidpointObjectType('ShadowType', 'shadows', 'shadow')
+    ROLE = MidpointObjectType('RoleType', 'roles', 'role')
+    VALUE_POLICY = MidpointObjectType('ValuePolicyType', 'valuePolicies', 'valuePolicy')
+    ORG = MidpointObjectType('OrgType', 'orgs', 'org')
+    FUNCTION_LIBRARY = MidpointObjectType('FunctionLibraryType', 'functionLibraries', 'functionLibrary')
+    REPORT = MidpointObjectType('ReportType', 'reports', 'report')
+    POLICY = MidpointObjectType('PolicyType', 'policies', 'policy')
+    # The following REST endpoints are all present in Midpoint 4.4 through 4.11.
+    ARCHETYPE = MidpointObjectType('ArchetypeType', 'archetypes', 'archetype')
+    SERVICE = MidpointObjectType('ServiceType', 'services', 'service')
+    LOOKUP_TABLE = MidpointObjectType('LookupTableType', 'lookupTables', 'lookupTable')
+    CASE = MidpointObjectType('CaseType', 'cases', 'case')
+    NODE = MidpointObjectType('NodeType', 'nodes', 'node')
+    OBJECT_COLLECTION = MidpointObjectType('ObjectCollectionType', 'objectCollections', 'objectCollection')
+    DASHBOARD = MidpointObjectType('DashboardType', 'dashboards', 'dashboard')
+    SEQUENCE = MidpointObjectType('SequenceType', 'sequences', 'sequence')
+    OBJECTS = MidpointObjectType(None, None, 'objects')
+
+    @staticmethod
+    def __find(needle: str, getter: Callable) -> MidpointObjectType:
+        for type in MidpointObjectTypes:
+            if getter(type.value) == needle:
+                return type.value
+
+        raise MidpointTypeNotFound(f'No type found for value {needle}')
+
+    # The exact lookups below are not used by the CLI itself, which goes through find_by_name.
+    # They are kept as public API for `script run` scripts, which receive the client.
+
+    @staticmethod
+    def find_by_java_type(java_type: str) -> MidpointObjectType:
+        """The type whose schema type name is exactly java_type (e.g. 'UserType').
+
+        Raises MidpointTypeNotFound when no type has that name. See find_by_name for a lenient lookup.
+        """
+        return MidpointObjectTypes.__find(java_type, lambda t: t.object_type)
+
+    @staticmethod
+    def find_by_endpoint(endpoint: str) -> MidpointObjectType:
+        """The type whose REST collection is exactly endpoint (e.g. 'users' for ws/rest/users).
+
+        Raises MidpointTypeNotFound when no type has that endpoint.
+        """
+        return MidpointObjectTypes.__find(endpoint, lambda t: t.endpoint)
+
+    @staticmethod
+    def find_by_tagname(tagname: str) -> MidpointObjectType:
+        """The type whose XML element name is exactly tagname (e.g. 'user'), case-sensitive.
+
+        Raises MidpointTypeNotFound when no type has that element name. See find_by_name for a lenient lookup.
+        """
+        return MidpointObjectTypes.__find(tagname, lambda t: t.tagname)
+
+    @staticmethod
+    def find_by_name(name: str) -> MidpointObjectType:
+        """
+        Flexible type lookup that tries multiple matching strategies:
+        1. Case-insensitive tagname match (e.g., "objectTemplate", "ObjectTemplate")
+        2. Case-insensitive Java type match (e.g., "ObjectTemplateType")
+        3. Partial name with Type suffix appended (e.g., "ObjectTemplate" → "ObjectTemplateType")
+        4. Partial name with Type suffix removed (e.g., "ObjectTemplateType" → "ObjectTemplate")
+
+        Raises MidpointTypeNotFound with helpful suggestions if no match is found.
+        """
+        if not name:
+            raise MidpointTypeNotFound('Type name cannot be empty')
+
+        name_lower = name.lower()
+
+        # Strategy 1: Try case-insensitive tagname match
+        for mp_type in MidpointObjectTypes:
+            if mp_type.value.tagname and mp_type.value.tagname.lower() == name_lower:
+                return mp_type.value
+
+        # Strategy 2: Try case-insensitive Java type match
+        for mp_type in MidpointObjectTypes:
+            if mp_type.value.object_type and mp_type.value.object_type.lower() == name_lower:
+                return mp_type.value
+
+        # Strategy 3: Try appending "Type" suffix for partial matches
+        # (e.g., "ObjectTemplate" → "ObjectTemplateType")
+        if not name_lower.endswith('type'):
+            name_with_type = name + 'Type'
+            name_with_type_lower = name_with_type.lower()
+            for mp_type in MidpointObjectTypes:
+                if mp_type.value.object_type and mp_type.value.object_type.lower() == name_with_type_lower:
+                    return mp_type.value
+
+        # Strategy 4: Try removing "Type" suffix
+        # (e.g., "ObjectTemplateType" → "objectTemplate")
+        if name_lower.endswith('type'):
+            name_without_type = name[:-4]  # Remove "Type"
+            name_without_type_lower = name_without_type.lower()
+            for mp_type in MidpointObjectTypes:
+                if mp_type.value.tagname and mp_type.value.tagname.lower() == name_without_type_lower:
+                    return mp_type.value
+
+        # No match found - create helpful error message
+        valid_types = []
+        for mp_type in MidpointObjectTypes:
+            if mp_type.value.tagname != 'objects':  # Skip the generic "objects" type
+                if mp_type.value.object_type:
+                    valid_types.append(f'{mp_type.value.tagname} ({mp_type.value.object_type})')
+                else:
+                    valid_types.append(mp_type.value.tagname)
+
+        valid_types_str = ', '.join(sorted(valid_types))
+        raise MidpointTypeNotFound(f'No type found for value "{name}". Valid types are: {valid_types_str}')
+
+
+def optional_text(node: Element | None) -> str | None:
+    """The text of node, or None when node is missing (unlike safe_get_text, which returns a default)."""
+    return node.text if node is not None else None