[Dashboard navigation] Inject/extract references (#164330)

Fixes #154363

## Summary

Extracts and injects references to Dashboards in Link panels to allow
sharing / importing to other Spaces.

To test this:

1. Create an empty dashboard.
1. Create a Links panel on the dashboard and save to library.
1. Save the dashboard as one or more new dashboards.
1. Update the Links panel with links to the new dashboards.
1. Create two new Spaces, "space1" and "space2" with the default
settings.
1. In Saved Objects, click the Actions button for your Links and choose
"Copy to Spaces".
1. Copy the Links to "space1".
1. Switch to the "space1" space and verify all the dashboards using that
Links panel were included.
1. In Saved Objects, select the Links saved object and export it
including all related objects
1. Switch to "space2" and import the Links saved object from the file
downloaded in the previous step.
1. Verify all the dashboards were also imported.
1. Inspect the saved object for the Links. The `references` array should
contain objects for each dashboard.
1. The `attributes.links[].destination` property should be a string in
the format of `links_<someuuid>_dashboard`. This string should match one
of the `references[].id`.

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

src/plugins/dashboard/public/services/dashboard_content_management/lib/find_dashboards.ts

@@ -80,6 +80,7 @@ export async function findDashboardById(
       id,
       status: 'success',
       attributes: cachedDashboard.item.attributes,
+      references: cachedDashboard.item.references,
     };
   }
   /** Otherwise, fetch the dashboard from the content management client, add it to the cache, and return the result */

src/plugins/navigation_embeddable/common/content_management/index.ts

@@ -24,6 +24,7 @@ export {
   DASHBOARD_LINK_TYPE,
   NAV_VERTICAL_LAYOUT,
   NAV_HORIZONTAL_LAYOUT,
+  EXTERNAL_LINK_SUPPORTED_PROTOCOLS,
 } from './latest';
 
 export * as NavigationEmbeddableV1 from './v1';

src/plugins/navigation_embeddable/common/content_management/v1/cm_services.ts

@@ -16,21 +16,35 @@ import {
   objectTypeToGetResultSchema,
 } from '@kbn/content-management-utils';
 import { DASHBOARD_LINK_TYPE, EXTERNAL_LINK_TYPE } from '.';
-import { NAV_HORIZONTAL_LAYOUT, NAV_VERTICAL_LAYOUT } from './constants';
+import {
+  EXTERNAL_LINK_SUPPORTED_PROTOCOLS,
+  NAV_HORIZONTAL_LAYOUT,
+  NAV_VERTICAL_LAYOUT,
+} from './constants';
 
-const navigationEmbeddableLinkSchema = schema.object({
+const baseNavigationEmbeddableLinkSchema = {
   id: schema.string(),
-  type: schema.oneOf([schema.literal(DASHBOARD_LINK_TYPE), schema.literal(EXTERNAL_LINK_TYPE)]),
-  destination: schema.string(),
   label: schema.maybe(schema.string()),
   order: schema.number(),
+};
+
+const dashboardLinkSchema = schema.object({
+  ...baseNavigationEmbeddableLinkSchema,
+  destinationRefName: schema.string(),
+  type: schema.literal(DASHBOARD_LINK_TYPE),
+});
+
+const externalLinkSchema = schema.object({
+  ...baseNavigationEmbeddableLinkSchema,
+  type: schema.literal(EXTERNAL_LINK_TYPE),
+  destination: schema.uri({ scheme: EXTERNAL_LINK_SUPPORTED_PROTOCOLS }),
 });
 
 const navigationEmbeddableAttributesSchema = schema.object(
   {
     title: schema.string(),
     description: schema.maybe(schema.string()),
-    links: schema.maybe(schema.arrayOf(navigationEmbeddableLinkSchema)),
+    links: schema.arrayOf(schema.oneOf([dashboardLinkSchema, externalLinkSchema])),
     layout: schema.maybe(
       schema.oneOf([schema.literal(NAV_HORIZONTAL_LAYOUT), schema.literal(NAV_VERTICAL_LAYOUT)])
     ),

src/plugins/navigation_embeddable/common/content_management/v1/constants.ts

@@ -17,3 +17,5 @@ export const EXTERNAL_LINK_TYPE = 'externalLink';
  */
 export const NAV_HORIZONTAL_LAYOUT = 'horizontal';
 export const NAV_VERTICAL_LAYOUT = 'vertical';
+
+export const EXTERNAL_LINK_SUPPORTED_PROTOCOLS = ['http', 'https', 'mailto'];

src/plugins/navigation_embeddable/common/content_management/v1/index.ts

@@ -20,4 +20,5 @@ export {
   DASHBOARD_LINK_TYPE,
   NAV_VERTICAL_LAYOUT,
   NAV_HORIZONTAL_LAYOUT,
+  EXTERNAL_LINK_SUPPORTED_PROTOCOLS,
 } from './constants';

src/plugins/navigation_embeddable/common/content_management/v1/types.ts

@@ -35,14 +35,25 @@ export type NavigationEmbeddableCrudTypes = ContentManagementCrudTypes<
  */
 export type NavigationLinkType = typeof DASHBOARD_LINK_TYPE | typeof EXTERNAL_LINK_TYPE;
 
-export interface NavigationEmbeddableLink {
+interface BaseNavigationEmbeddableLink {
   id: string;
-  type: NavigationLinkType;
-  destination: string;
   label?: string;
   order: number;
+  destination?: string;
+}
+
+interface DashboardLink extends BaseNavigationEmbeddableLink {
+  type: typeof DASHBOARD_LINK_TYPE;
+  destinationRefName?: string;
 }
 
+interface ExternalLink extends BaseNavigationEmbeddableLink {
+  type: typeof EXTERNAL_LINK_TYPE;
+  destination: string;
+}
+
+export type NavigationEmbeddableLink = DashboardLink | ExternalLink;
+
 export type NavigationLayoutType = typeof NAV_HORIZONTAL_LAYOUT | typeof NAV_VERTICAL_LAYOUT;
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions

src/plugins/navigation_embeddable/common/embeddable/extract.test.ts

@@ -0,0 +1,64 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { extract } from './extract';
+
+test('Should return original state and empty references with by-reference embeddable state', () => {
+  const navigationEmbeddableByReferenceInput = {
+    id: '2192e502-0ec7-4316-82fb-c9bbf78525c4',
+    type: 'navigation_embeddable',
+  };
+
+  expect(extract!(navigationEmbeddableByReferenceInput)).toEqual({
+    state: navigationEmbeddableByReferenceInput,
+    references: [],
+  });
+});
+
+test('Should update state with refNames with by-value embeddable state', () => {
+  const navigationEmbeddableByValueInput = {
+    id: '8d62c3f0-c61f-4c09-ac24-9b8ee4320e20',
+    attributes: {
+      links: [
+        {
+          type: 'dashboardLink',
+          id: 'fc7b8c70-2eb9-40b2-936d-457d1721a438',
+          destination: 'elastic_agent-1a4e7280-6b5e-11ed-98de-67bdecd21824',
+          order: 0,
+        },
+      ],
+      layout: 'horizontal',
+    },
+    type: 'navigation_embeddable',
+  };
+
+  expect(extract!(navigationEmbeddableByValueInput)).toEqual({
+    references: [
+      {
+        name: 'link_fc7b8c70-2eb9-40b2-936d-457d1721a438_dashboard',
+        type: 'dashboard',
+        id: 'elastic_agent-1a4e7280-6b5e-11ed-98de-67bdecd21824',
+      },
+    ],
+    state: {
+      id: '8d62c3f0-c61f-4c09-ac24-9b8ee4320e20',
+      attributes: {
+        links: [
+          {
+            type: 'dashboardLink',
+            id: 'fc7b8c70-2eb9-40b2-936d-457d1721a438',
+            destinationRefName: 'link_fc7b8c70-2eb9-40b2-936d-457d1721a438_dashboard',
+            order: 0,
+          },
+        ],
+        layout: 'horizontal',
+      },
+      type: 'navigation_embeddable',
+    },
+  });
+});

src/plugins/navigation_embeddable/common/embeddable/extract.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { EmbeddableRegistryDefinition } from '@kbn/embeddable-plugin/common';
+import type { NavigationEmbeddableAttributes } from '../content_management';
+import { extractReferences } from '../persistable_state';
+import { NavigationEmbeddablePersistableState } from './types';
+
+export const extract: EmbeddableRegistryDefinition['extract'] = (state) => {
+  const typedState = state as NavigationEmbeddablePersistableState;
+
+  // by-reference embeddable
+  if (!('attributes' in typedState) || typedState.attributes === undefined) {
+    // No references to extract for by-reference embeddable since all references are stored with by-reference saved object
+    return { state, references: [] };
+  }
+
+  // by-value embeddable
+  const { attributes, references } = extractReferences({
+    attributes: typedState.attributes as unknown as NavigationEmbeddableAttributes,
+  });
+
+  return {
+    state: {
+      ...state,
+      attributes,
+    },
+    references,
+  };
+};

src/plugins/navigation_embeddable/common/embeddable/index.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export { inject } from './inject';
+export { extract } from './extract';

src/plugins/navigation_embeddable/common/embeddable/inject.test.ts

@@ -0,0 +1,69 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { inject } from './inject';
+
+test('Should return original state with by-reference embeddable state', () => {
+  const navigationEmbeddableByReferenceInput = {
+    id: 'ea40fd4e-216c-49a7-917f-f733c8a2c817',
+    type: 'navigation_embeddable',
+  };
+
+  const references = [
+    {
+      name: 'panel_ea40fd4e-216c-49a7-917f-f733c8a2c817',
+      type: 'navigation_embeddable',
+      id: '7f92d7d0-8e5f-11ec-9477-312c8a6de896',
+    },
+  ];
+
+  expect(inject!(navigationEmbeddableByReferenceInput, references)).toEqual(
+    navigationEmbeddableByReferenceInput
+  );
+});
+
+test('Should inject refNames with by-value embeddable state', () => {
+  const navigationEmbeddableByValueInput = {
+    id: 'c3937cf9-29be-43df-a4af-a4df742d7d35',
+    attributes: {
+      links: [
+        {
+          type: 'dashboardLink',
+          id: 'fc7b8c70-2eb9-40b2-936d-457d1721a438',
+          destinationRefName: 'link_fc7b8c70-2eb9-40b2-936d-457d1721a438_dashboard',
+          order: 0,
+        },
+      ],
+      layout: 'horizontal',
+    },
+    type: 'navigation_embeddable',
+  };
+  const references = [
+    {
+      name: 'link_fc7b8c70-2eb9-40b2-936d-457d1721a438_dashboard',
+      type: 'dashboard',
+      id: 'elastic_agent-1a4e7280-6b5e-11ed-98de-67bdecd21824',
+    },
+  ];
+
+  expect(inject!(navigationEmbeddableByValueInput, references)).toEqual({
+    id: 'c3937cf9-29be-43df-a4af-a4df742d7d35',
+    attributes: {
+      links: [
+        {
+          type: 'dashboardLink',
+          id: 'fc7b8c70-2eb9-40b2-936d-457d1721a438',
+          destination: 'elastic_agent-1a4e7280-6b5e-11ed-98de-67bdecd21824',
+          order: 0,
+        },
+      ],
+      layout: 'horizontal',
+    },
+    type: 'navigation_embeddable',
+  });
+});

src/plugins/navigation_embeddable/common/embeddable/inject.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { EmbeddableRegistryDefinition } from '@kbn/embeddable-plugin/common';
+import { NavigationEmbeddableAttributes } from '../content_management';
+import { injectReferences } from '../persistable_state';
+import { NavigationEmbeddablePersistableState } from './types';
+
+export const inject: EmbeddableRegistryDefinition['inject'] = (state, references) => {
+  const typedState = state as NavigationEmbeddablePersistableState;
+
+  // by-reference embeddable
+  if (!('attributes' in typedState) || typedState.attributes === undefined) {
+    return typedState;
+  }
+
+  // by-value embeddable
+  try {
+    const { attributes: attributesWithInjectedIds } = injectReferences({
+      attributes: typedState.attributes as unknown as NavigationEmbeddableAttributes,
+      references,
+    });
+
+    return {
+      ...typedState,
+      attributes: attributesWithInjectedIds,
+    };
+  } catch (error) {
+    // inject exception prevents entire dashboard from display
+    // Instead of throwing, swallow error and let dashboard display
+    // Errors will surface in navigation embeddable panel.
+    // Users can then manually edit links to resolve any problems.
+    return typedState;
+  }
+};

src/plugins/navigation_embeddable/common/embeddable/types.ts

@@ -0,0 +1,14 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { EmbeddableStateWithType } from '@kbn/embeddable-plugin/common';
+import { SerializableRecord } from '@kbn/utility-types';
+
+export type NavigationEmbeddablePersistableState = EmbeddableStateWithType & {
+  attributes: SerializableRecord;
+};

src/plugins/navigation_embeddable/common/persistable_state/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export { extractReferences, injectReferences } from './references';