update()

Updates an existing object on the server using dms.XMLUpdate. The passed model instance is not mutated.

ECM Model reference — for a full description of system.is_modified, system.has_removed_table_rows, system.modified_fields, and how change tracking works.

If no fields have been changed and no files are provided, the server call is skipped by default. Pass force=True to send the request regardless.

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

1. Signature

  • Sync

  • Async

ecm.dms.update(
    model: T,
    files: list[JobRequestFile] | None = None,
    replace_files: bool = True,
    force: bool = False,
    *,
    check_mandatory: bool = True,
) -> None
await ecm.dms.update(
    model: T,
    files: list[JobRequestFile] | None = None,
    replace_files: bool = True,
    force: bool = False,
    *,
    check_mandatory: bool = True,
) -> None

2. Parameters

Name Type Description

model

ECMFolderModel | ECMRegisterModel | ECMDocumentModel

The model instance to update. Must have been loaded from the server so that model.system.id is set.

files

list[JobRequestFile] | None

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

replace_files

bool

When True (default) and files are provided, the new files replace the existing document files (REPLACEFILES=1). When False, files are appended to the existing ones. Only relevant for ECMDocumentModel when files is provided.

force

bool

When True, the server call is always executed even when no changes are detected. Default: False.

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

None

4. Automatic skip

The server call is silently skipped when all of the following conditions are true:

  • force=False (default)

  • model.system.is_modified is False — no fields have been changed

  • files is None

The model tracks field changes automatically when values are set. Removed table rows are also detected: when rows have been deleted, the option REPLACETABLEFIELDS=1 is added to the request automatically.

5. Exceptions

ValueError

model.system.id is None (object was not loaded from the server) or check_mandatory=True and a required field is not set.

TypeError

files was provided for a folder or register model.

6. Examples

6.1. Simple field update

  • Sync

  • Async

folder = ecm.dms.get(InvoiceFolder, 12345)
folder.Title = "Invoice 2024 (updated)"
ecm.dms.update(folder)
folder = await ecm.dms.get(InvoiceFolder, 12345)
folder.Title = "Invoice 2024 (updated)"
await ecm.dms.update(folder)

6.2. Replace document file

  • Sync

  • Async

from ecmind_blue_client.rpc import JobRequestFileFromPath

doc = ecm.dms.get(InvoiceDocument, 42)
doc.Title = "Invoice No. 42 (corrected)"
ecm.dms.update(
    doc,
    files=[JobRequestFileFromPath("/tmp/invoice_v2.pdf")],
    replace_files=True,  # replace existing files (default)
)
from ecmind_blue_client.rpc import JobRequestFileFromPath

doc = await ecm.dms.get(InvoiceDocument, 42)
doc.Title = "Invoice No. 42 (corrected)"
await ecm.dms.update(
    doc,
    files=[JobRequestFileFromPath("/tmp/invoice_v2.pdf")],
    replace_files=True,
)

6.3. Append file instead of replacing

  • Sync

  • Async

from ecmind_blue_client.rpc import JobRequestFileFromPath

doc = ecm.dms.get(InvoiceDocument, 42)
ecm.dms.update(
    doc,
    files=[JobRequestFileFromPath("/tmp/attachment.pdf")],
    replace_files=False,  # add file, keep existing ones
)
from ecmind_blue_client.rpc import JobRequestFileFromPath

doc = await ecm.dms.get(InvoiceDocument, 42)
await ecm.dms.update(
    doc,
    files=[JobRequestFileFromPath("/tmp/attachment.pdf")],
    replace_files=False,
)

6.4. Forcing an update

Useful when external logic requires resubmission even though no fields have changed:

  • Sync

  • Async

folder = ecm.dms.get(InvoiceFolder, 12345)
# no field changes — without force=True the call would be skipped
ecm.dms.update(folder, force=True)
folder = await ecm.dms.get(InvoiceFolder, 12345)
await ecm.dms.update(folder, force=True)

6.5. Disabling mandatory field validation

  • Sync

  • Async

folder = ecm.dms.get(InvoiceFolder, 12345)
folder.Title = None  # clear a mandatory field
# check_mandatory=False: no error, obligation check also disabled server-side
ecm.dms.update(folder, check_mandatory=False)
folder = await ecm.dms.get(InvoiceFolder, 12345)
folder.Title = None
await ecm.dms.update(folder, check_mandatory=False)

7. See also

  • update_and_get() — combines update() and get() in one call when the updated instance is needed

  • insert() — creates a new object

  • get() — loads a single object from the server