insert()

Creates a new object on the server and returns (object_id, object_type_id). Internally uses dms.XMLInsert. The passed model instance is not mutated.

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

1. Signature

  • Sync

  • Async

ecm.dms.insert(
    model: T,
    files: list[JobRequestFile] | None = None,
    *,
    folder_id: int | ECMFolderModel | None = None,
    register_id: int | ECMRegisterModel | None = None,
    check_mandatory: bool = True,
) -> tuple[int, int]
await ecm.dms.insert(
    model: T,
    files: list[JobRequestFile] | None = None,
    *,
    folder_id: int | ECMFolderModel | None = None,
    register_id: int | ECMRegisterModel | None = None,
    check_mandatory: bool = True,
) -> tuple[int, int]

2. Parameters

Name Type Description

model

ECMFolderModel | ECMRegisterModel | ECMDocumentModel

The model instance to create, with the desired field values set. The instance is not mutated.

files

list[JobRequestFile] | None

Optional list of files to attach to the new document. Only allowed for ECMDocumentModel — raises TypeError for folder or register models. Default: None.

folder_id

int | ECMFolderModel | None

Folder to place the object in — either a numeric ID or an ECMFolderModel instance (its id is used). Only valid for registers and documents. Default: None.

register_id

int | ECMRegisterModel | None

Register to file the document in (ECMDocumentModel) or parent register (ECMRegisterModel) — either a numeric ID or an ECMRegisterModel instance. Default: None.

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 object.

4. Exceptions

ECMException

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

ECMMissingArgumentException

folder_id is missing for a register or document model. Subclass of ECMException.

TypeError

files was provided for a folder or register model.

ValueError

check_mandatory=True and a required field is not set.

5. Examples

5.1. Simple folder

  • Sync

  • Async

object_id, object_type_id = ecm.dms.insert(
    InvoiceFolder(Title="Invoice 2024", Year=2024)
)
print(object_id)
object_id, object_type_id = await ecm.dms.insert(
    InvoiceFolder(Title="Invoice 2024", Year=2024)
)
print(object_id)

5.2. Register inside a folder

  • Sync

  • Async

object_id, _ = ecm.dms.insert(
    InvoiceRegister(Name="Incoming invoices"),
    folder_id=folder.system.id,
)
object_id, _ = await ecm.dms.insert(
    InvoiceRegister(Name="Incoming invoices"),
    folder_id=folder.system.id,
)

5.3. Document with file and filing location

  • Sync

  • Async

from ecmind_blue_client.rpc import JobRequestFileFromPath

object_id, _ = ecm.dms.insert(
    InvoiceDocument(Title="Invoice No. 42"),
    files=[JobRequestFileFromPath("/tmp/invoice.pdf")],
    folder_id=folder.system.id,
    register_id=register.system.id,
)
print(object_id)
from ecmind_blue_client.rpc import JobRequestFileFromPath

object_id, _ = await ecm.dms.insert(
    InvoiceDocument(Title="Invoice No. 42"),
    files=[JobRequestFileFromPath("/tmp/invoice.pdf")],
    folder_id=folder.system.id,
    register_id=register.system.id,
)
print(object_id)

5.4. Passing model instances as folder_id / register_id

Instead of a numeric ID, a model instance can be passed directly — insert() extracts the ID automatically:

  • Sync

  • Async

folder = ecm.dms.insert_and_get(InvoiceFolder(Title="Invoice 2024"))
register = ecm.dms.insert_and_get(
    InvoiceRegister(Name="Incoming"),
    folder_id=folder,          # ECMFolderModel instance instead of int
)
object_id, _ = ecm.dms.insert(
    InvoiceDocument(Title="Invoice No. 42"),
    folder_id=folder,          # ECMFolderModel instance
    register_id=register,      # ECMRegisterModel instance
)
folder = await ecm.dms.insert_and_get(InvoiceFolder(Title="Invoice 2024"))
register = await ecm.dms.insert_and_get(
    InvoiceRegister(Name="Incoming"),
    folder_id=folder,
)
object_id, _ = await ecm.dms.insert(
    InvoiceDocument(Title="Invoice No. 42"),
    folder_id=folder,
    register_id=register,
)

5.5. Disabling mandatory field validation

  • Sync

  • Async

# check_mandatory=False: no error even if required fields are missing
object_id, _ = ecm.dms.insert(
    InvoiceFolder(Title="Draft"),
    check_mandatory=False,
)
object_id, _ = await ecm.dms.insert(
    InvoiceFolder(Title="Draft"),
    check_mandatory=False,
)

6. See also

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

  • update() — updates an existing object