insert_variant_and_get()

Combines insert_variant() and get() into a single call: creates a new variant and immediately returns the fully server-populated model instance. Raises ECMException if the server rejects the insert.

ECM Model reference — for a full description of all system properties available on the returned instance.

1. Signature

  • Sync

  • Async

ecm.dms.insert_variant_and_get(
    model: T,                                # bound to 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,
    rights: bool = False,
    base_params: bool = False,
    file_properties: bool = False,
    variants: bool = False,
    use_result_list: bool = False,
    fields: list[str | ECMField] | None = None,
) -> T
await ecm.dms.insert_variant_and_get(
    model: T,
    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,
    rights: bool = False,
    base_params: bool = False,
    file_properties: bool = False,
    variants: bool = False,
    use_result_list: bool = False,
    fields: list[str | ECMField] | None = None,
) -> T

2. Parameters

2.1. Variant parameters

See insert_variant() for model, parent_document_id, files, same_level, set_active, transfer_retention, and check_mandatory.

2.2. Get parameters

The following parameters are forwarded unchanged to get(). See the get() reference for full details.

Name Type Summary

rights

bool

Fetch access rights (obj.system.rights). Default: False.

base_params

bool

Fetch administrative metadata (obj.system.base_params). Default: False.

file_properties

bool

Fetch file metadata (obj.system.file_properties). Default: False.

variants

bool

Fetch W-module version branches (obj.system.variants). Default: False.

use_result_list

bool

Switch retrieval mode (enables folder_id/register_id in result). Default: False.

fields

list[str | ECMField] | None

Restrict returned fields. Only effective with use_result_list=True. Default: None.

3. Return value

A typed ECMDocumentModel instance populated with all server-side field values (ID, system fields, index fields).

4. Exceptions

ECMException

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

TypeError

model is not an ECMDocumentModel.

ValueError

parent_document_id has no id, or check_mandatory=True and a required field is missing.

5. Example

  • Sync

  • Async

parent = ecm.dms.get(InvoiceDocument, parent_id)

variant = ecm.dms.insert_variant_and_get(
    InvoiceDocument(Title="Revision 2"),
    parent,
    same_level=True,
    set_active=True,
)
print(variant.system.id, variant.Title)
parent = await ecm.dms.get(InvoiceDocument, parent_id)

variant = await ecm.dms.insert_variant_and_get(
    InvoiceDocument(Title="Revision 2"),
    parent,
    same_level=True,
    set_active=True,
)
print(variant.system.id, variant.Title)

6. See also