From d9bed2384dd8b74271275c0d9dc8bde1e5794111 Mon Sep 17 00:00:00 2001
From: David Dreschner <david.dreschner@nextcloud.com>
Date: Mon, 18 May 2026 14:20:57 +0200
Subject: [PATCH] feat(Groupware): Add note about user migration capabilities

Signed-off-by: David Dreschner <david.dreschner@nextcloud.com>
---
 admin_manual/groupware/mail.rst          | 27 ++++++++++++++++++++++++
 user_manual/groupware/index.rst          |  1 +
 user_manual/groupware/user_migration.rst | 22 +++++++++++++++++++
 3 files changed, 50 insertions(+)
 create mode 100644 user_manual/groupware/user_migration.rst

diff --git a/admin_manual/groupware/mail.rst b/admin_manual/groupware/mail.rst
index 73cbbaf8868..c58ceec1569 100644
--- a/admin_manual/groupware/mail.rst
+++ b/admin_manual/groupware/mail.rst
@@ -252,3 +252,30 @@ Translation
 .. versionadded:: 4.2
 
 The mail app can optionally provide translations for messages if the :ref:`translation API <machine_translation>` is enabled.
+
+User migration
+--------------
+
+.. versionadded:: 5.9
+
+.. important::
+   The `User Migration App <https://apps.nextcloud.com/apps/user_migration>`_ must be installed and enabled on both
+   instances.
+
+To migrate user data from one Nextcloud instance to another, use the User Migration App via the
+``occ user:export`` or ``occ user:import`` command line tool.
+
+The Mail app can migrate the following data:
+
+- Manually added mail accounts and their respective account settings (e.g., display name, signature, quick actions, ...)
+- Configured internal addresses
+- Configured trusted senders
+- S/MIME certificates and private keys
+- General app settings like the order of mail accounts
+
+.. note:: Provisioned mail accounts are not migrated, as they are expected to be re-provisioned on the new instance.
+
+.. note:: The User Migration App is **not** a backup solution, as existing data is not being removed before the import process.
+
+See the `User Migration App <https://apps.nextcloud.com/apps/user_migration>`_ on the Nextcloud App Store for more
+information.
diff --git a/user_manual/groupware/index.rst b/user_manual/groupware/index.rst
index e923e66ef13..abfea4355be 100644
--- a/user_manual/groupware/index.rst
+++ b/user_manual/groupware/index.rst
@@ -25,3 +25,4 @@ You can find out more about Nextcloud Groupware `on our website <https://nextclo
    sync_kde
    sync_gnome
    sync_windows10
+   user_migration
diff --git a/user_manual/groupware/user_migration.rst b/user_manual/groupware/user_migration.rst
new file mode 100644
index 00000000000..d7e5bd25a59
--- /dev/null
+++ b/user_manual/groupware/user_migration.rst
@@ -0,0 +1,22 @@
+==============================
+Migrate data between instances
+==============================
+
+The `User Migration App <https://apps.nextcloud.com/apps/user_migration>`_ lets you move your Nextcloud Groupware
+data between instances.
+
+The following data can be migrated:
+
+- Contacts and groups
+- Calendars including events, details and attendees
+- Calendar app settings including appointment and proposal schedule configurations
+- Mail account parameters, aliases and preferences
+
+.. important::
+   The User Migration App must be installed on both instances, along with the latest version of the respective
+   Nextcloud Groupware app.
+
+Once the User Migration App is installed, you can start the migration process by going to your **Personal settings**
+and clicking on **Data migration** on the left side. You can choose which data you want to migrate and start the
+export process. Once the export is finished, download the generated file and import it onto the new instance by going
+to the same section.