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). 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.

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)