API Reference

The API is accessible via the ECM() factory and is split into the following namespaces:

Namespace Description Reference

ecm.dms

Folder, register, and document operations

→ ecm.dms

ecm.security

User and group management

→ ecm.security

ecm.system

Server metadata and object definitions

→ ecm.system

ecm.db

Direct SQL access via ADO

→ ecm.db

ecm.portfolio

Portfolios ("Mappen") and their content

→ 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)

The ECM() function is overloaded: passing a SyncPoolClient returns ECMSync; passing an AsyncPoolClient returns ECMAsync.

2. impersonate()

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

Returns a new ECM instance that injects the given user context into every request. The target user can be identified in two ways, each mapping to its own server parameter:

Argument Server parameter

username

$SwitchContextUserName$

user_guid

$SwitchContextUserGUID$

Exactly one of the two must be given, otherwise ValueError is raised. A str is always treated as a user name, never as a GUID — user names may consist of digits or look like a GUID, so GUIDs must be passed explicitly via user_guid.

The executing user requires the Context Switch system role.

2.1. When the switch is refused

impersonate() itself performs no server round trip. When the server cannot assume the target user, the first job executed through the returned instance raises an ECMImpersonationException. The server answers every such case with the collective return code -1043332467 and names the cause only in its error stack; the exception reads it from there and phrases its own message, in the third person and naming the target user, instead of forwarding the server’s text.

Attribute Content

username / user_guid

The identification given to impersonate(); the other one is None.

cause

An ECMImpersonationCause member, or None for a code the library does not know.

cause_code

The server’s cause code from the error stack, None when the stack carried no evaluable entry.

cause_message

The server’s own line, e.g. Login for user X valid up to 2026/03/25 12:00:00.; the validity dates of EXPIRED and NOT_YET_VALID are only here.

ECMImpersonationCause Stack code Message of the exception (<user> is 'name' or 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

Same text; the lock marker was reset administratively but the server still refuses.

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.

Measured on enaio 12.0: USER_UNKNOWN, LOCKED_BY_FAILED_LOGINS and EXPIRED; the remaining causes follow the server reference. The collective code refers to the context switch only, never to a user parameter of the job itself (such as UserGUID of mng.GetUserRoles). The complete server error stack, including its SEH dump, stays reachable through cause.

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("no such user")
    else:
        print(error)   # e.g. "The user account 'john' is blocked; the context switch is not possible."

Identification by numeric user ID is deliberately not offered. enaio 12.0 accepts the $SwitchContextUserID$ parameter but never evaluates it: the job keeps running as the logged-in user, with that user’s permissions and owner GUID on newly created objects, and without any error. The former user_id argument was removed for that reason (verified 2026-09-22 against 12.0 build 799).

Supports both direct usage and use as a 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"))

Identification by GUID works the same way:

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