From 1cd2d41b62495f34fa3b41661cc141e0db227dc6 Mon Sep 17 00:00:00 2001
From: sven1103-agent <261423644+sven1103-agent@users.noreply.github.com>
Date: Thu, 30 Jul 2026 08:43:35 +0200
Subject: [PATCH] docs: add missing InvenioRDM application.properties entries
 to v1.14.0 migration

The released migration doc for v1.14.0 only covered the two SQL schema
migrations but omitted the new
configuration entries in application.properties. Without these, operators
upgrading will find the application fails to start.

This adds:
- A new 'Application properties changes' section before the schema summary
- A reference table of all four instance properties (id, display-name,
  base-url, api-version)
- The default config block with the two pre-configured instances (Zenodo,
  FDAT)
- Operator action items (review, add, restart)
- Updated post-migration checklist step 1
---
 docs/migrations/released/v1.14.0.md | 54 +++++++++++++++++++++++++++--
 1 file changed, 52 insertions(+), 2 deletions(-)

diff --git a/docs/migrations/released/v1.14.0.md b/docs/migrations/released/v1.14.0.md
index 3957d4c9a..aa22310f7 100644
--- a/docs/migrations/released/v1.14.0.md
+++ b/docs/migrations/released/v1.14.0.md
@@ -34,6 +34,55 @@ Before applying any migrations:
 
 ---
 
+## Application properties changes
+
+InvenioRDM external service integration requires new configuration entries in
+`application.properties`. Operators upgrading from v1.13.0 **must** add these
+properties — without them the application will fail to start (the
+`InvenioRdmInstance` list is mandatory).
+
+### New properties
+
+| Property | Type | Description |
+|---|---|---|
+| `qbic.external-service.invenio-rdm.instances[N].id` | String | Stable identifier for the InvenioRDM instance (e.g. `zenodo`, `fdat`). Used as a lookup key in the UI. |
+| `qbic.external-service.invenio-rdm.instances[N].display-name` | String | Human-readable name shown in the UI (e.g. `Zenodo`, `FDAT`). |
+| `qbic.external-service.invenio-rdm.instances[N].base-url` | URL | Base URL of the InvenioRDM instance API (e.g. `https://zenodo.org`). |
+| `qbic.external-service.invenio-rdm.instances[N].api-version` | Integer | Invenio REST API version for per-instance adapter dispatch (currently unused; defaults to version 12). |
+
+### Default configuration
+
+The default `application.properties` ships with two pre-configured instances:
+
+```properties
+# ── InvenioRDM instances ────────────────────────────────────────
+qbic.external-service.invenio-rdm.instances[0].id=zenodo
+qbic.external-service.invenio-rdm.instances[0].display-name=Zenodo
+qbic.external-service.invenio-rdm.instances[0].base-url=https://zenodo.org
+qbic.external-service.invenio-rdm.instances[0].api-version=12
+
+qbic.external-service.invenio-rdm.instances[1].id=fdat
+qbic.external-service.invenio-rdm.instances[1].display-name=FDAT
+qbic.external-service.invenio-rdm.instances[1].base-url=https://fdat.uni-tuebingen.de
+qbic.external-service.invenio-rdm.instances[1].api-version=12
+```
+
+> **Note:** The `instances` list uses zero-based indexed keys. To add a third instance, use
+> `instances[2].<property>`. Removing an instance means removing its entries from the
+> configuration — the application will stop offering the ability to connect datasets from
+> that instance.
+
+### Operator action
+
+1. **Review** the properties above and adjust them for your environment. In particular:
+   - Verify `base-url` values point to the correct InvenioRDM instances for your organisation.
+   - Add or remove instance entries (`instances[0]`, `instances[1]`, …) as needed.
+2. **Add** the properties to your `application.properties` (or equivalent externalised
+   configuration / environment variables).
+3. **Restart** the application after applying schema migrations.
+
+---
+
 ## Summary of schema changes in this release
 
 | # | Script | Description | Risk |
@@ -323,9 +372,10 @@ mysql -u <user> -h <host> -P <port> data_management < /tmp/complete-schema-1.13.
 
 ## Post-migration checklist
 
-After applying all migrations:
+After applying all migrations and configuration changes:
 
-1. **Restart the application.**
+1. **Verify application.properties contains all new InvenioRDM instance entries** (see *Application properties changes* above).
+2. **Restart the application.**
 2. **Verify the application starts without errors** — check logs for schema
    mismatch warnings.
 3. **Run a smoke test** against a project with no connected datasets to confirm