API Reference
The API is accessible via the ECM() factory and is split into the following namespaces:
| Namespace | Description | Reference |
|---|---|---|
|
Folder, register, and document operations |
|
|
User and group management |
|
|
Server metadata and object definitions |
|
|
Direct SQL access via ADO |
|
|
Portfolios ("Mappen") and their content |
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 |
|---|---|
|
|
|
|
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 |
|---|---|
|
The identification given to |
|
An |
|
The server’s cause code from the error stack, |
|
The server’s own line, e.g. |
ECMImpersonationCause |
Stack code | Message of the exception (<user> is 'name' or GUID …) |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Same text; the lock marker was reset administratively but the server still refuses. |
|
|
|
|
|
|
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 |
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")