set_active_variant()

Aktiviert eine bestehende Variante eines Dokuments über std.SetActiveVariant. Anders als insert_variant() mit set_active=True wirkt die Methode auf einen bereits bestehenden Variantenbaum.

Der Serverjob benötigt zusätzlich die bisher aktive Variante (dwPrevActVarID), die der Aufrufer normalerweise nicht kennt. Sie wird auf dem jeweils günstigsten Weg ermittelt:

  1. aus previously_active_id, wenn angegeben — kein zusätzlicher Server-Roundtrip,

  2. aus dem Variantenbaum einer Modell-Instanz, die mit variants=True geladen wurde,

  3. sonst über einen variants()-Aufruf.

Ist die angegebene Variante bereits aktiv, passiert nichts und es wird kein Job ausgeführt.

1. Signatur

  • Sync

  • Async

ecm.dms.set_active_variant(
    variant: int | ECMDocumentModel | ECMModelDocumentVariant,
    object_type_id: int | None = None,
    *,
    previously_active_id: int | ECMDocumentModel | ECMModelDocumentVariant | None = None,
) -> None
await ecm.dms.set_active_variant(
    variant: int | ECMDocumentModel | ECMModelDocumentVariant,
    object_type_id: int | None = None,
    *,
    previously_active_id: int | ECMDocumentModel | ECMModelDocumentVariant | None = None,
) -> None

2. Parameter

Parameter Typ Standard Beschreibung

variant

int | ECMDocumentModel | ECMModelDocumentVariant

—

Die zu aktivierende Variante: numerische ID, Modell-Instanz oder ein Knoten aus system.variants bzw. variants().

object_type_id

int | None

None

Die numerische Objekttyp-ID. Wenn None, wird sie aus der Modell-Instanz übernommen oder über get_object_type_by_id() ermittelt. Alle Varianten eines Baums haben denselben Objekttyp.

previously_active_id

int | ECMDocumentModel | ECMModelDocumentVariant | None

None

Die bisher aktive Variante, in denselben drei Formen. Überspringt das Lesen des Variantenbaums und damit auch die Prüfungen unten.

3. Rückgabewert

None.

4. Ausnahmen

Ausnahme Bedingung

ValueError

Eine übergebene Modell-Instanz hat kein id, oder variant gehört nicht zum ermittelten Variantenbaum.

ECMWrongStateException

Das Dokument hat überhaupt keine Varianten (kein W-Dokument), oder im Baum ist keine Variante aktiv.

ECMNotFoundException

Der Server liefert kein Objekt zu dieser ID.

std.SetActiveVariant überschreibt zwei IDs ohne eigene Prüfung. Eine falsche oder fremde dwPrevActVarID hinterlässt deshalb einen Baum mit zwei aktiven Varianten oder ohne aktive Variante. Die Prüfungen oben fangen genau diese Fälle ab — mit previously_active_id übernimmt der Aufrufer die Verantwortung dafür selbst.

5. Beispiele

5.1. Ursprungsdokument wieder aktivieren

  • Sync

  • Async

doc = ecm.dms.get(InvoiceDocument, 12345)
ecm.dms.set_active_variant(doc)
doc = await ecm.dms.get(InvoiceDocument, 12345)
await ecm.dms.set_active_variant(doc)

5.2. Variante aus dem gelesenen Baum aktivieren

  • Sync

  • Async

doc = ecm.dms.get(InvoiceDocument, 12345, variants=True)
target = next(v for root in doc.system.variants for v in root.walk() if v.doc_ver == "2.0.0")
ecm.dms.set_active_variant(target, doc.system.type_id)
doc = await ecm.dms.get(InvoiceDocument, 12345, variants=True)
target = next(v for root in doc.system.variants for v in root.walk() if v.doc_ver == "2.0.0")
await ecm.dms.set_active_variant(target, doc.system.type_id)

5.3. Ohne zusätzliche Abfrage umschalten

Wenn die bisher aktive Variante bekannt ist — etwa aus einer vorhergehenden Abfrage — entfällt der Roundtrip über variants():

  • Sync

  • Async

active = ecm.dms.active_variant(12345)
new_id, _ = ecm.dms.insert_variant(InvoiceDocument(Name="Korrektur"), 12345)
ecm.dms.set_active_variant(new_id, 327685, previously_active_id=active)
active = await ecm.dms.active_variant(12345)
new_id, _ = await ecm.dms.insert_variant(InvoiceDocument(Name="Korrektur"), 12345)
await ecm.dms.set_active_variant(new_id, 327685, previously_active_id=active)

6. Siehe auch