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. Geladenes Modell erneut anlegen

Ein vom Server geladenes Modell lässt sich direkt an insert() übergeben, etwa um ein Objekt zu kopieren. Gesendet werden alle geladenen Index- und Tabellenfelder. Der Owner geht nur als Benutzername hinaus: der Server liefert ihn als GUID, lehnt eine GUID aber mit Fehler -1019 ab. Eine GUID, ob geladen oder per to_dict() kopiert, bleibt deshalb außen vor, und das neue Objekt gehört dem aufrufenden Benutzer. Einen anderen Owner setzt system.assign_owner() (#15523). Felder, die eine Abfrage mit fields() nicht angefordert hat, bekommen die Initialwerte des Servers.

source = ecm.dms.get(InvoiceFolder, 12345)
source.system.assign_owner("MUELLER")   # optional, sonst gehört die Kopie dem Aufrufer
new_id, _ = ecm.dms.insert(source)

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

7. Beispiele

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

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

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

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

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

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

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