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

midpoint_cli/client/midpoint_client.py

@@ -0,0 +1,866 @@
+"""MidpointClient: the high-level operations of the CLI on a Midpoint server."""
+
+import contextlib
+import json
+import logging
+import sys
+import time
+from collections.abc import Callable, Sequence
+from datetime import UTC, datetime
+from typing import Any
+from xml.etree import ElementTree
+from xml.etree.ElementTree import Element
+from xml.sax.saxutils import escape as xml_escape
+from xml.sax.saxutils import quoteattr
+
+import requests
+
+from midpoint_cli.client.audit import (
+    as_utc,
+    audit_script_error,
+    initial_audit_cursor,
+    parse_audit_events_from_script_response,
+    parse_audit_timestamp,
+)
+from midpoint_cli.client.audit_query import AUDIT_EXEC_SCRIPT_PATH, AuditQuery, build_execute_script_body
+from midpoint_cli.client.configuration import MidpointClientConfiguration
+from midpoint_cli.client.constants import API_TYPES_NS, COMMON_NS, TYPES_NS, ResultStatus, TaskExecutionState
+from midpoint_cli.client.errors import (
+    MidpointAmbiguousName,
+    MidpointClientNotConfigured,
+    MidpointMissingPassword,
+    MidpointObjectNotFound,
+    MidpointServerError,
+    TaskExecutionFailure,
+)
+from midpoint_cli.client.logging_config import (
+    LoggingConfiguration,
+    check_logger_name,
+    class_logger_modification,
+    normalize_level,
+    parse_logging,
+)
+from midpoint_cli.client.object_query import (
+    ORG_SEARCH_PATHS,
+    ROLE_SEARCH_PATHS,
+    USER_SEARCH_PATHS,
+    ObjectQuery,
+    and_filter,
+    equal_filter,
+    in_oid_filter,
+    is_oid,
+    ref_filter,
+    task_status_filter,
+)
+from midpoint_cli.client.objects import (
+    MidpointConnector,
+    MidpointObject,
+    MidpointObjectList,
+    MidpointObjectType,
+    MidpointObjectTypes,
+    MidpointOrganization,
+    MidpointResource,
+    MidpointRole,
+    MidpointShadow,
+    MidpointTask,
+    MidpointUser,
+    namespaces,
+    safe_get_text,
+)
+from midpoint_cli.client.observer import MidpointCommunicationObserver
+from midpoint_cli.client.progress import ProgressMonitor
+from midpoint_cli.client.rest import PutResult, RestApiClient
+from midpoint_cli.client.safe_xml import fromstring as safe_fromstring
+from midpoint_cli.client.server_info import (
+    ACTUATOR_FIELDS,
+    SYSTEM_CONFIGURATION_OID,
+    ServerInformation,
+    describe_repository,
+    parse_deployment,
+    parse_logged_in_user,
+    parse_nodes,
+)
+from midpoint_cli.client.server_version import MidpointVersion, parse_server_version
+from midpoint_cli.client.task_definitions import (
+    report_task_name,
+    report_task_xml,
+    resource_task_name,
+    resource_task_xml,
+)
+
+logger = logging.getLogger(__name__)
+
+# SynchronizationSituationType values, the same from 4.4.11 to 4.11.0.
+SHADOW_SITUATIONS = ('linked', 'unlinked', 'unmatched', 'disputed', 'deleted')
+# Shadow counts are read from the repository only: no resource is contacted and no
+# definitions are applied, so a resource that is down or has no schema can still be counted.
+_SHADOW_COUNT_OPTIONS = ('raw',)
+
+
+# Local classes of the object types the CLI displays; other types (archetypes, services, cases,
+# lookup tables, nodes, object collections, dashboards, sequences, ...) are parsed to OID and name only.
+# Tasks are parsed by _parse_object itself, as they need the server version.
+_LOCAL_CLASSES: tuple[tuple[MidpointObjectTypes, type[MidpointObject]], ...] = (
+    (MidpointObjectTypes.USER, MidpointUser),
+    (MidpointObjectTypes.ROLE, MidpointRole),
+    (MidpointObjectTypes.ORG, MidpointOrganization),
+    (MidpointObjectTypes.RESOURCE, MidpointResource),
+    (MidpointObjectTypes.CONNECTOR, MidpointConnector),
+    (MidpointObjectTypes.SHADOW, MidpointShadow),
+)
+
+
+def _parse_object(
+    object_type: MidpointObjectType, entity: Element, server_version: MidpointVersion | None = None
+) -> MidpointObject:
+    """Parse an object element with the local class of object_type, or to OID and name for other types.
+
+    Tasks are parsed for server_version, whose task schema they follow.
+    """
+    if object_type == MidpointObjectTypes.TASK.value:
+        return MidpointTask(entity, server_version)
+    for known_type, local_class in _LOCAL_CLASSES:
+        if known_type.value == object_type:
+            return local_class(entity)
+    obj = MidpointObject()
+    obj['OID'] = entity.attrib.get('oid')
+    obj['Name'] = safe_get_text(entity.find('c:name', namespaces))
+    return obj
+
+
+def _expected_total(task: MidpointTask) -> int | None:
+    """The number of items the task expects to process, or None when the server does not tell."""
+    try:
+        total = int(task['Expected Total'])
+    except (TypeError, ValueError):
+        return None
+    return total if total > 0 else None
+
+
+# A task the CLI creates is started by the server's scheduler, usually within a second or two.
+# Until then it has no result; waiting stops after TASK_START_ATTEMPTS polls.
+TASK_START_POLL_SECONDS = 1
+TASK_START_ATTEMPTS = 120
+
+
+class MidpointClient:
+    def __init__(
+        self,
+        client_configuration: MidpointClientConfiguration | None = None,
+        api_client: RestApiClient | None = None,
+        observer: MidpointCommunicationObserver | None = None,
+    ):
+        self._api_client: RestApiClient | None = None
+
+        if client_configuration is not None:
+            self._api_client = RestApiClient(client_configuration, observer=observer)
+
+        if api_client is not None:
+            self._api_client = api_client
+
+        # Server version, detected on first use (get_server_version); None until then or if unknown.
+        self._server_version: MidpointVersion | None = None
+        self._server_version_detected = False
+
+    @property
+    def api_client(self) -> RestApiClient:
+        if self._api_client is None:
+            raise MidpointClientNotConfigured(
+                'MidpointClient was created without a client configuration or a REST API client'
+            )
+        return self._api_client
+
+    @api_client.setter
+    def api_client(self, api_client: RestApiClient) -> None:
+        self._api_client = api_client
+
+    def __get_object(self, midpoint_type: MidpointObjectType, oid: str) -> Element:
+        response = self.api_client.get_element(midpoint_type, oid)
+        tree = safe_fromstring(response)
+
+        status = tree.find('c:status', namespaces)
+
+        if status is not None and status.text == ResultStatus.FATAL_ERROR:
+            message_node = tree.find('c:partialResults/c:message', namespaces)
+            message = message_node.text if message_node is not None else 'Unknown error'
+            raise MidpointServerError(message)
+
+        return tree
+
+    def __get_collection(
+        self,
+        mp_class: MidpointObjectType,
+        local_class: type,
+        limit: int | None = None,
+        name_filter: str | None = None,
+    ) -> MidpointObjectList:
+        """List a collection; with a limit or a name filter, the server filters and pages it."""
+        if limit is None and not name_filter:
+            tree = self.api_client.get_elements(mp_class)
+            return MidpointObjectList([local_class(entity) for entity in tree])
+        return self.search_objects(mp_class, ObjectQuery.listing(limit=limit, name_filter=name_filter))
+
+    def search_objects(
+        self, object_type: MidpointObjectType, query: ObjectQuery, options: Sequence[str] = ()
+    ) -> MidpointObjectList:
+        """Run a server-side search (POST ws/rest/<collection>/search) and parse the matching objects.
+
+        options are REST GetOperationOptions such as 'raw' (see RestApiClient.search_elements).
+        """
+        if options:
+            tree = self.api_client.search_elements(object_type, query.to_xml(), options)
+        else:
+            tree = self.api_client.search_elements(object_type, query.to_xml())
+        server_version = self._server_version_for(object_type)
+        return MidpointObjectList(
+            [
+                _parse_object(object_type, entity, server_version)
+                for entity in tree
+                if entity.attrib.get('oid') is not None
+            ]
+        )
+
+    def _server_version_for(self, object_type: MidpointObjectType) -> MidpointVersion | None:
+        """The server version for parsing objects of object_type: only tasks need it."""
+        return self.get_server_version() if object_type == MidpointObjectTypes.TASK.value else None
+
+    def get_object(self, object_type: MidpointObjectType, oid: str) -> MidpointObject:
+        """Fetch one object by OID, parsed with the local class of its type."""
+        return _parse_object(object_type, self.__get_object(object_type, oid), self._server_version_for(object_type))
+
+    def find_objects(self, object_type: MidpointObjectType, reference: str) -> MidpointObjectList:
+        """Every object a CLI reference designates: the object with that OID, or else all objects with that name.
+
+        A reference in OID form is fetched directly. Otherwise the server is searched by exact name;
+        when nothing has that name, the reference is tried as an OID (the generic repository allows
+        OIDs that are not UUIDs). An empty list means nothing matched.
+        """
+        if not is_oid(reference):
+            matches = self.search_objects(object_type, ObjectQuery.name_equals(reference))
+            if matches:
+                return matches
+        try:
+            return MidpointObjectList([self.get_object(object_type, reference)])
+        except MidpointObjectNotFound:
+            return MidpointObjectList()
+        except MidpointServerError:
+            # The search above reached the server, so this is the reference being refused as an
+            # OID (unsafe characters, or the native repository rejecting a non-UUID OID).
+            if is_oid(reference):
+                raise
+            return MidpointObjectList()
+
+    def find_object(self, object_type: MidpointObjectType, reference: str) -> MidpointObject | None:
+        """The single object a CLI reference (OID or name) designates, or None when nothing matches.
+
+        Raises MidpointAmbiguousName when the reference is a name shared by several objects,
+        instead of silently acting on one of them.
+        """
+        matches = self.find_objects(object_type, reference)
+        if len(matches) > 1:
+            raise MidpointAmbiguousName(object_type, reference, [str(m.get_oid()) for m in matches])
+        return matches[0] if matches else None
+
+    def resolve_oid(self, object_type: MidpointObjectType, reference: str) -> str:
+        """The OID a CLI reference designates: a canonical OID as is, else the OID of the object so named.
+
+        Raises MidpointObjectNotFound when nothing has that name or OID, and MidpointAmbiguousName
+        when several objects have that name.
+        """
+        if is_oid(reference):
+            return reference
+        found = self.find_object(object_type, reference)
+        oid = found.get_oid() if found is not None else None
+        if oid is None:
+            raise MidpointObjectNotFound(f'No {object_type.tagname} has the name or OID {reference!r}')
+        return oid
+
+    def complete_names(self, object_type: MidpointObjectType, prefix: str, limit: int = 50) -> MidpointObjectList:
+        """At most limit objects whose name starts with prefix, for tab completion."""
+        return self.search_objects(object_type, ObjectQuery.name_prefix(prefix, limit))
+
+    def get_tasks(
+        self, limit: int | None = None, name_filter: str | None = None, statuses: Sequence[str] = ()
+    ) -> MidpointObjectList:
+        """List tasks; statuses keeps those in any of the `task ls --status` states (TASK_STATUS_FILTERS)."""
+        if limit is None and not name_filter and not statuses:
+            server_version = self.get_server_version()
+            tree = self.api_client.get_elements(MidpointObjectTypes.TASK.value)
+            return MidpointObjectList([MidpointTask(entity, server_version) for entity in tree])
+        status_filter = task_status_filter(statuses)
+        return self.search_objects(
+            MidpointObjectTypes.TASK.value,
+            ObjectQuery.listing(
+                limit=limit, name_filter=name_filter, filters=[status_filter] if status_filter is not None else []
+            ),
+        )
+
+    def get_resources(self, limit: int | None = None, name_filter: str | None = None) -> MidpointObjectList:
+        return self.__get_collection(MidpointObjectTypes.RESOURCE.value, MidpointResource, limit, name_filter)
+
+    def get_resource_shadow_counts(self, resource_oid: str) -> dict[str, int]:
+        """Count the repository shadows of a resource by synchronization situation.
+
+        Returns a count for each of SHADOW_SITUATIONS, plus 'none' for shadows without a
+        situation and 'total'. Midpoint 4.10+ counts on the server (6 searches answering one
+        shadow each); earlier versions cannot count, so all shadows of the resource are
+        downloaded in one search and counted here, which is slow on large resources.
+        """
+        by_resource = ref_filter('resourceRef', resource_oid)
+        version = self.get_server_version()
+        if version is None or version.at_least(4, 10):
+            total = self.api_client.count_elements(
+                MidpointObjectTypes.SHADOW.value,
+                ObjectQuery(filter=by_resource, limit=1).to_xml(),
+                _SHADOW_COUNT_OPTIONS,
+            )
+            if total is not None:
+                counts = dict.fromkeys(SHADOW_SITUATIONS, 0)
+                for situation in SHADOW_SITUATIONS if total else ():
+                    situation_filter = and_filter([by_resource, equal_filter('synchronizationSituation', situation)])
+                    counts[situation] = (
+                        self.api_client.count_elements(
+                            MidpointObjectTypes.SHADOW.value,
+                            ObjectQuery(filter=situation_filter, limit=1).to_xml(),
+                            _SHADOW_COUNT_OPTIONS,
+                        )
+                        or 0
+                    )
+                counts['none'] = max(total - sum(counts.values()), 0)
+                counts['total'] = total
+                return counts
+
+        shadows = self.api_client.search_elements(
+            MidpointObjectTypes.SHADOW.value, ObjectQuery(filter=by_resource).to_xml(), _SHADOW_COUNT_OPTIONS
+        )
+        counts = dict.fromkeys((*SHADOW_SITUATIONS, 'none', 'total'), 0)
+        for shadow in shadows:
+            if shadow.attrib.get('oid') is None:
+                continue
+            situation = safe_get_text(shadow.find('c:synchronizationSituation', namespaces)).strip()
+            counts[situation if situation in SHADOW_SITUATIONS else 'none'] += 1
+            counts['total'] += 1
+        return counts
+
+    def get_connectors(self, limit: int | None = None, name_filter: str | None = None) -> MidpointObjectList:
+        return self.__get_collection(MidpointObjectTypes.CONNECTOR.value, MidpointConnector, limit, name_filter)
+
+    def get_reports(self, limit: int | None = None, name_filter: str | None = None) -> MidpointObjectList:
+        return self.search_objects(
+            MidpointObjectTypes.REPORT.value, ObjectQuery.listing(limit=limit, name_filter=name_filter)
+        )
+
+    def get_shadows(
+        self,
+        resource_oid: str | None = None,
+        kind: str | None = None,
+        intent: str | None = None,
+        limit: int | None = None,
+        name_filter: str | None = None,
+    ) -> MidpointObjectList:
+        """Shadows from the repository, optionally of one resource, kind and intent.
+
+        The search is raw: without it the model would hand a shadow search to provisioning,
+        which reads the resource itself and wants an object class or kind. A raw search
+        reads the repository only, so it lists what Midpoint knows without contacting the resource.
+        """
+        filters = []
+        if resource_oid is not None:
+            filters.append(ref_filter('resourceRef', resource_oid))
+        if kind:
+            filters.append(equal_filter('kind', kind))
+        if intent:
+            filters.append(equal_filter('intent', intent))
+        query = ObjectQuery.listing(limit=limit, name_filter=name_filter, filters=filters)
+        return self.search_objects(MidpointObjectTypes.SHADOW.value, query, options=['raw'])
+
+    def get_objects_by_oid(self, object_type: MidpointObjectType, oids: Sequence[str]) -> MidpointObjectList:
+        """The objects of one type with the given OIDs, in one search; unknown OIDs are skipped."""
+        if not oids:
+            return MidpointObjectList()
+        return self.search_objects(object_type, ObjectQuery(filter=in_oid_filter(oids)))
+
+    def search_text(
+        self,
+        object_type: MidpointObjectType,
+        query_text: str | None,
+        limit: int | None = None,
+        raw: bool = False,
+    ) -> MidpointObjectList:
+        """Objects of one type matching a Midpoint Query Language filter (all objects without one), by name.
+
+        raw searches the repository only (see get_shadows), without contacting resources.
+        """
+        query = ObjectQuery.text(query_text, limit=limit) if query_text else ObjectQuery.listing(limit=limit)
+        return self.search_objects(object_type, query, options=['raw'] if raw else [])
+
+    def get_user(self, oid: str) -> MidpointUser:
+        user_root = self.__get_object(MidpointObjectTypes.USER.value, oid)
+        user = MidpointUser(user_root)
+        return user
+
+    def get_users(self, limit: int | None = None, name_filter: str | None = None) -> MidpointObjectList:
+        return self.__get_collection(MidpointObjectTypes.USER.value, MidpointUser, limit, name_filter)
+
+    def get_orgs(self, limit: int | None = None, name_filter: str | None = None) -> MidpointObjectList:
+        return self.__get_collection(MidpointObjectTypes.ORG.value, MidpointOrganization, limit, name_filter)
+
+    def get_orgs_by_oid(self, oids: list[str]) -> MidpointObjectList:
+        """The organizations with the given OIDs, in one search; unknown OIDs are skipped."""
+        if not oids:
+            return MidpointObjectList()
+        return self.search_objects(MidpointObjectTypes.ORG.value, ObjectQuery.oids(oids))
+
+    def get_roles(self, limit: int | None = None, name_filter: str | None = None) -> MidpointObjectList:
+        return self.__get_collection(MidpointObjectTypes.ROLE.value, MidpointRole, limit, name_filter)
+
+    def search_users(self, terms: list[str]) -> MidpointObjectList:
+        """Users whose name, full name or email address contains the terms (see ObjectQuery.terms)."""
+        return self.search_objects(MidpointObjectTypes.USER.value, ObjectQuery.terms(terms, USER_SEARCH_PATHS))
+
+    def search_roles(self, terms: list[str]) -> MidpointObjectList:
+        """Roles whose name or display name contains the terms (see ObjectQuery.terms)."""
+        return self.search_objects(MidpointObjectTypes.ROLE.value, ObjectQuery.terms(terms, ROLE_SEARCH_PATHS))
+
+    def search_orgs(self, terms: list[str]) -> MidpointObjectList:
+        """Organizations whose name or display name contains the terms (see ObjectQuery.terms)."""
+        return self.search_objects(MidpointObjectTypes.ORG.value, ObjectQuery.terms(terms, ORG_SEARCH_PATHS))
+
+    def _modify(
+        self, object_type: MidpointObjectType, oid: str, modification_type: str, path: str, value_xml: str
+    ) -> None:
+        """Apply one item delta to an object: PATCH ws/rest/<collection>/<oid> with an ObjectModificationType."""
+        xml_body = (
+            '<objectModification'
+            f" xmlns='{API_TYPES_NS}'"
+            f" xmlns:c='{COMMON_NS}'"
+            f" xmlns:t='{TYPES_NS}'>"
+            '<itemDelta>'
+            f'<t:modificationType>{modification_type}</t:modificationType>'
+            f'<t:path>{path}</t:path>'
+            f'<t:value>{value_xml}</t:value>'
+            '</itemDelta>'
+            '</objectModification>'
+        )
+        self.api_client.patch_element(object_type, oid, xml_body)
+
+    @staticmethod
+    def _target_ref(target_type: MidpointObjectType, target_oid: str) -> str:
+        return f"<c:targetRef oid={quoteattr(target_oid)} type='c:{target_type.object_type}'/>"
+
+    def assign(self, user_oid: str, target_type: MidpointObjectType, target_oid: str) -> None:
+        """Add an assignment of a role, org, service or archetype (target_type) to a user."""
+        self._modify(
+            MidpointObjectTypes.USER.value, user_oid, 'add', 'c:assignment', self._target_ref(target_type, target_oid)
+        )
+
+    def unassign(self, user_oid: str, target_type: MidpointObjectType, target_oid: str) -> None:
+        """Remove a user's assignment of a role, org, service or archetype, matched by its target."""
+        self._modify(
+            MidpointObjectTypes.USER.value,
+            user_oid,
+            'delete',
+            'c:assignment',
+            self._target_ref(target_type, target_oid),
+        )
+
+    def assign_role(self, user_oid: str, role_oid: str) -> None:
+        self.assign(user_oid, MidpointObjectTypes.ROLE.value, role_oid)
+
+    def unassign_role(self, user_oid: str, role_oid: str) -> None:
+        self.unassign(user_oid, MidpointObjectTypes.ROLE.value, role_oid)
+
+    def set_user_enabled(self, user_oid: str, enabled: bool) -> None:
+        """Enable or disable a user by replacing activation/administrativeStatus."""
+        status = 'enabled' if enabled else 'disabled'
+        self._modify(MidpointObjectTypes.USER.value, user_oid, 'replace', 'c:activation/c:administrativeStatus', status)
+
+    def set_user_password(self, user_oid: str, password: str) -> None:
+        """Replace a user's password with a protected string in clear (t:clearValue); the server encrypts it.
+
+        The password only travels in the request body: it is never logged, and errors carry the
+        server's message, not the request.
+        """
+        self._modify(
+            MidpointObjectTypes.USER.value,
+            user_oid,
+            'replace',
+            'c:credentials/c:password/c:value',
+            f'<t:clearValue>{xml_escape(password)}</t:clearValue>',
+        )
+
+    def get_resource(self, oid: str) -> MidpointResource:
+        return MidpointResource(self.__get_object(MidpointObjectTypes.RESOURCE.value, oid))
+
+    def get_role(self, oid: str) -> MidpointRole:
+        return MidpointRole(self.__get_object(MidpointObjectTypes.ROLE.value, oid))
+
+    def get_org(self, oid: str) -> MidpointOrganization:
+        return MidpointOrganization(self.__get_object(MidpointObjectTypes.ORG.value, oid))
+
+    def get_shadow(self, oid: str) -> MidpointShadow:
+        return MidpointShadow(self.__get_object(MidpointObjectTypes.SHADOW.value, oid))
+
+    def task_action(
+        self,
+        task_oid: str,
+        task_action: str,
+        progress_monitor: ProgressMonitor,
+        show_changes: bool = True,
+    ) -> MidpointTask | None:
+        run_started_at = datetime.now(UTC)
+        self.api_client.execute_action(MidpointObjectTypes.TASK.value, task_oid, task_action)
+
+        if task_action == 'run':
+            return self.task_wait(task_oid, progress_monitor, show_changes=show_changes, run_started_at=run_started_at)
+
+        return None
+
+    def task_wait(
+        self,
+        task_oid: str,
+        progress_monitor: ProgressMonitor,
+        show_changes: bool = True,
+        run_started_at: datetime | None = None,
+    ) -> MidpointTask:
+        server_version = self.get_server_version()
+        # First, get the initial task state to extract start time
+        task_root = self.__get_object(MidpointObjectTypes.TASK.value, task_oid)
+        initial_task = MidpointTask(task_root, server_version)
+
+        # Set the task start time on the progress monitor before entering
+        task_start_time = initial_task.get_start_time()
+        progress_monitor.set_task_start_time(task_start_time)
+
+        # Audit-stream state — only used when show_changes is on and the task
+        # advertises a taskIdentifier (the join key into audit records).
+        task_identifier = initial_task.get_task_identifier() if show_changes else None
+        audit_cursor = initial_audit_cursor(run_started_at, task_start_time)
+        seen_event_ids: set[str] = set()
+        # Set to False on the first MidpointServerError so we stop retrying on
+        # servers that refuse or cannot run the audit script.
+        audit_available: bool = True
+
+        with progress_monitor as progress:
+            # Update with initial progress and statistics
+            initial_progress = int(initial_task['Progress'] or '0')
+            initial_success = initial_task.get_success_count()
+            initial_failure = initial_task.get_failure_count()
+            progress.set_expected_total(_expected_total(initial_task))
+            progress.update_with_stats(initial_progress, initial_success, initial_failure)
+
+            # Drain any audit events that already happened before we attached.
+            if task_identifier and audit_available:
+                try:
+                    audit_cursor = self._stream_task_audit_events(
+                        task_identifier, audit_cursor, seen_event_ids, progress
+                    )
+                except MidpointServerError:
+                    audit_available = False
+
+            # Check if task is already completed
+            rstatus = initial_task['Result Status']
+            if rstatus != ResultStatus.IN_PROGRESS:
+                print(file=sys.stderr)  # ends the progress line, which is on stderr
+                if rstatus != ResultStatus.SUCCESS:
+                    raise TaskExecutionFailure(
+                        'Failed execution of task ' + task_oid + ' with status ' + rstatus, initial_task
+                    )
+                return initial_task
+
+            # Continue polling for updates
+            while True:
+                time.sleep(2)
+                task_root = self.__get_object(MidpointObjectTypes.TASK.value, task_oid)
+                task = MidpointTask(task_root, server_version)
+
+                # Update with progress and statistics
+                current_progress = int(task['Progress'] or '0')
+                current_success = task.get_success_count()
+                current_failure = task.get_failure_count()
+                progress.set_expected_total(_expected_total(task))
+                progress.update_with_stats(current_progress, current_success, current_failure)
+
+                if task_identifier and audit_available:
+                    try:
+                        audit_cursor = self._stream_task_audit_events(
+                            task_identifier, audit_cursor, seen_event_ids, progress
+                        )
+                    except MidpointServerError:
+                        audit_available = False
+
+                rstatus = task['Result Status']
+
+                if rstatus != ResultStatus.IN_PROGRESS:
+                    # One last drain so trailing events that landed between the
+                    # final fetch and the status flip aren't lost.
+                    if task_identifier and audit_available:
+                        with contextlib.suppress(MidpointServerError):
+                            self._stream_task_audit_events(task_identifier, audit_cursor, seen_event_ids, progress)
+                    print(file=sys.stderr)  # ends the progress line, which is on stderr
+                    if rstatus != ResultStatus.SUCCESS:
+                        raise TaskExecutionFailure(
+                            'Failed execution of task ' + task_oid + ' with status ' + rstatus, task
+                        )
+
+                    return task
+
+    def _stream_task_audit_events(
+        self,
+        task_identifier: str,
+        cursor: datetime | None,
+        seen: set[str],
+        progress: ProgressMonitor,
+    ) -> datetime | None:
+        """Fetch new audit events for the running task and push each through the monitor.
+
+        The cursor is inclusive, so events sharing the newest timestamp already seen are
+        fetched again; ``seen`` drops the ones already shown. Returns the advanced cursor.
+        """
+        if cursor is not None:
+            cursor = as_utc(cursor)
+        events = self.search_audit(
+            AuditQuery(task_identifier=task_identifier, since=cursor, since_inclusive=True, limit=0)
+        )
+        # Audit search returns descending by timestamp; replay chronologically.
+        for ev in reversed(events):
+            event_id = ev.get('EventIdentifier')
+            if not event_id or event_id in seen:
+                continue
+            seen.add(event_id)
+            progress.log_event(ev)
+            ts_text = ev.get('Timestamp')
+            ts = parse_audit_timestamp(ts_text) if ts_text else None
+            if ts and (cursor is None or ts > cursor):
+                cursor = ts
+        return cursor
+
+    def create_task(self, task_xml: str) -> str:
+        """Create a task (POST ws/rest/tasks) and return its OID; a runnable task is started by the server."""
+        oid = self.api_client.create_element(MidpointObjectTypes.TASK.value, task_xml)
+        if oid is None:
+            raise MidpointServerError('The server accepted the task but did not report its OID')
+        return oid
+
+    def start_resource_task(
+        self,
+        operation: str,
+        resource: MidpointObject,
+        kind: str | None = None,
+        intent: str | None = None,
+        object_class: str | None = None,
+    ) -> tuple[str, str]:
+        """Create and start an import ('import') or reconciliation ('reconcile') task for a resource.
+
+        Returns the OID and name of the new task.
+        """
+        resource_oid = resource.get_oid()
+        if resource_oid is None:
+            raise AssertionError('Resource OID cannot be None')
+        name = resource_task_name(operation, resource.get_name() or resource_oid, kind, intent, object_class)
+        task_xml = resource_task_xml(operation, name, resource_oid, kind, intent, object_class)
+        return self.create_task(task_xml), name
+
+    def start_report_task(self, report: MidpointObject) -> tuple[str, str]:
+        """Create and start a classic export task for a report; returns the OID and name of the new task."""
+        report_oid = report.get_oid()
+        if report_oid is None:
+            raise AssertionError('Report OID cannot be None')
+        name = report_task_name(report.get_name() or report_oid)
+        return self.create_task(report_task_xml(name, report_oid)), name
+
+    def wait_for_task_start(self, task_oid: str) -> None:
+        """Wait until a newly created task has started (it has a result) or was stopped.
+
+        task_wait reads a task without a result as failed, so a new task is only handed to it
+        once the scheduler has picked it up.
+        """
+        for attempt in range(TASK_START_ATTEMPTS):
+            task = self.get_object(MidpointObjectTypes.TASK.value, task_oid)
+            if task.get('Result Status') or task.get('Execution Status') in (
+                TaskExecutionState.SUSPENDED,
+                TaskExecutionState.CLOSED,
+            ):
+                return
+            if attempt + 1 < TASK_START_ATTEMPTS:
+                time.sleep(TASK_START_POLL_SECONDS)
+        raise TaskExecutionFailure(
+            f'Task {task_oid} did not start within {TASK_START_ATTEMPTS * TASK_START_POLL_SECONDS} seconds; '
+            f'it is still waiting for the server to run it'
+        )
+
+    def run_new_task(
+        self,
+        task_oid: str,
+        progress_monitor: ProgressMonitor,
+        show_changes: bool = True,
+        run_started_at: datetime | None = None,
+    ) -> MidpointTask:
+        """Wait for a task created by create_task to start, then follow it to completion like task_wait."""
+        self.wait_for_task_start(task_oid)
+        return self.task_wait(task_oid, progress_monitor, show_changes=show_changes, run_started_at=run_started_at)
+
+    def test_resource(self, resource_oid: str) -> str:
+        response = self.api_client.execute_action(MidpointObjectTypes.RESOURCE.value, resource_oid, 'test')
+        tree = safe_fromstring(response)
+        status_node = tree.find('c:status', namespaces)
+        return status_node.text if status_node is not None and status_node.text is not None else 'unknown'
+
+    def get_xml(self, midpoint_type: MidpointObjectType, oid: str) -> str:
+        return self.api_client.get_element(midpoint_type, oid)
+
+    def put_xml(self, xml_file: str, patch_file: str | None = None, patch_write: bool = False) -> PutResult:
+        return self.api_client.put_element(xml_file, patch_file, patch_write)
+
+    def delete(self, midpoint_type: MidpointObjectType, oid: str) -> str:
+        return self.api_client.delete(midpoint_type, oid)
+
+    def search_audit(self, query: AuditQuery) -> MidpointObjectList:
+        """Run an audit search and return the matching events as MidpointAuditEvent objects.
+
+        Tunnels through ``rpc/executeScript`` because Midpoint has no REST endpoint
+        for audit search. Midpoint 4.11+ refuses that Groovy script by default; such
+        refusals are raised as ``MidpointAuditScriptRefused`` with the settings to change.
+        A script that does not compile or link against the server's internal classes
+        is raised as ``MidpointAuditScriptIncompatible``, naming the server version.
+        """
+        server_version = self.get_server_version()
+        try:
+            response_xml = self.api_client.post_xml(
+                AUDIT_EXEC_SCRIPT_PATH, build_execute_script_body(query, server_version)
+            )
+        except MidpointServerError as e:
+            replacement = audit_script_error(e, server_version)
+            if replacement is not None:
+                raise replacement from e
+            raise
+        return MidpointObjectList(parse_audit_events_from_script_response(response_xml))
+
+    def get_server_version(self) -> MidpointVersion | None:
+        """Return the server's Midpoint version, read once from ``actuator/info`` and cached.
+
+        Returns None when the server does not tell: callers then fall back to heuristics.
+        A failure to reach the server is not cached, so a later call tries again.
+        """
+        if not self._server_version_detected:
+            try:
+                self._remember_server_version(self._get_actuator_info())
+            except (MidpointServerError, ValueError) as e:
+                logger.debug('Could not detect the Midpoint server version: %s', e)
+                unreachable = isinstance(e, MidpointMissingPassword) or isinstance(
+                    e.__cause__, requests.RequestException
+                )
+                self._server_version_detected = not unreachable
+        return self._server_version
+
+    def _remember_server_version(self, actuator_info: dict[str, Any]) -> None:
+        self._server_version = parse_server_version(actuator_info.get('version'))
+        self._server_version_detected = True
+
+    def _get_actuator_info(self) -> dict[str, Any]:
+        raw = self.api_client.get_endpoint('actuator/info')
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            raise ValueError(f'Unexpected actuator/info content: {raw[:100]!r}')
+        return data
+
+    def get_logging_configuration(self) -> LoggingConfiguration:
+        """The root logger level and the class loggers of the system configuration."""
+        return parse_logging(
+            self.__get_object(MidpointObjectTypes.SYSTEM_CONFIGURATION.value, SYSTEM_CONFIGURATION_OID)
+        )
+
+    def set_class_logger(self, package: str, level: str) -> str:
+        """Set the level of a class logger in the system configuration, adding the logger if needed.
+
+        Only the logging items are patched, never the whole system configuration. Returns
+        'added', 'updated', or 'unchanged' when the logger already had that level (nothing is
+        sent then). Raises ValueError for an invalid level or logger name.
+        """
+        level = normalize_level(level)
+        package = check_logger_name(package)
+        existing = self.get_logging_configuration().loggers_of(package)
+        if existing and all(logger.level == level for logger in existing):
+            return 'unchanged'
+        self.api_client.patch_element(
+            MidpointObjectTypes.SYSTEM_CONFIGURATION.value,
+            SYSTEM_CONFIGURATION_OID,
+            class_logger_modification(existing, package, level),
+        )
+        return 'updated' if existing else 'added'
+
+    def get_system_info(self) -> dict[str, str]:
+        """The properties `info` shows, by name (see get_server_information)."""
+        return self.get_server_information().properties
+
+    def get_server_information(self) -> ServerInformation:
+        """Gather what `info` shows from actuator/info, the nodes, the system configuration and ws/rest/self.
+
+        Each source is read on its own, so one the account may not read (403) or a proxy hides
+        (404) only leaves its properties out and is listed in ``unavailable``. A failure every
+        other call would repeat (no answer, no password, 401) is raised at once, as is the
+        first error when no source could be read.
+        """
+        info = ServerInformation()
+        failures: list[MidpointServerError] = []
+
+        def read(source: str, reader: Callable[[], Any]) -> Any:
+            try:
+                return reader()
+            except (MidpointServerError, ValueError, ElementTree.ParseError) as e:
+                if isinstance(e, MidpointServerError) and _repeats_on_every_call(e):
+                    raise
+                logger.debug('Could not read %s: %s', source, e)
+                info.unavailable.append(f'{source}: {e}')
+                failures.append(e if isinstance(e, MidpointServerError) else MidpointServerError(f'{source}: {e}'))
+                return None
+
+        actuator = read('actuator/info', self._get_actuator_info)
+        nodes = read('nodes', lambda: parse_nodes(self.api_client.get_elements(MidpointObjectTypes.NODE.value)))
+        system_configuration = read(
+            'system configuration',
+            lambda: self.__get_object(MidpointObjectTypes.SYSTEM_CONFIGURATION.value, SYSTEM_CONFIGURATION_OID),
+        )
+        logged_in = read(
+            'ws/rest/self', lambda: parse_logged_in_user(safe_fromstring(self.api_client.get_endpoint('ws/rest/self')))
+        )
+
+        if actuator is not None:
+            if not self._server_version_detected:
+                self._remember_server_version(actuator)
+            for key, label in ACTUATOR_FIELDS:
+                if actuator.get(key):
+                    info.properties[label] = str(actuator[key])
+
+        # Without actuator/info, the build of the nodes still tells the version.
+        node_versions = sorted({node.version for node in nodes or [] if node.version})
+        version = self._server_version
+        if 'Midpoint Version' not in info.properties and node_versions:
+            info.properties['Midpoint Version'] = ', '.join(node_versions)
+            if len(node_versions) == 1:
+                version = parse_server_version(node_versions[0])
+
+        repository = describe_repository(version)
+        if repository is not None:
+            info.properties['Repository'] = repository
+        if system_configuration is not None:
+            info.properties.update(parse_deployment(system_configuration))
+        if nodes is not None:
+            info.properties['Nodes'] = str(len(nodes))
+            for node in nodes:
+                info.properties[f'Node {node.identifier}'] = node.describe()
+        if logged_in is not None:
+            info.properties['Logged In As'] = logged_in
+
+        if not info.properties and failures:
+            raise failures[0]
+        return info
+
+
+def _repeats_on_every_call(error: MidpointServerError) -> bool:
+    """Whether every further REST call would fail the same way: no password, no answer, or rejected credentials."""
+    return (
+        isinstance(error, MidpointMissingPassword)
+        or isinstance(error.__cause__, requests.RequestException)
+        or error.status_code == 401
+    )