Reuse existing media library entries when a media source item has already been imported

content/guides/media-library/media-sources/index.md

@@ -58,7 +58,13 @@ module.exports = {
           // when the remote service supports image resizing, pass '{{width}}' as search parameter
           // the editor will replace {{width}} and the image can then requested in the right size
           previewUrl: `https://li-test.ch/${result.id}.png?w={{width}}`
-        }
+        },
+        // If systemName and externalId are returned for search results,
+        // Livingdocs stores them on the media library entry of inserted items.
+        // When the same item is imported again, Livingdocs reuses the existing
+        // media library entry instead of creating a duplicate.
+        systemName: 'exampleSource', // {{< added-in "release-2026-03" >}}
+        externalId: result.id // {{< added-in "release-2026-03" >}}
       }
     })
 

content/operations/releases/release-2026-03.md

@@ -138,10 +138,40 @@ No rollback steps are required for this release.
 
 ## Breaking Changes :fire:
 
+### Validation of Media Source Plugin Return Properties `systemName` and `externalId`
+
+The media source plugin function `searchMediaImage` now requires `systemName` and `externalId` to be strings when returned. Previously, these properties were not validated and had no effect.
+
 ## Deprecations
 
 ## Features :gift:
 
+### Reuse Already Imported Media Source Items :gift:
+
+When a media source item has already been imported, Livingdocs now reuses the existing media library entry instead of importing it again. This allows keeping media libraries free of duplicates when using media from external systems.
+
+To enable the deduplication, [media source]({{< ref "/guides/media-library/media-sources/" >}}) search results can include `systemName` and `externalId`. If a media library entry with the same `systemName`/`externalId` pair already exists, it is reused.
+
+```diff
+module.exports = {
+  handle: 'examplePlugin',
+  async searchMediaImage() {
+    return {
+      total: 123,
+      results: [
+        {
+          metadata: {},
+          asset: {},
++         systemName: 'exampleSource',
++         externalId: 'exampleExternalId'
+        }
+      ]
+    }
+  },
+  async fetchMediaImage() {}
+}
+```
+
 ## Vulnerability Patches
 
 We are constantly patching module vulnerabilities for the Livingdocs Server and Livingdocs Editor as module fixes are available. Below is a list of all patched vulnerabilities included in the release.