insert_variant()

Creates a new variant of an existing document and returns (object_id, object_type_id). Internally uses dms.XMLInsert with the variantparent_id attribute set on the <Object> element. The passed model instance is not mutated.

The new variant inherits its filing location from the parent document, so folder_id / register_id are not accepted.

If the fully populated instance is needed directly after creation, insert_variant_and_get() is the more compact alternative.

1. Signature

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

Name Type Description

model

ECMDocumentModel

The model instance describing the new variant’s index data. Must be a document model — folders and registers raise TypeError.

parent_document_id

int | ECMDocumentModel

Parent document — either a numeric ID or an ECMDocumentModel instance whose id is used.

files

list[JobRequestFile] | None

Optional list of files to attach to the new variant. Default: None.

same_level

bool | None

True creates a sibling variant at the same level as the parent (VARIANTSAMELEVEL=1). False creates a sub-variant one level below (VARIANTSAMELEVEL=0). None (default) omits the option so the server default applies.

set_active

bool | None

True activates the new variant (VARIANTSETACTIVE=1). False leaves the currently active variant unchanged. None (default) omits the option.

transfer_retention

bool | None

True transfers the planned retention from the parent (VARIANTTRANSFERRETENTION=1). None (default) omits the option.

check_mandatory

bool

When True (default), validates client-side that all mandatory=True ECMField descriptors have a value. When False, both client-side and server-side obligation checks are disabled (CHECKOBLIGATION=0).

3. Return value

tuple[int, int] — (object_id, object_type_id) of the newly created variant.

4. Exceptions

ECMException

The server rejected the insert (ObjectID == -1).

TypeError

model is not an ECMDocumentModel.

ValueError

parent_document_id is an ECMDocumentModel with no id set, or check_mandatory=True and a required field is not set.

5. Examples

5.1. Sub-variant with defaults

  • 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. Sibling variant, activated, with a file

  • 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 as plain integer 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. See also

  • insert_variant_and_get() — combines insert_variant() and get() in one call when the full instance is needed immediately

  • insert() — creates a non-variant object