move()

Moves a document or register to a new folder/register location using dms.XMLMove. Moving a register also moves all its contained child objects recursively.

When wf_to_user_tray=True, the document is moved from the workflow tray to the user tray. In that case no location parameters should be provided.

1. Signature

  • Sync

  • Async

ecm.dms.move(
    model: ECMDocumentModel | ECMRegisterModel | int | str,
    object_type: int | str | None = None,
    *,
    folder_id: int | str | ECMFolderModel | None = None,
    register_id: int | str | ECMRegisterModel | None = None,
    register_type: int | str | None = None,
    wf_to_user_tray: bool = False,
    options: ECMMoveOptions | None = None,
) -> None
await ecm.dms.move(
    model: ECMDocumentModel | ECMRegisterModel | int | str,
    object_type: int | str | None = None,
    *,
    folder_id: int | str | ECMFolderModel | None = None,
    register_id: int | str | ECMRegisterModel | None = None,
    register_type: int | str | None = None,
    wf_to_user_tray: bool = False,
    options: ECMMoveOptions | None = None,
) -> None

2. Parameters

Parameter Type Default Description

model

ECMDocumentModel | ECMRegisterModel | int | str

—

The object to move. Either a model instance (must have id set) or a plain integer object ID (requires object_type).

object_type

int | str | None

None

Only required when model is a plain int. Either a numeric type ID or the internal name of the object type.

folder_id

int | str | ECMFolderModel | None

None

Target folder — a numeric ID or an ECMFolderModel instance whose id is used. Required unless wf_to_user_tray=True.

register_id

int | str | ECMRegisterModel | None

None

Target register — a numeric ID or an ECMRegisterModel instance whose id is used. Pass -1 to place the object directly in the folder without a parent register.

register_type

int | str | None

None

Type ID of the target register. Optional, but passing it is faster: the server identifies the target register by the pair of ID and type, so a missing type is resolved automatically. That resolution costs one extra dms.GetObjectTypeByID round trip per call unless it can be read off a loaded ECMRegisterModel instance. See Pass the register type (faster).

wf_to_user_tray

bool

False

When True, moves the document from the workflow tray to the user tray. No location parameters should be set in this case.

3. Exceptions

Exception Condition

ValueError

model is a plain int and object_type is None.

ValueError

model is a model instance with id set to None.

4. Examples

4.1. Move a document to a different folder

  • Sync

  • Async

doc = ecm.dms.select(InvoiceDocument).where(InvoiceDocument.Title == "Draft").execute()[0]
target_folder = ecm.dms.select(InvoiceFolder).where(InvoiceFolder.Year == 2024).execute()[0]

ecm.dms.move(doc, folder_id=target_folder, register_id=-1)
doc = (await ecm.dms.select(InvoiceDocument).where(InvoiceDocument.Title == "Draft").execute())[0]
target_folder = (await ecm.dms.select(InvoiceFolder).where(InvoiceFolder.Year == 2024).execute())[0]

await ecm.dms.move(doc, folder_id=target_folder, register_id=-1)

4.2. Move using plain object ID and type name

  • Sync

  • Async

ecm.dms.move(
    42,
    "InvoiceDocument",
    folder_id=100,
    register_id=-1,
)
await ecm.dms.move(
    42,
    "InvoiceDocument",
    folder_id=100,
    register_id=-1,
)

4.3. Move a document into an existing register

  • Sync

  • Async

register = ecm.dms.select(ContractRegister).where(ContractRegister.Name == "Contracts").execute()[0]

ecm.dms.move(doc, folder_id=target_folder, register_id=register)
register = (await ecm.dms.select(ContractRegister).where(ContractRegister.Name == "Contracts").execute())[0]

await ecm.dms.move(doc, folder_id=target_folder, register_id=register)

4.4. Pass the register type (faster)

The server identifies the target register by the pair register_id + register_type. When register_type is missing the client resolves it: from the ECMRegisterModel instance if one was passed, otherwise with an extra dms.GetObjectTypeByID call. That round trip happens on every move(). When filing many objects into the same register, resolve the type once and pass it along, saving one server call per document.

register = ecm.dms.select(ContractRegister).where(ContractRegister.Name == "Contracts").execute()[0]
register_type = register.system.type_id  # or: ecm.dms.get_object_type_by_id(register_id)

for doc in documents:
    ecm.dms.move(
        doc.system.id,
        object_type=ContractDocument._internal_name_,
        folder_id=target_folder_id,
        register_id=register.system.id,
        register_type=register_type,
    )

4.5. Move from workflow tray to user tray

  • Sync

  • Async

ecm.dms.move(doc, wf_to_user_tray=True)
await ecm.dms.move(doc, wf_to_user_tray=True)

4.6. Job options: skip the target check inside a loop

The server checks on every move whether the target location exists. When the same target folder is used a hundred times in a loop, one check up front is enough:

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMMoveOptions

target = ecm.dms.get(InvoiceFolder, target_id)   # provably exists
fast = ECMMoveOptions().check_position(False)

for doc in documents:
    ecm.dms.move(doc, folder_id=target, register_id=-1, options=fast)
from ecmind_blue_client.ecm import ECMMoveOptions

target = await ecm.dms.get(InvoiceFolder, target_id)
fast = ECMMoveOptions().check_position(False)

for doc in documents:
    await ecm.dms.move(doc, folder_id=target, register_id=-1, options=fast)

The option object is immutable, so it can safely be built once and reused inside the loop.

Full option list in Job options.

5. See also

  • copy() — Copy an object to a new location

  • delete() — Delete an object