get()

Loads a single object from the server by its ID and returns it as a typed model instance. Raises ECMNotFoundException if no object with the given ID exists.

ECM Model reference — for a full description of all system properties (system.id, system.rights, system.base_params, system.file_properties, etc.) and how change tracking works.

Two retrieval modes are available internally, differing in scope and performance — see [_retrieval_modes].

1. Signature

  • Sync

  • Async

ecm.dms.get(
    model_class: type[T],
    object_id: int,
    object_type_id: int | None = None,
    *,
    rights: bool = False,
    base_params: bool = False,
    file_properties: bool = False,
    variants: bool = False,
    use_result_list: bool = False,
    fields: list[str | ECMField] | None = None,
) -> T
await ecm.dms.get(
    model_class: type[T],
    object_id: int,
    object_type_id: int | None = None,
    *,
    rights: bool = False,
    base_params: bool = False,
    file_properties: bool = False,
    variants: bool = False,
    use_result_list: bool = False,
    fields: list[str | ECMField] | None = None,
) -> T

2. Parameters

Name Type Description

model_class

type[T]

The model class of the object to load. Determines the object type and the returned fields.

object_id

int

The numeric ID of the object to load.

object_type_id

int | None

Optional numeric object type ID. Only evaluated in standard mode (use_result_list=False); ignored when use_result_list=True. If omitted, the server determines the type automatically.

rights

bool

When True, the access rights of the logged-in user are fetched (populates obj.system.rights). The insert quotas are requested along with them, because the server otherwise always reports insert as denied. Default: False.

base_params

bool

When True, administrative parameters are fetched (populates obj.system.base_params): creator, creation date, owner, last modifier, modification date. Default: False.

file_properties

bool

When True, file metadata is fetched (populates obj.system.file_properties). Relevant only for document types. Default: False.

variants

bool

When True, W-module version branches are fetched (populates obj.system.variants). Available in both modes. Default: False.

use_result_list

bool

Switches the retrieval mode — see [_retrieval_modes]. Default: False.

fields

list[str | ECMField] | None

Restricts the returned fields. Only effective when use_result_list=True; silently ignored when use_result_list=False. None returns all fields. Default: None.

3. Return value

A typed model instance of the requested object.

4. Exceptions

ECMNotFoundException

Raised when no object with the given ID exists on the server.

5. Retrieval modes

get() supports two internal retrieval methods that differ in scope and constraints:

use_result_list=False (default) use_result_list=True

Server job

dms.GetObjectDetails

dms.GetResultList (HOL)

Performance

Faster (direct ID lookup)

Slower (query + paging)

Document location fields
(folder_id, register_id)

Not available

Available

variants

Available

Available

fields

Not available (ignored)

Available

Objects without a filing location
(no folder/register)

Can be fetched

Raises ECMNotFoundException

use_result_list=True requires the object to be placed in the filing structure (i.e. assigned to a folder or register). Objects without a filing location cannot be found via GetResultList.

Both retrieval modes fetch the index data inline as the BASE64 parameter XML (Flags=0) rather than as a response file. The file costs a second network round trip per call, because the server writes parameter block and result separately and the client has to wait for the 32-byte file header. For a single object the payload is tiny, so the detour is pure loss: measured against a test server at 20 ms RTT, one get() dropped from 64 ms to 30 ms, and ten consecutive calls from 650 ms to 331 ms.

6. Examples

6.1. Simple fetch

  • Sync

  • Async

folder = ecm.dms.get(InvoiceFolder, 12345)
print(folder.Title, folder.Year)
folder = await ecm.dms.get(InvoiceFolder, 12345)
print(folder.Title, folder.Year)

6.2. With error handling

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMNotFoundException

try:
    folder = ecm.dms.get(InvoiceFolder, 12345)
    print(folder.Title)
except ECMNotFoundException:
    print("Object not found")
from ecmind_blue_client.ecm import ECMNotFoundException

try:
    folder = await ecm.dms.get(InvoiceFolder, 12345)
    print(folder.Title)
except ECMNotFoundException:
    print("Object not found")

6.3. Rights and administrative parameters

  • Sync

  • Async

folder = ecm.dms.get(InvoiceFolder, 12345, rights=True, base_params=True)
print(folder.system.rights.edit_metadata)
print(folder.system.base_params.creator)
folder = await ecm.dms.get(InvoiceFolder, 12345, rights=True, base_params=True)
print(folder.system.rights.edit_metadata)
print(folder.system.base_params.creator)

6.4. Document with file information and variants

  • Sync

  • Async

doc = ecm.dms.get(InvoiceDocument, 12345, file_properties=True, variants=True)
print(doc.system.file_properties.extension, doc.system.file_properties.size)
for v in doc.system.variants:
    print(v.doc_ver, "active" if v.is_active else "")
doc = await ecm.dms.get(InvoiceDocument, 12345, file_properties=True, variants=True)
print(doc.system.file_properties.extension, doc.system.file_properties.size)
for v in doc.system.variants:
    print(v.doc_ver, "active" if v.is_active else "")

6.5. Fetch document location fields (use_result_list)

folder_id and register_id are only available with use_result_list=True:

  • Sync

  • Async

doc = ecm.dms.get(InvoiceDocument, 12345, use_result_list=True)
print(doc.system.folder_id)    # ID of the parent folder
print(doc.system.register_id)  # ID of the parent register
doc = await ecm.dms.get(InvoiceDocument, 12345, use_result_list=True)
print(doc.system.folder_id)
print(doc.system.register_id)

6.6. Load only specific fields (use_result_list + fields)

  • Sync

  • Async

folder = ecm.dms.get(
    InvoiceFolder, 12345,
    use_result_list=True,
    fields=[InvoiceFolder.Title, InvoiceFolder.Year],
)
print(folder.Title, folder.Year)
# folder.Status is None (not requested)
folder = await ecm.dms.get(
    InvoiceFolder, 12345,
    use_result_list=True,
    fields=[InvoiceFolder.Title, InvoiceFolder.Year],
)
print(folder.Title, folder.Year)