= get()
:description: Loads a single ECM object by its object_id. Expects a typed model class and returns a fully populated instance or raises ECMNotFoundException.
:keywords: get, object_id, ECMNotFoundException, model class, instance, ECMFolderModel, ECMDocumentModel
:page-tags: api, dms

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.

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

== Signature

[tabs]
====
Sync::
+
[source,python]
----
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
----

Async::
+
[source,python]
----
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
----
====

== Parameters

[cols="1,1,3"]
|===
|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`.
|===

== Return value

A typed model instance of the requested object.

== Exceptions

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

== Retrieval modes

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

[cols="1,1,1"]
|===
| |`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`
|===

[NOTE]
====
`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`.
====

== Examples

=== Simple fetch

[tabs]
====
Sync::
+
[source,python]
----
folder = ecm.dms.get(InvoiceFolder, 12345)
print(folder.Title, folder.Year)
----

Async::
+
[source,python]
----
folder = await ecm.dms.get(InvoiceFolder, 12345)
print(folder.Title, folder.Year)
----
====

=== With error handling

[tabs]
====
Sync::
+
[source,python]
----
from ecmind_blue_client.ecm import ECMNotFoundException

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

Async::
+
[source,python]
----
from ecmind_blue_client.ecm import ECMNotFoundException

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

=== Rights and administrative parameters

[tabs]
====
Sync::
+
[source,python]
----
folder = ecm.dms.get(InvoiceFolder, 12345, rights=True, base_params=True)
print(folder.system.rights.edit_metadata)
print(folder.system.base_params.creator)
----

Async::
+
[source,python]
----
folder = await ecm.dms.get(InvoiceFolder, 12345, rights=True, base_params=True)
print(folder.system.rights.edit_metadata)
print(folder.system.base_params.creator)
----
====

=== Document with file information and variants

[tabs]
====
Sync::
+
[source,python]
----
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 "")
----

Async::
+
[source,python]
----
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 "")
----
====

=== Fetch document location fields (use_result_list)

`folder_id` and `register_id` are only available with `use_result_list=True`:

[tabs]
====
Sync::
+
[source,python]
----
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
----

Async::
+
[source,python]
----
doc = await ecm.dms.get(InvoiceDocument, 12345, use_result_list=True)
print(doc.system.folder_id)
print(doc.system.register_id)
----
====

=== Load only specific fields (use_result_list + fields)

[tabs]
====
Sync::
+
[source,python]
----
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)
----

Async::
+
[source,python]
----
folder = await ecm.dms.get(
    InvoiceFolder, 12345,
    use_result_list=True,
    fields=[InvoiceFolder.Title, InvoiceFolder.Year],
)
print(folder.Title, folder.Year)
----
====
