From b4ee78f97a772efc48ad444988c35be33c2056e8 Mon Sep 17 00:00:00 2001 From: Jeramy Soucy Date: Thu, 14 Nov 2024 09:26:58 +0100 Subject: [PATCH] Update legacy url aliases developer documentation (#199969) Closes #176164 ## Summary Updates the legacy URL aliases developer documentation to cover the two applicable scenarios where legacy URL aliases would be generated. Formerly, the document was only concerned with saved object namespace type migrations, but aliases can now also be generated when copying or importing saved objects. --- .../advanced/legacy-url-aliases.asciidoc | 28 +++++++++++++++++-- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/developer/advanced/legacy-url-aliases.asciidoc b/docs/developer/advanced/legacy-url-aliases.asciidoc index 3e441dd582123..a92902d674a15 100644 --- a/docs/developer/advanced/legacy-url-aliases.asciidoc +++ b/docs/developer/advanced/legacy-url-aliases.asciidoc @@ -13,11 +13,20 @@ type are *globally unique across all spaces*. {kib} creates a special entity called a **legacy URL alias** for each saved object that requires a new ID. This legacy URL alias allows {kib} to preserve any deep link URLs that exist for these objects. -[[legacy-url-aliases-example]] -=== Example +There are two cases where a legacy URL alias will get generated. + +1. During migration, when an object's namespace type is being converted from the single-namespace type to a multi-namespace type. If +the object resides in a non-default space, it gets a new ID and a legacy URL alias is generated. -Consider the following scenario: +2. During copy/import of saved objects, when any object requires a new ID **and the compatibilityMode option is enabled** (see the +<> API and https://github.com/elastic/kibana/pull/149021[PR #149021] +for more information). + +[[legacy-url-aliases-example]] +=== Examples +Consider the following scenarios: +==== Migration scenario You have {kib} 7.16, and you create a new dashboard.The ID of this dashboard is "123". You create a new space called "Bill's space" and <> your dashboard to the other space. Now you have two different dashboards that can be accessed at the following URLs: @@ -33,6 +42,19 @@ If you use your bookmark to access that dashboard using its old URL, {kib} detec ID. If you navigate to `http://localhost:5601/s/bills-space/app/dashboards#/view/123`, you'll see a message indicating that the dashboard has a new URL, and you're automatically redirected to `http://localhost:5601/s/bills-space/app/dashboards#/view/456`. +==== Copy scenario (weak links) +You have a data view and two dashboards in the default space, but you would also like to have them in another space. One of the dashboards +includes a Markdown visualization with a link to the other dashboard - a so-called **weak link**. This is a weak link because the ID of the +referenced object is not added to the object's references array, and therefore there is no explicit relationship between the objects. + +If you were to use the <> API to create new copies of these assets in another +space **without the `compatibilityMode` option set to true**, the Markdown link would be broken. The copied objects created in the target +space receive a new ID, and the weak link in the Markdown visualization would point to the ID of the source object from the originating space. + +By setting `compatibilityMode` to true when using the copy API, legacy aliases will be generated for any objects that require a new ID. This +allows the weak link to the second dashboard to be resolved. Though a dashboard with the ID from the weak link will not be found, a legacy +alias with this source ID will have been generated, and it will contain a target ID of the new local copy of the dashboard. + [[legacy-url-aliases-handling-errors]] === Handling errors