set_active_variant()

Activates an existing variant of a document via std.SetActiveVariant. Unlike insert_variant() with set_active=True, this method operates on a variant tree that already exists.

The server job also needs the currently active variant (dwPrevActVarID), which the caller usually does not know. It is resolved in the cheapest available way:

  1. from previously_active_id when given — no extra server roundtrip,

  2. from the variant tree of a model instance that was loaded with variants=True,

  3. otherwise with one variants() call.

Activating the variant that is already active does nothing and performs no job.

1. Signature

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

Parameter Type Default Description

variant

int | ECMDocumentModel | ECMModelDocumentVariant

—

The variant to activate: a numeric ID, a model instance, or a node from system.variants or variants().

object_type_id

int | None

None

The numeric object type ID. If None, it is taken from the model instance or resolved via get_object_type_by_id(). All variants of a tree share one object type.

previously_active_id

int | ECMDocumentModel | ECMModelDocumentVariant | None

None

The currently active variant, in the same three shapes. Skips reading the variant tree, and with it the checks below.

3. Return value

None.

4. Exceptions

Exception Condition

ValueError

A passed model instance has no id, or variant is not part of the resolved variant tree.

ECMWrongStateException

The document has no variants at all (not a W-document), or no variant in the tree is active.

ECMNotFoundException

The server returns no object for that ID.

std.SetActiveVariant overwrites two IDs without validating them. A wrong or unrelated dwPrevActVarID therefore leaves the tree with two active variants or with none. The checks above cover exactly those cases — with previously_active_id the caller takes that responsibility instead.

5. Examples

5.1. Re-activate the original document

  • 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. Activate a variant from the loaded tree

  • 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. Switch without an extra lookup

When the previously active variant is known — from an earlier query, for instance — the variants() roundtrip is not needed:

  • Sync

  • Async

active = ecm.dms.active_variant(12345)
new_id, _ = ecm.dms.insert_variant(InvoiceDocument(Name="Correction"), 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="Correction"), 12345)
await ecm.dms.set_active_variant(new_id, 327685, previously_active_id=active)

6. See also