Add docs for merging items

modules/restapi/src/main/resources/docspell-openapi.yml

@@ -2340,11 +2340,20 @@ paths:
       summary: Merge multiple items into one.
       description: |
         A list of items is merged into one item by copying all
-        metadata into the first item in the list. Metadata is only
-        written, if there is no value present. So the order of items
-        in the list matters - the first item with a correspondent or
-        folder will win. For metadata that allow multiple values, like
-        tags or custom fields the values are combined.
+        metadata into the first item in the list.
+
+        Metadata is copied into the target item, if there is no value
+        present. So the order of items in the list matters - the first
+        item with a correspondent or folder will win.
+
+        For metadata that allow multiple values, like tags or custom
+        fields the values are combined. Notes are concatenated from
+        all items and custom fields with the same name are added
+        together for money/numeric fields, concatenated for text
+        fields or the first value is used for other field types.
+
+        After a successful merge, the remaining items are deleted from
+        the database (they cannot be restored).
       security:
         - authTokenHeader: []
       requestBody:

website/site/content/docs/features/_index.md

@@ -45,6 +45,7 @@ description = "A list of features and limitations."
 - [Read your mailboxes](@/docs/webapp/scanmailbox.md) via IMAP to
   import mails into docspell
 - [Edit multiple items](@/docs/webapp/multiedit.md) at once
+- [Merge](@/docs/webapp/merge.md) multiple items
 - REST server and document processing are separate applications which
   can be scaled-out independently
 - Everything stored in a SQL database: PostgreSQL, MariaDB or H2

website/site/content/docs/webapp/merge.md

@@ -0,0 +1,70 @@
++++
+title = "Merge Items"
+weight = 100
+[extra]
+mktoc = true
++++
+
+Merging multiple items into one lets you transfer metadata and
+attachments from multiple items into a single one. The items that have
+been merged are removed afterwards.
+
+# Usage
+## Select items to merge
+
+Multiple items can be merged where all metadata is copied into the
+target item. This can be done by selecting multiple items to merge via
+the multi selection tool as described
+[here](@/docs/webapp/multiedit.md#toggle-selection-mode).
+
+Then select some items (at least 2) and click the merge tool button.
+
+{{ figure(file="merge-01.png") }}
+
+
+## Edit order of items
+
+This opens the merge view, where you can change the order of the
+selected items.
+
+{{ figure(file="merge-02.png") }}
+
+The order of this list can matter when merging (see below). You can
+move items via drag and drop:
+
+{{ figure(file="merge-03.png") }}
+
+
+## Click merge
+
+Once you clicke the *Merge* button, the items are merged and you will
+be taken to the search view.
+
+{{ figure(file="merge-04.png") }}
+
+As you can see, tags are all combined. Custom fields of same name are
+also merged, where possible. For text fields, the values are
+concatenated with a comma as separator. Money and numeric fields are
+simply added together. Also it shows that there are now two
+attachments in the item.
+
+
+# How it works
+
+Since the metadata of all items are merged into one, the order matters
+for fields that allow only one value (for example correspondents,
+concerning person/equipment, folder and dates). For these fields, the
+value of the first item in the list is used. The exception is the item
+notes: they are all concatenated with some newlines in between.
+
+All properties that allow multiple values (like tags and the
+attachments, of course) are simply moved to the target item. Custom
+fields are merged depending on their type. Fields of type money and
+numeric are added together such that the final item contains the sum
+of all values. Text fields are concatenated using a comma as
+separator. Other fields (boolean and date) are again chosen from the
+first item that has a value.
+
+After merging, the other items are removed from the database (they
+cannot be restored). This reason is that many data is moved into the
+target item and so the remaining items are actually empty.