insert()

Legt ein neues Objekt auf dem Server an und gibt (object_id, object_type_id) zurück. Intern wird dms.XMLInsert verwendet. Die übergebene Modell-Instanz wird nicht verändert.

Wird die vollständige Instanz direkt nach dem Anlegen benötigt, ist insert_and_get() die kompaktere Alternative.

1. Signatur

  • Sync

  • Async

ecm.dms.insert(
    model: T,
    files: Sequence[JobRequestFile] | None = None,
    *,
    folder_id: int | str | ECMFolderModel | None = None,
    register_id: int | str | ECMRegisterModel | None = None,
    check_mandatory: bool = True,
    options: ECMInsertOptions | None = None,
) -> tuple[int, int]
await ecm.dms.insert(
    model: T,
    files: Sequence[JobRequestFile] | None = None,
    *,
    folder_id: int | str | ECMFolderModel | None = None,
    register_id: int | str | ECMRegisterModel | None = None,
    check_mandatory: bool = True,
    options: ECMInsertOptions | None = None,
) -> tuple[int, int]

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

Sequence[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 | str | ECMFolderModel | None

Ordner, in dem das Objekt abgelegt wird — entweder eine numerische ID oder eine ECMFolderModel-Instanz (deren id wird verwendet). Nur für Register und Dokumente gültig. Standard: None.

register_id

int | str | 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 ECMField-Felder einen Wert haben. Bei False wird die client- und serverseitige Pflichtfeldprüfung deaktiviert (CHECKOBLIGATION=0).

options

ECMInsertOptions | None

Zusätzliche dms.XMLInsert-Joboptionen, z. B. ECMInsertOptions().init_fields(False).check_key_fields(False). Hier gesetzte Optionen haben Vorrang vor denen, die aus den getypten Parametern oben abgeleitet werden. Siehe Joboptionen. Standard: None.

3. Rückgabewert

tuple[int, int] — (object_id, object_type_id) des neu erstellten Objekts.

4. Schreibbare Systemfelder

Systemfelder (SystemFields-Enum) werden standardmäßig aus der dms.XMLInsert-XML herausgefiltert; der enaio-Server lehnt fast alle mit ECMAccessDeniedException ab. Über die Allowlist WRITABLE_SYSTEM_FIELDS (in ecmind_blue_client.const) sind folgende Felder schreibbar:

  • OBJECT_FOREIGNID — String-Feld; Referenz ins externe Archivsystem oder enaio-Objekt-ID für „grüner Pfeil".

  • OBJECT_SYSTEMID — Int-Feld; auf Insert nur zulässig, wenn gleichzeitig OBJECT_FOREIGNID gesetzt ist (sonst Fehler -1013).

  • OBJECT_USERGUID — Owner; der Wert muss der Benutzername sein (z. B. "ROOT"), nicht die GUID-Hex. Der Server löst auf und speichert die GUID.

Details und Beispiele in update().

5. Ausnahmen

ECMException

Der Server hat den Insert abgelehnt (ObjectID == -1).

ECMMissingArgumentException

folder_id fehlt bei einem Register- oder Dokument-Modell. Subklasse von ECMException.

TypeError

files wurde für ein Ordner- oder Register-Modell übergeben.

ValueError

check_mandatory=True und ein Pflichtfeld ist nicht gesetzt, oder ein schreibgeschütztes Feld (ECMField(read_only=…)) wird geschrieben — siehe ECM-Modell.

6. Beispiele

6.1. Einfacher Ordner

  • Sync

  • Async

object_id, object_type_id = ecm.dms.insert(
    InvoiceFolder(Title="Rechnung 2024", Year=2024)
)
print(object_id)
object_id, object_type_id = await ecm.dms.insert(
    InvoiceFolder(Title="Rechnung 2024", Year=2024)
)
print(object_id)

6.2. Register in einem Ordner ablegen

  • Sync

  • Async

object_id, _ = ecm.dms.insert(
    InvoiceRegister(Name="Eingangsrechnungen"),
    folder_id=folder.system.id,
)
object_id, _ = await ecm.dms.insert(
    InvoiceRegister(Name="Eingangsrechnungen"),
    folder_id=folder.system.id,
)

6.3. Dokument mit Datei und Ablageort

  • Sync

  • Async

from ecmind_blue_client.rpc import JobRequestFileFromPath

object_id, _ = ecm.dms.insert(
    InvoiceDocument(Title="Rechnung Nr. 42"),
    files=[JobRequestFileFromPath("/tmp/rechnung.pdf")],
    folder_id=folder.system.id,
    register_id=register.system.id,
)
print(object_id)
from ecmind_blue_client.rpc import JobRequestFileFromPath

object_id, _ = await ecm.dms.insert(
    InvoiceDocument(Title="Rechnung Nr. 42"),
    files=[JobRequestFileFromPath("/tmp/rechnung.pdf")],
    folder_id=folder.system.id,
    register_id=register.system.id,
)
print(object_id)

6.4. Modell-Instanz als folder_id / register_id übergeben

Statt einer numerischen ID kann direkt eine Modell-Instanz übergeben werden — insert() entnimmt daraus automatisch die ID:

  • Sync

  • Async

folder = ecm.dms.insert_and_get(InvoiceFolder(Title="Rechnung 2024"))
register = ecm.dms.insert_and_get(
    InvoiceRegister(Name="Eingang"),
    folder_id=folder,          # ECMFolderModel-Instanz statt int
)
object_id, _ = ecm.dms.insert(
    InvoiceDocument(Title="Rechnung Nr. 42"),
    folder_id=folder,          # ECMFolderModel-Instanz
    register_id=register,      # ECMRegisterModel-Instanz
)
folder = await ecm.dms.insert_and_get(InvoiceFolder(Title="Rechnung 2024"))
register = await ecm.dms.insert_and_get(
    InvoiceRegister(Name="Eingang"),
    folder_id=folder,
)
object_id, _ = await ecm.dms.insert(
    InvoiceDocument(Title="Rechnung Nr. 42"),
    folder_id=folder,
    register_id=register,
)

6.5. Pflichtfeldprüfung deaktivieren

  • Sync

  • Async

# check_mandatory=False: kein Fehler, auch wenn Pflichtfelder fehlen
object_id, _ = ecm.dms.insert(
    InvoiceFolder(Title="Entwurf"),
    check_mandatory=False,
)
object_id, _ = await ecm.dms.insert(
    InvoiceFolder(Title="Entwurf"),
    check_mandatory=False,
)

6.6. Joboptionen: Objekttyp mit Key-Feldern

Hat der Objekttyp serverseitige Key-Felder, füllt der Server beim Insert die nicht gesetzten Felder mit Initialwerten und prüft die Key-Felder auf Eindeutigkeit. Bei einem Import, der die Werte bereits mitbringt, scheitert der Insert daran. Beide Prüfungen lassen sich für den einzelnen Aufruf abschalten:

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMInsertOptions

# Belegnummer ist ein Key-Feld des Typs und wird vom Import selbst geliefert
object_id, _ = ecm.dms.insert(
    InvoiceDocument(Title="Rechnung Nr. 42"),
    folder_id=folder.system.id,
    options=ECMInsertOptions().init_fields(False).check_key_fields(False),
)
from ecmind_blue_client.ecm import ECMInsertOptions

object_id, _ = await ecm.dms.insert(
    InvoiceDocument(Title="Rechnung Nr. 42"),
    folder_id=folder.system.id,
    options=ECMInsertOptions().init_fields(False).check_key_fields(False),
)

Optionen aus options haben Vorrang vor denen, die aus den getypten Parametern abgeleitet werden. check_mandatory=False zusammen mit check_obligation(True) überspringt also die clientseitige Pflichtfeldprüfung, lässt die serverseitige aber aktiv.

Vollständige Optionsliste in Joboptionen.

7. Siehe auch

  • insert_and_get() — kombiniert insert() und get() in einem Aufruf, wenn die vollständige Instanz benötigt wird

  • update() — aktualisiert ein bestehendes Objekt