insert_variant()

Legt eine neue Variante eines bestehenden Dokuments an und gibt (object_id, object_type_id) zurück. Intern wird dms.XMLInsert mit gesetztem variantparent_id-Attribut auf dem <Object>-Element verwendet. Die übergebene Modell-Instanz wird nicht verändert.

Die neue Variante erbt ihren Ablageort vom übergeordneten Dokument, daher werden folder_id / register_id nicht akzeptiert.

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

1. Signatur

  • Sync

  • Async

ecm.dms.insert_variant(
    model: ECMDocumentModel,
    parent_document_id: int | ECMDocumentModel,
    files: list[JobRequestFile] | None = None,
    *,
    same_level: bool | None = None,
    set_active: bool | None = None,
    transfer_retention: bool | None = None,
    check_mandatory: bool = True,
) -> tuple[int, int]
await ecm.dms.insert_variant(
    model: ECMDocumentModel,
    parent_document_id: int | ECMDocumentModel,
    files: list[JobRequestFile] | None = None,
    *,
    same_level: bool | None = None,
    set_active: bool | None = None,
    transfer_retention: bool | None = None,
    check_mandatory: bool = True,
) -> tuple[int, int]

2. Parameter

Name Typ Beschreibung

model

ECMDocumentModel

Modell-Instanz mit den Indexdaten der neuen Variante. Muss ein Dokument-Modell sein — Ordner- oder Register-Modelle lösen TypeError aus.

parent_document_id

int | ECMDocumentModel

Übergeordnetes Dokument — entweder als numerische ID oder als ECMDocumentModel-Instanz (deren id wird verwendet).

files

list[JobRequestFile] | None

Optionale Dateiliste für die neue Variante. Standard: None.

same_level

bool | None

True erzeugt eine Geschwistervariante auf derselben Ebene wie das Elternteil (VARIANTSAMELEVEL=1). False erzeugt eine Untervariante eine Ebene unterhalb (VARIANTSAMELEVEL=0). None (Standard) lässt die Option weg; der Server-Standard greift.

set_active

bool | None

True aktiviert die neue Variante (VARIANTSETACTIVE=1). False lässt die aktuell aktive Variante unverändert. None (Standard) lässt die Option weg.

transfer_retention

bool | None

True übernimmt die geplante Aufbewahrungsdauer des Elternteils (VARIANTTRANSFERRETENTION=1). None (Standard) lässt die Option weg.

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

3. Rückgabewert

tuple[int, int] — (object_id, object_type_id) der neu erstellten Variante.

4. Ausnahmen

ECMException

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

TypeError

model ist keine ECMDocumentModel-Instanz.

ValueError

parent_document_id ist eine ECMDocumentModel-Instanz ohne id, oder check_mandatory=True und ein Pflichtfeld ist nicht gesetzt.

5. Beispiele

5.1. Untervariante mit Standardwerten

  • Sync

  • Async

parent = ecm.dms.get(InvoiceDocument, parent_id)

variant = InvoiceDocument(Title="Revision 2")
variant_id, _ = ecm.dms.insert_variant(variant, parent)
print(variant_id)
parent = await ecm.dms.get(InvoiceDocument, parent_id)

variant = InvoiceDocument(Title="Revision 2")
variant_id, _ = await ecm.dms.insert_variant(variant, parent)
print(variant_id)

5.2. Geschwistervariante, aktiviert, mit Datei

  • Sync

  • Async

from ecmind_blue_client.rpc import JobRequestFileFromPath

variant_id, _ = ecm.dms.insert_variant(
    InvoiceDocument(Title="Revision 2"),
    parent,
    files=[JobRequestFileFromPath("/tmp/rev2.pdf")],
    same_level=True,
    set_active=True,
)
from ecmind_blue_client.rpc import JobRequestFileFromPath

variant_id, _ = await ecm.dms.insert_variant(
    InvoiceDocument(Title="Revision 2"),
    parent,
    files=[JobRequestFileFromPath("/tmp/rev2.pdf")],
    same_level=True,
    set_active=True,
)

5.3. Parent als numerische ID

  • Sync

  • Async

variant_id, _ = ecm.dms.insert_variant(
    InvoiceDocument(Title="Revision 2"),
    parent_document_id=42,
)
variant_id, _ = await ecm.dms.insert_variant(
    InvoiceDocument(Title="Revision 2"),
    parent_document_id=42,
)

6. Siehe auch

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

  • insert() — legt ein Nicht-Varianten-Objekt an