process_list_by_object()

Returns the workflow processes whose file contains a given DMS object via wfm.GetProcessListByObject.

1. Signature

  • Sync

  • Async

ecm.workflow.process_list_by_object(
    obj: int | ECMWorkspaceDocument | ECMFolderModel | ECMRegisterModel | ECMDocumentModel,
    organisation: str | ECMOrganisation | None = None,
    *,
    user: str | ECMOrganisationObject | ECMOrganisationObjectRef | None = None,
    all_processes: bool = False,
) -> list[ECMObjectProcess]
await ecm.workflow.process_list_by_object(
    obj: int | ECMWorkspaceDocument | ECMFolderModel | ECMRegisterModel | ECMDocumentModel,
    organisation: str | ECMOrganisation | None = None,
    *,
    user: str | ECMOrganisationObject | ECMOrganisationObjectRef | None = None,
    all_processes: bool = False,
) -> list[ECMObjectProcess]

2. Parameters

Parameter Type Description

obj

int | ECMWorkspaceDocument | model instance

The DMS object: its numeric ID, an ECMWorkspaceDocument, or a loaded typed model instance whose system.id is read.

organisation

str | ECMOrganisation | None

The organisation as a GUID or as an ECMOrganisation. Defaults to the active organisation when omitted.

user

str | ECMOrganisationObject | ECMOrganisationObjectRef | None

Optional workflow-organisation user. When given, is_process_responsible tells for each process whether that user is one of its process responsibles. Omitted, the flag is always False. This is the workflow-organisation GUID, not the security-system user ID.

all_processes

bool

False (the server default) lists running processes only. True adds ended processes from the history.

3. Return value

A list of ECMObjectProcess instances in server order. Returns an empty list when no process holds the object.

Measured on enaio 12.0:

  • An unknown object ID is not an error; the server answers <Processes><Resources/></Processes>, which reads as an empty list.

  • Ended processes are listed only with all_processes=True, with state 16 (TERMINATED) and an empty activities tuple.

  • activities holds the activities that currently have a work item. Right after start_process() it is still empty until the engine has created the first work item, about three seconds later; the activity then appears with state 64 and no owner.

  • An unknown, empty or foreign user GUID is accepted and simply yields is_process_responsible = False.

3.1. ECMObjectProcess fields

Field Type Description

id

str

GUID of the process instance (Id).

name

str

Instance name of the process (Name).

subject

str

Subject of the process (Subject), empty when none was set.

state

int

Raw process state (State): 1 INIT, 2 RUNNING, 4 SUSPENDED, 8 ACTIVE, 16 TERMINATED, 32 COMPLETED, 64 SYSSUSPENDED.

creator_id

str

GUID of the workflow-organisation user who started the process (CreatorId).

creator_name

str

Display name of that user (CreatorName).

created_at

datetime | None

Start time as a UTC datetime (CreationTime). None where the server reported 0.

is_process_responsible

bool

True when the user passed to the query is a process responsible of this process (ProcessResponsible).

activities

tuple[ECMObjectProcessActivity, …​]

The activities currently holding a work item. Empty for ended processes and for a moment after the start.

localised_names

Mapping[str, str]

Instance name per locale, resolved from the <Resources> block via ProcessNameResId.

localised_subjects

Mapping[str, str]

Subject per locale, resolved via ProcessSubjectResId.

3.2. ECMObjectProcessActivity fields

Field Type Description

name

str

Technical activity name (Name).

state

int

Raw activity-state bitmask (State): 128 personalised, 64 not personalised.

ended_at

datetime | None

End time as a UTC datetime (EndTime). None while the activity runs.

owner

str

Name of the user currently owning the activity (Owner), empty when nobody has taken it.

owner_id

str

GUID of the owning user (OwnerId), empty when nobody has taken it.

performers

tuple[ECMObjectProcessPerformer, …​]

The organisation objects the activity is addressed to (<Objects>).

localised_names

Mapping[str, str]

Activity name per locale, resolved via ActivityNameResId.

3.3. ECMObjectProcessPerformer fields

Field Type Description

id

str

GUID of the workflow-organisation object (Id).

name

str

Display name of the organisation object (Name).

email

str

E-mail address (EMail), empty when unset.

is_user

bool

True for a user object, False for a role or group (User).

absent

bool

True when the user is marked absent (Absent).

substitute

bool

True when the entry is a substitute of the actual performer (Substitute).

flags

int

Raw performer flags (Flags); 7 measured for an ordinary user performer.

The server manual documents only flat attributes on <Process>. Measured on enaio 12.0 the response additionally carries CreatorName, the <Activities> block with the performers of each activity, the *ResId attributes and a trailing <Resources> block with the localised texts per locale. The client maps all of it; the resource IDs are not exposed.

4. Examples

4.1. Processes of a document

  • Sync

  • Async

for process in ecm.workflow.process_list_by_object(document_id):
    owners = ", ".join(a.owner or "-" for a in process.activities)
    print(f"{process.name} ({process.state}) owned by {owners}")
for process in await ecm.workflow.process_list_by_object(document_id):
    owners = ", ".join(a.owner or "-" for a in process.activities)
    print(f"{process.name} ({process.state}) owned by {owners}")

4.2. Including ended processes, from a loaded model

  • Sync

  • Async

document = ecm.dms.get(Invoice, document_id)
processes = ecm.workflow.process_list_by_object(document, all_processes=True)
ended = [p for p in processes if p.state & 16]
document = await ecm.dms.get(Invoice, document_id)
processes = await ecm.workflow.process_list_by_object(document, all_processes=True)
ended = [p for p in processes if p.state & 16]

4.3. Responsibility of a user

  • Sync

  • Async

user = ecm.workflow.organisation_user_by_login("root")
for process in ecm.workflow.process_list_by_object(document_id, user=user):
    print(process.name, process.is_process_responsible)
user = await ecm.workflow.organisation_user_by_login("root")
for process in await ecm.workflow.process_list_by_object(document_id, user=user):
    print(process.name, process.is_process_responsible)

5. See also