history()

Returns the modification history of an object via DMS.GetObjectHistory. The server returns a UTF-16 encoded DMSHistory XML document which is parsed into an ECMHistory instance containing a list of ECMHistoryEntry objects, ordered newest first.

1. Signature

  • Sync

  • Async

ecm.dms.history(
    model: _ECMModelBase | int,
    object_type_id: int | None = None,
) -> ECMHistory
await ecm.dms.history(
    model: _ECMModelBase | int,
    object_type_id: int | None = None,
) -> ECMHistory

2. Parameters

Parameter Type Default Description

model

_ECMModelBase | int

 — 

Either an ECM model instance (its id is used) or a plain integer object ID.

object_type_id

int | None

None

The numeric object type ID. If None, the type is extracted from the model instance when available, or resolved via get_object_type_by_id() for plain integer IDs.

3. Return value

An ECMHistory instance.

3.1. ECMHistory fields

Field Type Description

server_version

str

Version string of the executing server.

timestamp

datetime

Server-side timestamp of the query.

entries

list[ECMHistoryEntry]

List of history entries, ordered newest first.

3.2. ECMHistoryEntry fields

Field Type Description

guid

str

Unique GUID of the history entry (hex string, no dashes).

time

datetime

Timestamp of the modification.

action

ECMHistoryAction | None

The history action type, or None if the action ID is unknown.

action_id

int

Raw numeric action ID from the server.

action_name

str

Localised short name of the action.

description

str

Localised long description of the action.

username

str

Internal user name (e.g. "ROOT").

display_name

str

Full display name of the user (e.g. "Administrator").

station

str

Hostname of the workstation.

station_id

str

GUID of the workstation.

info

str

Additional information about the action.

3.3. ECMHistoryAction enum

ECMHistoryAction is an IntEnum with 56 values (1—​56). The most commonly used members include:

Member ID Description

OBJECT_CREATED

2

The object was created.

INDEX_DATA_MODIFIED

3

The object’s index data was modified.

CONTENT_CHANGED

4

The document content was edited.

DOCUMENT_DELETED

6

The document was deleted.

VERSION_CREATED

17

A version was created for the document.

DOCUMENT_MOVED

21

The document location was changed.

OBJECT_INFORMATION

31

Log entry from the business model (created by set_history()).

DOCUMENT_EDITED_EXTERNALLY

56

The document was edited via an external application.

4. Exceptions

Exception Condition

ValueError

model is a model instance with id set to None.

ECMNotFoundException

object_type_id is None and no object with the given ID exists on the server.

5. Examples

5.1. Read history of a document

  • Sync

  • Async

doc = ecm.dms.get(InvoiceDocument, 12345)
history = ecm.dms.history(doc)
for entry in history.entries:
    print(f"{entry.time} {entry.action_name} by {entry.display_name}")
doc = await ecm.dms.get(InvoiceDocument, 12345)
history = await ecm.dms.history(doc)
for entry in history.entries:
    print(f"{entry.time} {entry.action_name} by {entry.display_name}")

5.2. Filter for version entries

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMHistoryAction

history = ecm.dms.history(12345)
versions = [e for e in history.entries if e.action == ECMHistoryAction.VERSION_CREATED]
for v in versions:
    print(f"Version GUID: {v.guid}, created at {v.time}")
from ecmind_blue_client.ecm import ECMHistoryAction

history = await ecm.dms.history(12345)
versions = [e for e in history.entries if e.action == ECMHistoryAction.VERSION_CREATED]
for v in versions:
    print(f"Version GUID: {v.guid}, created at {v.time}")

5.3. Use with a plain object ID

  • Sync

  • Async

# Provide object_type_id to avoid an extra server round trip
history = ecm.dms.history(12345, object_type_id=327685)
print(f"Server version: {history.server_version}")
print(f"Total entries: {len(history.entries)}")
history = await ecm.dms.history(12345, object_type_id=327685)
print(f"Server version: {history.server_version}")
print(f"Total entries: {len(history.entries)}")

6. See also

  • set_history() — Add a custom history entry

  • files() — Download files of a specific version via version_guid