insert_and_get()

Combines insert() and get() into a single call: creates a new object 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_and_get(
    model: T,
    files: list[JobRequestFile] | None = None,
    *,
    folder_id: int | ECMFolderModel | None = None,
    register_id: int | ECMRegisterModel | 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_and_get(
    model: T,
    files: list[JobRequestFile] | None = None,
    *,
    folder_id: int | ECMFolderModel | None = None,
    register_id: int | ECMRegisterModel | 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. Insert 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. 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 fields are set. When False, both client-side and server-side obligation checks are disabled (CHECKOBLIGATION=0).

2.2. Get parameters

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

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, documents only). 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 model instance populated with all server-side field values (ID, system fields, index fields).

4. Exceptions

ECMException

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

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

folder = ecm.dms.insert_and_get(InvoiceFolder(Title="Invoice 2024", Year=2024))
print(folder.system.id, folder.Title)
folder = await ecm.dms.insert_and_get(InvoiceFolder(Title="Invoice 2024", Year=2024))
print(folder.system.id, folder.Title)

5.2. Register inside a folder

  • Sync

  • Async

register = ecm.dms.insert_and_get(
    InvoiceRegister(Name="Incoming invoices"),
    folder_id=folder.system.id,
)
print(register.system.id)
register = await ecm.dms.insert_and_get(
    InvoiceRegister(Name="Incoming invoices"),
    folder_id=folder.system.id,
)
print(register.system.id)

5.3. Document with file and filing location

  • Sync

  • Async

from ecmind_blue_client.rpc import JobRequestFileFromPath

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

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

5.4. With metadata from get()

The rights, base_params, and file_properties parameters behave identically to get():

  • Sync

  • Async

doc = ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    files=[JobRequestFileFromPath("/tmp/invoice.pdf")],
    folder_id=folder.system.id,
    rights=True,
    base_params=True,
    file_properties=True,
)
print(doc.system.rights.edit_metadata)
print(doc.system.base_params.creator)
print(doc.system.file_properties.extension)
doc = await ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    files=[JobRequestFileFromPath("/tmp/invoice.pdf")],
    folder_id=folder.system.id,
    rights=True,
    base_params=True,
    file_properties=True,
)
print(doc.system.rights.edit_metadata)
print(doc.system.base_params.creator)
print(doc.system.file_properties.extension)

5.5. Read filing location from result (use_result_list)

folder_id and register_id in the result are only available with use_result_list=True — see Retrieval modes in get():

  • Sync

  • Async

doc = ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    folder_id=folder.system.id,
    use_result_list=True,
)
print(doc.system.folder_id)
print(doc.system.register_id)
doc = await ecm.dms.insert_and_get(
    InvoiceDocument(Title="Invoice No. 42"),
    folder_id=folder.system.id,
    use_result_list=True,
)
print(doc.system.folder_id)
print(doc.system.register_id)