insert_and_get()

Kombiniert insert() und 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.

ECM-Modell-Referenz — vollständige Beschreibung aller system-Eigenschaften der zurückgegebenen Instanz.

1. Signatur

  • Sync

  • Async

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

2. Parameter

2.1. Insert-Parameter

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

2.2. Get-Parameter

Die folgenden Parameter werden unverändert an get() weitergeleitet. Detailbeschreibung und Verhalten siehe dort.

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.

3. Rückgabewert

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

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

5. Beispiele

5.1. Einfacher Ordner

  • Sync

  • Async

folder = ecm.dms.insert_and_get(InvoiceFolder(Title="Rechnung 2024", Year=2024))
print(folder.system.id, folder.Title)
folder = await ecm.dms.insert_and_get(InvoiceFolder(Title="Rechnung 2024", Year=2024))
print(folder.system.id, folder.Title)

5.2. Register in einem Ordner ablegen

  • Sync

  • Async

register = ecm.dms.insert_and_get(
    InvoiceRegister(Name="Eingangsrechnungen"),
    folder_id=folder.system.id,
)
print(register.system.id)
register = await ecm.dms.insert_and_get(
    InvoiceRegister(Name="Eingangsrechnungen"),
    folder_id=folder.system.id,
)
print(register.system.id)

5.3. Dokument mit Datei und Ablageort

  • Sync

  • Async

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

5.4. Mit Metadaten aus get()

Die rights-, base_params- und file_properties-Parameter verhalten sich identisch zu get():

  • Sync

  • Async

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

5.5. 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 Abrufmodi in get():

  • Sync

  • Async

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