[Dashboard as code] Embeddable API Integration

examples/embeddable_examples/common/book/content_management/cm_services.ts

@@ -0,0 +1,19 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { EmbeddableContentManagementDefinition } from '@kbn/embeddable-plugin/common';
+import { bookAttributesDefinition } from './schema';
+
+export const bookCmDefinitions: EmbeddableContentManagementDefinition = {
+  id: 'book',
+  versions: {
+    1: bookAttributesDefinition,
+  },
+  latestVersion: 1,
+};

examples/embeddable_examples/common/book/content_management/schema/constants.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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export const BOOK_LATEST_VERSION = 1;
+
+export const BOOK_CONTENT_ID = 'book';
+
+export const SEQUEL_TO_REF_NAME = 'kibanaSavedObjectMeta.sequelToBook.id';

examples/embeddable_examples/common/book/content_management/schema/index.ts

@@ -0,0 +1,12 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export { bookAttributesDefinition, bookItemSchema, type BookItem } from './schema';
+export { BOOK_CONTENT_ID, BOOK_LATEST_VERSION } from './constants';
+export { itemToSavedObject, savedObjectToItem } from './transforms';

examples/embeddable_examples/common/book/content_management/schema/schema.ts

@@ -0,0 +1,30 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { TypeOf, schema } from '@kbn/config-schema';
+import type { VersionableEmbeddableObject } from '@kbn/embeddable-plugin/common';
+import type { SavedBookAttributes } from '../../../../server/types';
+import { itemToSavedObject, savedObjectToItem } from './transforms';
+
+export const bookItemSchema = schema.object({
+  bookTitle: schema.string(),
+  author: schema.string(),
+  pages: schema.number(),
+  synopsis: schema.maybe(schema.string()),
+  published: schema.maybe(schema.number()),
+  sequelTo: schema.maybe(schema.string()),
+});
+
+export type BookItem = TypeOf<typeof bookItemSchema>;
+
+export const bookAttributesDefinition: VersionableEmbeddableObject<SavedBookAttributes, BookItem> =
+  {
+    itemToSavedObject,
+    savedObjectToItem,
+  };

examples/embeddable_examples/common/book/content_management/schema/transforms/index.ts

@@ -0,0 +1,11 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export { itemToSavedObject } from './item_to_saved_object';
+export { savedObjectToItem } from './saved_object_to_item';

examples/embeddable_examples/common/book/content_management/schema/transforms/item_to_saved_object.ts

@@ -0,0 +1,57 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type { SavedObjectAttributesWithReferences } from '@kbn/embeddable-plugin/common/types';
+import type { SavedObjectReference } from '@kbn/core/server';
+import { Mutable } from 'utility-types';
+import {
+  BOOK_SAVED_OBJECT_TYPE,
+  type SavedBookAttributes,
+} from '../../../../../server/book/saved_object';
+import { SEQUEL_TO_REF_NAME } from '../constants';
+import { BookItem } from '../schema';
+
+const extractReferences = (attributes: BookItem) => {
+  const references: SavedObjectReference[] = [];
+  const extractedRefNames: Mutable<Partial<SavedBookAttributes['metadata']>> = {};
+  if (attributes.sequelTo) {
+    extractedRefNames.sequelToBookRefName = SEQUEL_TO_REF_NAME;
+    references.push({
+      name: SEQUEL_TO_REF_NAME,
+      type: BOOK_SAVED_OBJECT_TYPE,
+      id: attributes.sequelTo,
+    });
+  }
+  return { references, extractedRefNames };
+};
+
+export const itemToSavedObject = (
+  attributes: BookItem
+): SavedObjectAttributesWithReferences<SavedBookAttributes> => {
+  const { references, extractedRefNames } = extractReferences(attributes);
+  return {
+    attributes: {
+      bookTitleAsArray: [...attributes.bookTitle],
+      metadata: {
+        numbers: {
+          numberOfPages: attributes.pages,
+          publicationYear: attributes.published ?? undefined,
+        },
+        text: {
+          authorName: attributes.author,
+          bookSynopsis: attributes.synopsis,
+        },
+        ...extractedRefNames,
+      },
+      // Generate a string of random letters and numbers to demonstrate simplifying a savedObject
+      uselessGarbage: Array.from(Array(10), () => Math.random().toString(36).substring(2)).join(''),
+    },
+    references,
+  };
+};

examples/embeddable_examples/common/book/content_management/schema/transforms/saved_object_to_item.ts

@@ -0,0 +1,61 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type { SavedObjectAttributesWithReferences } from '@kbn/embeddable-plugin/common/types';
+import type { SavedObjectReference } from '@kbn/core/server';
+import { Mutable } from 'utility-types';
+import type { SavedBookAttributes } from '../../../../../server/book/saved_object';
+import { BookItem } from '../schema';
+
+const injectReferences = (attributes: SavedBookAttributes, references: SavedObjectReference[]) => {
+  const injectedParams: Mutable<Partial<BookItem>> = {};
+  if (attributes.metadata.sequelToBookRefName) {
+    const sequelId = references.find((r) => r.name === attributes.metadata.sequelToBookRefName)?.id;
+    if (sequelId) injectedParams.sequelTo = sequelId;
+  }
+  return injectedParams;
+};
+
+// 8.x used this SavedObject schema to store Book embeddables in URLs
+// It is NOT recommended to radically change SavedObject schemas other than adding additional optional fields,
+// but legacy URL handling is a special case
+interface BookSavedURLObjectAttributes {
+  bookTitle: string;
+  bookSynopsis?: string;
+  numberOfPages: number;
+  authorName: string;
+}
+const isUrlObject = (so: unknown): so is BookSavedURLObjectAttributes =>
+  !!(so as BookSavedURLObjectAttributes).bookTitle;
+
+const savedURLObjectToItem = ({
+  bookTitle,
+  bookSynopsis,
+  numberOfPages,
+  authorName,
+}: BookSavedURLObjectAttributes): BookItem => ({
+  bookTitle,
+  synopsis: bookSynopsis,
+  author: authorName,
+  pages: numberOfPages,
+});
+
+export const savedObjectToItem = (
+  so: SavedObjectAttributesWithReferences<SavedBookAttributes> | BookSavedURLObjectAttributes
+): BookItem =>
+  isUrlObject(so)
+    ? savedURLObjectToItem(so)
+    : {
+        bookTitle: so.attributes.bookTitleAsArray.join(''),
+        author: so.attributes.metadata.text.authorName,
+        pages: so.attributes.metadata.numbers.numberOfPages,
+        synopsis: so.attributes.metadata.text.bookSynopsis,
+        published: so.attributes.metadata.numbers.publicationYear ?? undefined,
+        ...injectReferences(so.attributes, so.references),
+      };

examples/embeddable_examples/common/field_list/constants.ts

@@ -0,0 +1,11 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export const FIELD_LIST_DATA_VIEW_REF_NAME = 'field_list_data_view_id';
+export const FIELD_LIST_ID = 'field_list';

examples/embeddable_examples/common/field_list/content_management/cm_services.ts

@@ -0,0 +1,29 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { EmbeddableContentManagementDefinition } from '@kbn/embeddable-plugin/common';
+import { fieldListAttributesDefinition as fieldListAttributesDefinitionV1 } from './schema/v1';
+import { fieldListAttributesDefinition as fieldListAttributesDefinitionV2 } from './schema/v2';
+import { FIELD_LIST_ID } from '../constants';
+
+/**
+ * In version 1 of the field list, the client-side embeddable was expected to inject and extract references.
+ * So the `itemToSavedObject` and `savedObjectToItem` methods were identity functions.
+ * In version 2 of the field list, the server handles data views references.
+ * So the `itemToSavedObject` and `savedObjectToItem` methods perform reference extraction and injection
+ * and the embeddable client does not need to know about references.
+ */
+export const fieldListCmDefinitions: EmbeddableContentManagementDefinition = {
+  id: FIELD_LIST_ID,
+  versions: {
+    1: fieldListAttributesDefinitionV1,
+    2: fieldListAttributesDefinitionV2,
+  },
+  latestVersion: 2,
+};

examples/embeddable_examples/common/field_list/content_management/schema/v1/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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export { fieldListAttributesDefinition } from './v1';

examples/embeddable_examples/common/field_list/content_management/schema/v1/v1.ts

@@ -0,0 +1,20 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type { VersionableEmbeddableObject } from '@kbn/embeddable-plugin/common';
+import type { SavedFieldListAttributes } from '../../../../../server/types';
+import type { FieldListAttributes } from '../../../../../server/field_list/content_management/schema/v1';
+
+export const fieldListAttributesDefinition: VersionableEmbeddableObject<
+  SavedFieldListAttributes,
+  FieldListAttributes
+> = {
+  itemToSavedObject: (item) => ({ attributes: item, references: [] }),
+  savedObjectToItem: ({ attributes }) => attributes,
+};

examples/embeddable_examples/common/field_list/content_management/schema/v2/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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export { fieldListAttributesDefinition } from './v2';

examples/embeddable_examples/common/field_list/content_management/schema/v2/v2.ts

@@ -0,0 +1,48 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type { VersionableEmbeddableObject } from '@kbn/embeddable-plugin/common';
+import { DATA_VIEW_SAVED_OBJECT_TYPE } from '@kbn/data-views-plugin/common';
+import type { SavedFieldListAttributes } from '../../../../../server/types';
+import type { FieldListAttributes } from '../../../../../server/field_list/content_management/schema/v2';
+import { FIELD_LIST_DATA_VIEW_REF_NAME } from '../../../constants';
+
+export const fieldListAttributesDefinition: VersionableEmbeddableObject<
+  SavedFieldListAttributes,
+  FieldListAttributes
+> = {
+  itemToSavedObject: (item) => {
+    const { selectedFieldNames, dataViewId } = item;
+    const references = [];
+    if (dataViewId) {
+      // inject data view id as a reference
+      references.push({
+        name: FIELD_LIST_DATA_VIEW_REF_NAME,
+        type: DATA_VIEW_SAVED_OBJECT_TYPE,
+        id: dataViewId,
+      });
+    }
+    return {
+      attributes: {
+        // don't store the dataViewId, it's in the references
+        selectedFieldNames,
+      },
+      references,
+    };
+  },
+  savedObjectToItem: ({ attributes, references }) => {
+    const { selectedFieldNames } = attributes;
+    // inject data view id from references
+    const dataViewRef = references.find((ref) => ref.name === FIELD_LIST_DATA_VIEW_REF_NAME);
+    return {
+      selectedFieldNames,
+      dataViewId: dataViewRef?.id,
+    };
+  },
+};

examples/embeddable_examples/kibana.jsonc

@@ -5,9 +5,10 @@
   "description": "Example app that shows how to register custom embeddables",
   "plugin": {
     "id": "embeddableExamples",
-    "server": false,
+    "server": true,
     "browser": true,
     "requiredPlugins": [
+      "contentManagement",
       "dataViews",
       "embeddable",
       "uiActions",
@@ -18,6 +19,12 @@
       "developerExamples",
       "dataViewFieldEditor"
     ],
-    "requiredBundles": ["dashboard", "presentationUtil", "kibanaUtils", "kibanaReact"]
+    "requiredBundles": [
+      "dashboard",
+      "presentationUtil",
+      "kibanaUtils",
+      "kibanaReact",
+      "savedObjectsFinder"
+    ]
   }
 }

examples/embeddable_examples/public/app/app.tsx

@@ -56,10 +56,12 @@ const App = ({
       {
         id: 'presentationContainer',
         title: 'Create a dashboard like experience with embeddables',
-        component: <PresentationContainerExample uiActions={deps.uiActions} />,
+        component: (
+          <PresentationContainerExample uiActions={deps.uiActions} embeddable={deps.embeddable} />
+        ),
       },
     ];
-  }, [deps.uiActions]);
+  }, [deps.uiActions, deps.embeddable]);
 
   const routes = useMemo(() => {
     return pages.map((page) => (