[[legacy-url-aliases]]
== Legacy URL Aliases

This page describes legacy URL aliases: what they are, where they come from, and how to disable them.

[[legacy-url-aliases-overview]]
=== Overview

Many saved object types were converted in {kib} 8.0, so they can eventually be shared across <<xpack-spaces,spaces>>. Before 8.0, you could
have two objects with the same type and same ID in two different spaces. Part of this conversion is to make sure all object IDs of a given
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

Consider the following 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
<<managing-saved-objects-copy-to-space,copy>> your dashboard to the other space. Now you have two different dashboards that can be accessed
at the following URLs:

* *Default space*: `http://localhost:5601/app/dashboards#/view/123`
* *Bill's space*: `http://localhost:5601/s/bills-space/app/dashboards#/view/123`

You use these two dashboards frequently, so you bookmark them in your web browser. After some time, you decide to upgrade to {kib} 8.0. When
these two dashboards go through the conversion process, the one in "Bill's space" will have its ID changed to "456". The URL to access that
dashboard is different -- not to worry though, there is a legacy URL alias for that dashboard.

If you use your bookmark to access that dashboard using its old URL, {kib} detects that you are using a legacy URL, and finds the new object
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`.

[[legacy-url-aliases-handling-errors]]
=== Handling errors

Legacy URL aliases are intended to be fully transparent, but there are rare situations where this can lead to an error. For example, you
might have a dashboard and one of the visualizations fails to load, directing you to this page. If you encounter an error in this situation,
you might want to disable the legacy URL alias completely. This leaves the saved object intact, and you will not lose any data -- you just
won't be able to use the old URL to access that saved object.

To disable a legacy URL alias, you need three pieces of information: the `targetSpace`, the `targetType`, and the `sourceId`. Then use the
<<spaces-api-disable-legacy-url-aliases,`_disable_legacy_url_aliases`>> API to disable the problematic legacy URL alias.
