variants()

Reads the variant tree of a document (W-module) and returns only the parsed <DocumentVariants> section. Unlike get() with variants=True or select() with .variants(), no typed or generated model class is needed — an object ID is enough.

1. Signature

  • Sync

  • Async

ecm.dms.variants(
    document: int | ECMDocumentModel | ECMModelDocumentVariant,
    object_type_id: int | None = None,
) -> list[ECMModelDocumentVariant]
await ecm.dms.variants(
    document: int | ECMDocumentModel | ECMModelDocumentVariant,
    object_type_id: int | None = None,
) -> list[ECMModelDocumentVariant]

2. Parameters

Parameter Type Default Description

document

int | ECMDocumentModel | ECMModelDocumentVariant

—

The document: a numeric ID, a model instance (its id is used), or a node from a variant tree read earlier (its doc_id is used).

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(). Passing it avoids an extra server roundtrip.

3. Return value

list[ECMModelDocumentVariant] — the root variants with their nested children. The list is empty when the document has no variants, which is the case for every document without the W-module enabled.

Each node carries doc_id, doc_ver, is_active, doc_parent, children and level (see ECM Model). walk() flattens a node and all of its descendants depth first:

for root in ecm.dms.variants(12345):
    for variant in root.walk():
        print("  " * variant.level, variant.doc_ver, "active" if variant.is_active else "")

4. Exceptions

Exception Condition

ValueError

document is a model instance with id set to None.

ECMNotFoundException

The server returns no object for that ID. Depending on the permissions, the server reports a non-existent ID as ECMAccessDeniedException instead.

5. Examples

5.1. Read the variant tree by ID

  • Sync

  • Async

tree = ecm.dms.variants(12345)
print([variant.doc_ver for root in tree for variant in root.walk()])
tree = await ecm.dms.variants(12345)
print([variant.doc_ver for root in tree for variant in root.walk()])

5.2. Collect all variant IDs of a document

  • Sync

  • Async

doc = ecm.dms.get(InvoiceDocument, 12345)
ids = [variant.doc_id for root in ecm.dms.variants(doc) for variant in root.walk()]
doc = await ecm.dms.get(InvoiceDocument, 12345)
ids = [variant.doc_id for root in await ecm.dms.variants(doc) for variant in root.walk()]

6. See also