active_variant()

Returns the variant flagged is_active from a document’s variant tree. Searches the whole tree including nested levels and, like variants(), needs no model class.

When the document is loaded in typed form anyway, doc.system.active_variant is the better path: ecm.dms.get(Model, id, variants=True) or ecm.dms.select(Model).variants() bring the tree along and the property derives from it without another server call. This method is meant for documents you only have an ID for — in a loop over many documents it costs one job per document. See ECM Model.

1. Signature

  • Sync

  • Async

ecm.dms.active_variant(
    document: int | ECMDocumentModel | ECMModelDocumentVariant,
    object_type_id: int | None = None,
) -> ECMModelDocumentVariant | None
await ecm.dms.active_variant(
    document: int | ECMDocumentModel | ECMModelDocumentVariant,
    object_type_id: int | None = None,
) -> ECMModelDocumentVariant | None

2. Parameters

Parameter Type Default Description

document

int | ECMDocumentModel | ECMModelDocumentVariant

—

The document: a numeric ID, a model instance, or a node from a variant tree read earlier.

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

3. Return value

ECMModelDocumentVariant | None — the active variant, or None when the document has no variants.

4. Exceptions

Exception Condition

ValueError

document is a model instance with id set to None.

ECMNotFoundException

The server returns no object for that ID.

5. Examples

5.1. Determine the active variant of a document

  • Sync

  • Async

active = ecm.dms.active_variant(12345)
if active is not None:
    print(active.doc_id, active.doc_ver, active.level)
active = await ecm.dms.active_variant(12345)
if active is not None:
    print(active.doc_id, active.doc_ver, active.level)

5.2. Download the files of the active variant

  • Sync

  • Async

active = ecm.dms.active_variant(doc)
if active is not None:
    files = ecm.dms.files(active.doc_id)
active = await ecm.dms.active_variant(doc)
if active is not None:
    files = await ecm.dms.files(active.doc_id)

6. See also