= insert_and_get()
:description: Creates a new ECM object (dms.XMLInsert) and immediately reads back the full instance with all server-populated fields. Combines insert() and get() in one call.
:keywords: insert_and_get, XMLInsert, instance, server fields, create object, ECMFolderModel, ECMDocumentModel
:page-tags: api, dms

Combines xref:api/dms/insert.adoc[insert()] and xref:api/dms/get.adoc[get()] into a single call: creates a new object and immediately returns the fully server-populated model instance. Raises `ECMException` if the server rejects the insert.

== Signature

[tabs]
====
Sync::
+
[source,python]
----
ecm.dms.insert_and_get(
    model: T,
    files: list[JobRequestFile] | None = None,
    *,
    folder_id: int | ECMFolderModel | None = None,
    register_id: int | ECMRegisterModel | None = None,
    check_mandatory: bool = True,
    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.insert_and_get(
    model: T,
    files: list[JobRequestFile] | None = None,
    *,
    folder_id: int | ECMFolderModel | None = None,
    register_id: int | ECMRegisterModel | None = None,
    check_mandatory: bool = True,
    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

=== Insert parameters

[cols="1,1,3"]
|===
|Name |Type |Description

|`model`
|`ECMFolderModel \| ECMRegisterModel \| ECMDocumentModel`
|The model instance to create, with the desired field values set. The instance is not mutated.

|`files`
|`list[JobRequestFile] \| None`
|Optional list of files to attach to the new document. Only allowed for `ECMDocumentModel` — raises `TypeError` for folder or register models. Default: `None`.

|`folder_id`
|`int \| ECMFolderModel \| None`
|Folder to place the object in — either a numeric ID or an `ECMFolderModel` instance. Only valid for registers and documents. Default: `None`.

|`register_id`
|`int \| ECMRegisterModel \| None`
|Register to file the document in (`ECMDocumentModel`) or parent register (`ECMRegisterModel`) — either a numeric ID or an `ECMRegisterModel` instance. Default: `None`.

|`check_mandatory`
|`bool`
|When `True` (default), validates client-side that all `mandatory=True` fields are set. When `False`, both client-side and server-side obligation checks are disabled (`CHECKOBLIGATION=0`).
|===

=== Get parameters

The following parameters are forwarded unchanged to xref:api/dms/get.adoc[get()]. See the get() reference for full details and behaviour.

[cols="1,1,3"]
|===
|Name |Type |Summary

|`rights`
|`bool`
|Fetch access rights (`obj.system.rights`). Default: `False`.

|`base_params`
|`bool`
|Fetch administrative metadata (`obj.system.base_params`). Default: `False`.

|`file_properties`
|`bool`
|Fetch file metadata (`obj.system.file_properties`, documents only). Default: `False`.

|`variants`
|`bool`
|Fetch W-module version branches (`obj.system.variants`). Default: `False`.

|`use_result_list`
|`bool`
|Switch retrieval mode (enables `folder_id`/`register_id` in result). Default: `False`.

|`fields`
|`list[str \| ECMField] \| None`
|Restrict returned fields. Only effective with `use_result_list=True`. Default: `None`.
|===

== Return value

A typed model instance populated with all server-side field values (ID, system fields, index fields).

== Exceptions

`ECMException`:: The server rejected the insert (`ObjectID == -1`).
`TypeError`:: `files` was provided for a folder or register model.
`ValueError`:: `check_mandatory=True` and a required field is not set.

== Examples

=== Simple folder

[tabs]
====
Sync::
+
[source,python]
----
folder = ecm.dms.insert_and_get(InvoiceFolder(Title="Invoice 2024", Year=2024))
print(folder.system.id, folder.Title)
----

Async::
+
[source,python]
----
folder = await ecm.dms.insert_and_get(InvoiceFolder(Title="Invoice 2024", Year=2024))
print(folder.system.id, folder.Title)
----
====

=== Register inside a folder

[tabs]
====
Sync::
+
[source,python]
----
register = ecm.dms.insert_and_get(
    InvoiceRegister(Name="Incoming invoices"),
    folder_id=folder.system.id,
)
print(register.system.id)
----

Async::
+
[source,python]
----
register = await ecm.dms.insert_and_get(
    InvoiceRegister(Name="Incoming invoices"),
    folder_id=folder.system.id,
)
print(register.system.id)
----
====

=== Document with file and filing location

[tabs]
====
Sync::
+
[source,python]
----
from ecmind_blue_client.rpc import JobRequestFileFromPath

doc = ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    files=[JobRequestFileFromPath("/tmp/invoice.pdf")],
    folder_id=folder.system.id,
    register_id=register.system.id,
)
print(doc.system.id)
----

Async::
+
[source,python]
----
from ecmind_blue_client.rpc import JobRequestFileFromPath

doc = await ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    files=[JobRequestFileFromPath("/tmp/invoice.pdf")],
    folder_id=folder.system.id,
    register_id=register.system.id,
)
print(doc.system.id)
----
====

=== With metadata from get()

The `rights`, `base_params`, and `file_properties` parameters behave identically to xref:api/dms/get.adoc[get()]:

[tabs]
====
Sync::
+
[source,python]
----
doc = ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    files=[JobRequestFileFromPath("/tmp/invoice.pdf")],
    folder_id=folder.system.id,
    rights=True,
    base_params=True,
    file_properties=True,
)
print(doc.system.rights.edit_metadata)
print(doc.system.base_params.creator)
print(doc.system.file_properties.extension)
----

Async::
+
[source,python]
----
doc = await ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    files=[JobRequestFileFromPath("/tmp/invoice.pdf")],
    folder_id=folder.system.id,
    rights=True,
    base_params=True,
    file_properties=True,
)
print(doc.system.rights.edit_metadata)
print(doc.system.base_params.creator)
print(doc.system.file_properties.extension)
----
====

=== Read filing location from result (use_result_list)

`folder_id` and `register_id` in the result are only available with `use_result_list=True` — see xref:api/dms/get.adoc#_retrieval_modes[Retrieval modes in get()]:

[tabs]
====
Sync::
+
[source,python]
----
doc = ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    folder_id=folder.system.id,
    use_result_list=True,
)
print(doc.system.folder_id)
print(doc.system.register_id)
----

Async::
+
[source,python]
----
doc = await ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    folder_id=folder.system.id,
    use_result_list=True,
)
print(doc.system.folder_id)
print(doc.system.register_id)
----
====
