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 | str | ECMDocumentModel,
    files: Sequence[JobRequestFile] | None = None,
    *,
    same_level: bool | None = None,
    set_active: bool | None = None,
    transfer_retention: bool | None = None,
    check_mandatory: bool = True,
    options: ECMInsertOptions | None = None,
) -> tuple[int, int]
await ecm.dms.insert_variant(
    model: ECMDocumentModel,
    parent_document_id: int | str | ECMDocumentModel,
    files: Sequence[JobRequestFile] | None = None,
    *,
    same_level: bool | None = None,
    set_active: bool | None = None,
    transfer_retention: bool | None = None,
    check_mandatory: bool = True,
    options: ECMInsertOptions | None = None,
) -> 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 | str | ECMDocumentModel

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

files

Sequence[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).

options

ECMInsertOptions | None

Additional dms.XMLInsert job options, e.g. ECMInsertOptions().init_fields(False). Options set here take precedence over the ones derived from the typed parameters above. See Job options. Default: None.

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,
)

5.4. Job options: variant without initial values

By default the server fills the new variant’s unset fields with the object type’s initial values. To have the variant carry only the supplied values, turn INITFIELDS off:

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMInsertOptions

variant_id, _ = ecm.dms.insert_variant(
    InvoiceDocument(Title="Invoice no. 42 (corrected)"),
    parent_document_id=doc,
    same_level=True,
    options=ECMInsertOptions().init_fields(False),
)
from ecmind_blue_client.ecm import ECMInsertOptions

variant_id, _ = await ecm.dms.insert_variant(
    InvoiceDocument(Title="Invoice no. 42 (corrected)"),
    parent_document_id=doc,
    same_level=True,
    options=ECMInsertOptions().init_fields(False),
)

same_level, set_active and transfer_retention already cover the variant options as dedicated parameters; options is there for the remaining dms.XMLInsert options.

Full option list in Job options.

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