= copy()
:description: Kopiert einen Ordner, ein Register oder ein Dokument an einen neuen Speicherort (dms.XMLCopy). Gibt die neue object_id zurück. Unterstützt optionale Umbenennung.
:keywords: copy, XMLCopy, kopieren, object_id, Ordner, Register, Dokument, Umbenennung
:page-tags: api, dms

Kopiert einen Ordner, ein Register oder ein Dokument an einen neuen Speicherort
über `dms.XMLCopy`.

Bei `copy_cascading=True` werden beim Kopieren eines Registers oder Ordners auch
alle enthaltenen Kindobjekte rekursiv kopiert. Bei `link_document=True` wird beim
Kopieren eines Dokuments ein zweiter Speicherort (Verknüpfung) für denselben
Indexdatensatz erstellt statt einer vollständig unabhängigen Kopie.

== Signatur

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

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

== Parameter

[cols="1,1,1,3"]
|===
|Parameter |Typ |Standard |Beschreibung

|`model`
|`ECMFolderModel \| ECMRegisterModel \| ECMDocumentModel \| int`
|—
|Das zu kopierende Objekt. Entweder eine Modellinstanz (muss `id` gesetzt haben) oder eine numerische Objekt-ID (erfordert `object_type`).

|`object_type`
|`int \| str \| None`
|`None`
|Nur erforderlich, wenn `model` ein einfacher `int` ist. Entweder eine numerische Typ-ID oder der interne Name des Objekttyps.

|`folder_id`
|`int \| ECMFolderModel \| None`
|`None`
|Zielordner — eine numerische ID oder eine `ECMFolderModel`-Instanz, deren `id` verwendet wird. Für alle Kopiervorgänge erforderlich.

|`register_id`
|`int \| ECMRegisterModel \| None`
|`None`
|Zielregister — eine numerische ID oder eine `ECMRegisterModel`-Instanz. `-1` übergeben, um die Kopie direkt im Ordner ohne übergeordnetes Register abzulegen.

|`register_type`
|`int \| None`
|`None`
|Typ-ID des Zielregisters. Wird automatisch ermittelt, wenn `register_id` eine `ECMRegisterModel`-Instanz ist, deren Klasse `_type_id_` definiert.

|`copy_cascading`
|`bool`
|`False`
|Bei `True` werden alle enthaltenen Kindobjekte ebenfalls rekursiv kopiert. Nur für Register und Ordner anwendbar.

|`link_document`
|`bool`
|`False`
|Bei `True` wird ein zweiter Speicherort (Verknüpfung) für denselben Indexdatensatz erstellt statt einer vollständigen Kopie. Nur für Dokumente anwendbar. Quell- und Zielort müssen verschieden sein.
|===

== Ausnahmen

[cols="1,3"]
|===
|Ausnahme |Bedingung

|`ValueError`
|`model` ist ein einfacher `int` und `object_type` ist `None`.

|`ValueError`
|`model` ist eine Modellinstanz mit `id` gleich `None`.
|===

== Beispiele

=== Dokument in einen anderen Ordner kopieren

[tabs]
====
Sync::
+
[source,python]
----
doc = ecm.dms.select(RechnungsDokument).where(RechnungsDokument.Titel == "Original").execute()[0]
ziel = ecm.dms.select(RechnungsOrdner).where(RechnungsOrdner.Jahr == 2025).execute()[0]

ecm.dms.copy(doc, folder_id=ziel, register_id=-1)
----

Async::
+
[source,python]
----
doc = (await ecm.dms.select(RechnungsDokument).where(RechnungsDokument.Titel == "Original").execute())[0]
ziel = (await ecm.dms.select(RechnungsOrdner).where(RechnungsOrdner.Jahr == 2025).execute())[0]

await ecm.dms.copy(doc, folder_id=ziel, register_id=-1)
----
====

=== Ordner mit allen Kindobjekten kopieren

[tabs]
====
Sync::
+
[source,python]
----
ordner = ecm.dms.select(RechnungsOrdner).where(RechnungsOrdner.Jahr == 2023).execute()[0]

# Kopiert den Ordner sowie alle enthaltenen Register und Dokumente
ecm.dms.copy(ordner, folder_id=archiv_id, register_id=-1, copy_cascading=True)
----

Async::
+
[source,python]
----
ordner = (await ecm.dms.select(RechnungsOrdner).where(RechnungsOrdner.Jahr == 2023).execute())[0]

await ecm.dms.copy(ordner, folder_id=archiv_id, register_id=-1, copy_cascading=True)
----
====

=== Verknüpfte Kopie erstellen (zweiter Speicherort)

[tabs]
====
Sync::
+
[source,python]
----
# Das Dokument erhält einen zweiten Speicherort — beide verweisen auf denselben Indexdatensatz
ecm.dms.copy(doc, folder_id=zweiter_ordner_id, register_id=-1, link_document=True)
----

Async::
+
[source,python]
----
await ecm.dms.copy(doc, folder_id=zweiter_ordner_id, register_id=-1, link_document=True)
----
====

== Siehe auch

* xref:api/dms/move.adoc[move()] — Objekt an einen neuen Speicherort verschieben
* xref:api/dms/delete.adoc[delete()] — Objekt löschen
