users()

Returns all user accounts known to the server. With extended_info=True, additional fields are populated for each user.

1. Signature

  • Sync

  • Async

ecm.security.users(*, extended_info: bool = False) -> list[ECMUser]
await ecm.security.users(*, extended_info: bool = False) -> list[ECMUser]

2. Parameters

Parameter Default Description

extended_info

False

When True, additionally populates groups, remark, valid_from, and valid_to for each user.

3. Return value

List of ECMUser instances, one per user account.

3.1. ECMUser fields

Field Type Description

id

int

Numeric user ID.

username

str

Short internal user name.

login_name

str

Login credential name used for authentication.

display_name

str

Full display name.

email

str

E-mail address.

guid

str

Globally unique identifier of the user account.

profile_id

int

Profile ID: -1 = no profile, 0 = user profile, >0 = assigned profile.

locked

bool

True if the account is locked, for whichever reason.

locked_cause

ECMUserLockCause

Why the account is locked: NONE (0), ADMINISTRATIVE (1) or FAILED_LOGINS (2). Mirrors the server’s tri-state locked attribute.

remark

str

Optional remark from the user configuration. Only populated with extended_info=True.

valid_from

datetime | None

Account valid-from date. Only populated with extended_info=True.

valid_to

datetime | None

Account valid-to date. Only populated with extended_info=True.

groups

list[str]

Names of groups the user belongs to. Only populated with extended_info=True.

The server attribute locked is tri-state, not boolean. enaio reports a lockout caused by too many failed logins as 2 and an administrative lock as 1. locked is True for both, locked_cause tells them apart.

The 2 marker survives only until the next write to the account. The lock itself follows the failed-attempt counter and outlives it, although the attribute then reads 0 again. From that point on only check_user_account() reveals the state.

4. Examples

4.1. List all users

  • Sync

  • Async

users = ecm.security.users()
for user in users:
    print(user.username, user.display_name, user.email)
    if user.locked:
        print(f"  → locked")
users = await ecm.security.users()
for user in users:
    print(user.username, user.display_name, user.email)

4.2. Include group membership

  • Sync

  • Async

users = ecm.security.users(extended_info=True)
for user in users:
    print(user.username, user.groups)
users = await ecm.security.users(extended_info=True)
for user in users:
    print(user.username, user.groups)

4.3. Find locked accounts

  • Sync

  • Async

locked = [u for u in ecm.security.users() if u.locked]
print(f"{len(locked)} locked accounts")
locked = [u for u in await ecm.security.users() if u.locked]
print(f"{len(locked)} locked accounts")

5. See also