API-Referenz

Die API ist über die ECM()-Factory zugänglich und in folgende Namespaces unterteilt:

Namespace Beschreibung Referenz

ecm.dms

Ordner-, Register- und Dokumentenoperationen

→ ecm.dms

ecm.security

Benutzer- und Gruppenverwaltung

→ ecm.security

ecm.system

Server-Metadaten und Objektdefinitionen

→ ecm.system

ecm.db

Direkter SQL-Zugriff über ADO

→ ecm.db

ecm.portfolio

Mappen (Portfolios) und ihre Inhalte

→ ecm.portfolio

1. ECM-Factory

from ecmind_blue_client.ecm import ECM
from ecmind_blue_client.pool import SyncPoolClient

client = SyncPoolClient(servers="<host>:4000:1", username="<username>", password="<password>")
ecm = ECM(client)

Die ECM()-Funktion ist überladen: Ein SyncPoolClient liefert ECMSync, ein AsyncPoolClient liefert ECMAsync.

2. impersonate()

ecm.impersonate(
    username: str | None = None,
    *,
    user_guid: str | None = None,
) -> ECMSync | ECMAsync

Gibt eine neue ECM-Instanz zurück, die alle Anfragen mit dem angegebenen Benutzerkontext ausführt. Der Zielbenutzer kann auf zwei Wege angegeben werden, jeder davon über einen eigenen Serverparameter:

Argument Serverparameter

username

$SwitchContextUserName$

user_guid

$SwitchContextUserGUID$

Genau eines der beiden Argumente muss gesetzt sein, andernfalls wird ein ValueError ausgelöst. Ein str ist immer ein Benutzername, niemals eine GUID — Benutzernamen können nur aus Ziffern bestehen oder wie eine GUID aussehen, deshalb müssen GUIDs explizit über user_guid übergeben werden.

Der ausführende Benutzer benötigt die Systemrolle Kontextwechsel.

2.1. Wenn der Wechsel abgelehnt wird

impersonate() selbst macht keine Serverrunde. Kann der Server den Zielbenutzer nicht annehmen, wirft der erste Job, der über die zurückgegebene Instanz läuft, eine ECMImpersonationException. Der Server antwortet in allen diesen Fällen mit dem Sammelcode -1043332467 und nennt die Ursache nur in seinem Fehlerstack; die Exception liest sie dort aus und formuliert ihre Meldung selbst, in der dritten Person und mit dem Zielbenutzer, statt den Servertext weiterzureichen.

Attribut Inhalt

username / user_guid

Die an impersonate() übergebene Kennung; das jeweils andere ist None.

cause

Ein Member von ECMImpersonationCause, oder None bei einem der Bibliothek unbekannten Code.

cause_code

Der Ursachencode des Servers aus dem Fehlerstack, None, wenn der Stack keinen auswertbaren Eintrag enthielt.

cause_message

Die eigene Zeile des Servers, z. B. Login for user X valid up to 2026/03/25 12:00:00.; die Gültigkeitszeitpunkte bei EXPIRED und NOT_YET_VALID stehen nur hier.

ECMImpersonationCause Stack-Code Meldung der Exception (<user> ist 'name' oder GUID …)

USER_UNKNOWN

1105265591

The user <user> is unknown; the context switch is not possible.

ACCOUNT_LOCKED

-1042218150

The user account <user> is blocked; the context switch is not possible.

LOCKED_BY_FAILED_LOGINS

-1042218334

The user account <user> is locked after failed logins; the context switch is not possible.

LOCKED_BY_FAILED_LOGINS_RESET

-1042218331

Gleicher Text; der Sperrmarker wurde administrativ zurückgesetzt, der Server lehnt trotzdem ab.

EXPIRED

-1042218315

The user account <user> has expired; the context switch is not possible.

NOT_YET_VALID

-1042218317

The user account <user> is not yet valid; the context switch is not possible.

Gemessen auf enaio 12.0: USER_UNKNOWN, LOCKED_BY_FAILED_LOGINS und EXPIRED; die übrigen Ursachen folgen der Serverreferenz. Der Sammelcode bezieht sich nur auf den Kontextwechsel, nie auf einen Benutzerparameter des Jobs selbst (etwa UserGUID von mng.GetUserRoles). Der vollständige Fehlerstack des Servers samt SEH-Dump bleibt über cause erreichbar.

from ecmind_blue_client.ecm import ECMImpersonationCause, ECMImpersonationException

try:
    roles = ecm.impersonate("john").security.roles()
except ECMImpersonationException as error:
    if error.cause is ECMImpersonationCause.USER_UNKNOWN:
        print("Benutzer unbekannt")
    else:
        print(error)   # z. B. "The user account 'john' is blocked; the context switch is not possible."

Eine Identifikation über die numerische Benutzer-ID gibt es bewusst nicht. enaio 12.0 nimmt den Parameter $SwitchContextUserID$ entgegen, wertet ihn aber nicht aus: Der Job läuft ohne Fehlermeldung weiter unter dem angemeldeten Benutzer, mit dessen Rechten und dessen Eigentümer-GUID auf neu angelegten Objekten. Das frühere Argument user_id wurde deshalb entfernt (verifiziert am 2026-09-22 gegen 12.0 Build 799).

Unterstützt sowohl den direkten Aufruf als auch die Verwendung als Context-Manager (with / async with).

  • Sync

  • Async

with ecm.impersonate("john") as ecm_john:
    ecm_john.dms.insert(MyFolder(Title="Test"))
async with ecm.impersonate("john") as ecm_john:
    await ecm_john.dms.insert(MyFolder(Title="Test"))

Die Angabe über die GUID funktioniert genauso:

ecm_john = ecm.impersonate(user_guid="8A1D1F2E4C7B4A9E8F0D3C5B7A9E1D2F")