= move()
:description: Moves a document or register to a new location (dms.XMLMove). Returns the updated object_id. Folders cannot be moved; use copy/delete for folder relocation.
:keywords: move, XMLMove, object_id, document, register
:page-tags: api, dms

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.

== Signature

[tabs]
====
Sync::
+
[source,python]
----
ecm.dms.move(
    model: ECMDocumentModel | ECMRegisterModel | int,
    object_type: int | str | None = None,
    *,
    folder_id: int | ECMFolderModel | None = None,
    register_id: int | ECMRegisterModel | None = None,
    register_type: int | None = None,
    wf_to_user_tray: bool = False,
) -> None
----

Async::
+
[source,python]
----
await ecm.dms.move(
    model: ECMDocumentModel | ECMRegisterModel | int,
    object_type: int | str | None = None,
    *,
    folder_id: int | ECMFolderModel | None = None,
    register_id: int | ECMRegisterModel | None = None,
    register_type: int | None = None,
    wf_to_user_tray: bool = False,
) -> None
----
====

== Parameters

[cols="1,1,1,3"]
|===
|Parameter |Type |Default |Description

|`model`
|`ECMDocumentModel \| ECMRegisterModel \| int`
|—
|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 \| 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 \| 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 \| None`
|`None`
|Type ID of the target register. Inferred automatically when `register_id` is an `ECMRegisterModel` instance whose class defines `_type_id_`.

|`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.
|===

== Exceptions

[cols="1,3"]
|===
|Exception |Condition

|`ValueError`
|`model` is a plain `int` and `object_type` is `None`.

|`ValueError`
|`model` is a model instance with `id` set to `None`.
|===

== Examples

=== Move a document to a different folder

[tabs]
====
Sync::
+
[source,python]
----
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)
----

Async::
+
[source,python]
----
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)
----
====

=== Move using plain object ID and type name

[tabs]
====
Sync::
+
[source,python]
----
ecm.dms.move(
    42,
    "InvoiceDocument",
    folder_id=100,
    register_id=-1,
)
----

Async::
+
[source,python]
----
await ecm.dms.move(
    42,
    "InvoiceDocument",
    folder_id=100,
    register_id=-1,
)
----
====

=== Move from workflow tray to user tray

[tabs]
====
Sync::
+
[source,python]
----
ecm.dms.move(doc, wf_to_user_tray=True)
----

Async::
+
[source,python]
----
await ecm.dms.move(doc, wf_to_user_tray=True)
----
====

== See also

* xref:api/dms/copy.adoc[copy()] — Copy an object to a new location
* xref:api/dms/delete.adoc[delete()] — Delete an object
