= insert_and_get()
:description: Legt ein neues ECM-Objekt an (dms.XMLInsert) und liest die vollständige Instanz mit allen Serverfeldern zurück. Kombiniert insert() und get() in einem Aufruf.
:keywords: insert_and_get, XMLInsert, Instanz, Serverfelder, Objekt anlegen, ECMFolderModel, ECMDocumentModel
:page-tags: api, dms

Kombiniert xref:api/dms/insert.adoc[insert()] und xref:api/dms/get.adoc[get()] in einem einzigen Aufruf: Legt ein neues Objekt an und gibt sofort die vollständige, vom Server befüllte Modell-Instanz zurück. Wirft `ECMException`, wenn der Server den Insert ablehnt.

== Signatur

[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
----
====

== Parameter

=== Insert-Parameter

[cols="1,1,3"]
|===
|Name |Typ |Beschreibung

|`model`
|`ECMFolderModel \| ECMRegisterModel \| ECMDocumentModel`
|Die zu erstellende Modell-Instanz mit den gewünschten Feldwerten. Die Instanz wird nicht verändert.

|`files`
|`list[JobRequestFile] \| None`
|Optionale Dateiliste für das neue Dokument. Nur für `ECMDocumentModel` erlaubt — bei Ordner- oder Register-Modellen wird `TypeError` geworfen. Standard: `None`.

|`folder_id`
|`int \| ECMFolderModel \| None`
|Ordner, in dem das Objekt abgelegt wird — entweder eine numerische ID oder eine `ECMFolderModel`-Instanz. Nur für Register und Dokumente gültig. Standard: `None`.

|`register_id`
|`int \| ECMRegisterModel \| None`
|Register, in dem das Dokument abgelegt wird (`ECMDocumentModel`), oder übergeordnetes Register (`ECMRegisterModel`) — entweder als numerische ID oder als `ECMRegisterModel`-Instanz. Standard: `None`.

|`check_mandatory`
|`bool`
|Wenn `True` (Standard), wird clientseitig geprüft, ob alle als `mandatory=True` deklarierten Felder gesetzt sind. Bei `False` wird sowohl die client- als auch die serverseitige Pflichtfeldprüfung deaktiviert (`CHECKOBLIGATION=0`).
|===

=== Get-Parameter

Die folgenden Parameter werden unverändert an xref:api/dms/get.adoc[get()] weitergeleitet. Detailbeschreibung und Verhalten siehe dort.

[cols="1,1,3"]
|===
|Name |Typ |Kurzübersicht

|`rights`
|`bool`
|Zugriffsrechte mit abrufen (`obj.system.rights`). Standard: `False`.

|`base_params`
|`bool`
|Verwaltungsparameter mit abrufen (`obj.system.base_params`). Standard: `False`.

|`file_properties`
|`bool`
|Datei-Metadaten mit abrufen (`obj.system.file_properties`, nur Dokumente). Standard: `False`.

|`variants`
|`bool`
|W-Modul-Versionsverzweigungen mit abrufen (`obj.system.variants`). Standard: `False`.

|`use_result_list`
|`bool`
|Abrufmodus umschalten (ermöglicht `folder_id`/`register_id` im Ergebnis). Standard: `False`.

|`fields`
|`list[str \| ECMField] \| None`
|Zurückgegebene Felder einschränken. Nur bei `use_result_list=True` wirksam. Standard: `None`.
|===

== Rückgabewert

Eine typisierte Modell-Instanz mit allen vom Server befüllten Feldern (ID, Systemfelder, Indexfelder).

== Ausnahmen

`ECMException`:: Der Server hat den Insert abgelehnt (`ObjectID == -1`).
`TypeError`:: `files` wurde für ein Ordner- oder Register-Modell übergeben.
`ValueError`:: `check_mandatory=True` und ein Pflichtfeld ist nicht gesetzt.

== Beispiele

=== Einfacher Ordner

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

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

=== Register in einem Ordner ablegen

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

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

=== Dokument mit Datei und Ablageort

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

doc = ecm.dms.insert_and_get(
    InvoiceDocument(Title="Rechnung Nr. 42"),
    files=[JobRequestFileFromPath("/tmp/rechnung.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="Rechnung Nr. 42"),
    files=[JobRequestFileFromPath("/tmp/rechnung.pdf")],
    folder_id=folder.system.id,
    register_id=register.system.id,
)
print(doc.system.id)
----
====

=== Mit Metadaten aus get()

Die `rights`-, `base_params`- und `file_properties`-Parameter verhalten sich identisch zu xref:api/dms/get.adoc[get()]:

[tabs]
====
Sync::
+
[source,python]
----
doc = ecm.dms.insert_and_get(
    InvoiceDocument(Title="Rechnung Nr. 42"),
    files=[JobRequestFileFromPath("/tmp/rechnung.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="Rechnung Nr. 42"),
    files=[JobRequestFileFromPath("/tmp/rechnung.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)
----
====

=== Ablageort aus dem Ergebnis lesen (use_result_list)

`folder_id` und `register_id` im Ergebnis sind nur mit `use_result_list=True` verfügbar — siehe xref:api/dms/get.adoc#_abrufmodi[Abrufmodi in get()]:

[tabs]
====
Sync::
+
[source,python]
----
doc = ecm.dms.insert_and_get(
    InvoiceDocument(Title="Rechnung Nr. 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="Rechnung Nr. 42"),
    folder_id=folder.system.id,
    use_result_list=True,
)
print(doc.system.folder_id)
print(doc.system.register_id)
----
====
