Saved objects (hereinafter "objects") are used to store all sorts of things in Kibana, from Dashboards to Index Patterns to Machine Learning Jobs. The effort to make objects shareable can be summarized in a single picture:

Each plugin can register different object types to be used in Kibana. Historically, objects could be isolated (existing in a single space) or global (existing in all spaces), there was no in-between. As of the 7.12 release, Kibana now supports two additional types of objects:

Ideally, most types of objects in Kibana will eventually be shareable; however, we have also introduced share-capable objects as a stepping stone for plugin developers to fully support this feature.

To implement this feature, we had to make a key change to how objects are serialized into raw Elasticsearch documents. As a result, some existing object IDs need to be changed, and this will cause some breaking changes to the way that consumers (plugin developers) interact with objects. We have implemented mitigations so that these changes will not affect end-users if consumers implement the required steps below.

Existing, isolated object types will need to go through a special conversion process to become share-capable upon upgrading Kibana to version 8.0. Once objects are converted, they can easily be switched to become fully shareable in any future release. This conversion will change the IDs of any existing objects that are not in the Default space. Changing object IDs itself has several knock-on effects:

To be perfectly clear: these effects will all be mitigated if and only if you follow the steps below!

If you’re still reading this page, you’re probably developing a Kibana plugin that registers an object type, and you want to know what steps you need to take to prepare for the 8.0 release and mitigate any breaking changes! Depending on how you are using saved objects, you may need to take up to 5 steps, which are detailed in separate sections below. Refer to this flowchart:

If your objects store any links to other objects (with an object type/ID), you need to take specific steps to ensure that these links continue functioning after the 8.0 upgrade.

⚠️ This step must be completed no later than the 7.16 release. ⚠️

If you answered "Yes" to Question 1, you need to make sure that your object links are only stored in the root-level references field. When a given object’s ID is changed, this field will be updated accordingly for other objects.

The image below shows two different examples of object links from a "case" object to an "action" object. The top shows the incorrect way to link to another object, and the bottom shows the correct way.

If your objects do not use the root-level references field, you’ll need to add a migration before the 8.0 release to fix that. Here’s a migration function for the example above:

function migrateCaseToV716(
  doc: SavedObjectUnsanitizedDoc<{ connector: { type: string; id: string } }>
): SavedObjectSanitizedDoc<unknown> {
  const {
    connector: { type: connectorType, id: connectorId, ...otherConnectorAttrs },
  } = doc.attributes;
  const { references = [] } = doc;
  return {
    ...doc,
    attributes: {
      ...doc.attributes,
      connector: otherConnectorAttrs,
    },
    references: [...references, { type: connectorType, id: connectorId, name: 'connector' }],
  };
}

...

// Use this migration function where the "case" object type is registered
migrations: {
  '7.16.0': migrateCaseToV716,
},

A deep link is a URL to a page that shows a specific object. End-users may bookmark these URLs or schedule reports with them, so it is critical to ensure that these URLs continue working. The image below shows an example of a deep link to a Canvas workpad object:

Note that some URLs may contain deep links to multiple objects, for example, a Dashboard and a filter for an Index Pattern.

⚠️ This step will preferably be completed in the 7.16 release; it must be completed no later than the 8.0 release. ⚠️

If you answered "Yes" to Question 2, you need to make sure that when you use the SavedObjectsClient to fetch an object using its ID, you use a different API to do so. The existing get() function will only find an object using its current ID. To make sure your existing deep link URLs don’t break, you should use the new resolve() function; this attempts to find an object using its old ID and its current ID.

In a nutshell, if your deep link page had something like this before:

const savedObject = savedObjectsClient.get(objType, objId);

You’ll need to change it to this:

const resolveResult = savedObjectsClient.resolve(objType, objId);
const savedObject = resolveResult.saved_object;

The SavedObjectsResolveResponse interface has three fields, summarized below:

The SavedObjectsClient is available both on the server-side and the client-side. You may be fetching the object on the server-side via a custom HTTP route, or you may be fetching it on the client-side directly. Either way, the outcome and alias_target_id fields need to be passed to your client-side code, and you should update your UI accordingly in the next step.

⚠️ This step will preferably be completed in the 7.16 release; it must be completed no later than the 8.0 release. ⚠️

The Spaces plugin API exposes React components and functions that you should use to render your UI in a consistent manner for end-users. Your UI will need to use the Core HTTP service and the Spaces plugin API to do this.

Your page should change according to the outcome:

⚠️ This step must be completed in the 8.0 release (no earlier and no later). ⚠️

After Step 3 is complete, you can add the code to convert your objects.

When you register your object, you need to change the namespaceType and also add a convertToMultiNamespaceTypeVersion field. This special field will trigger the actual conversion that will take place during the Core migration upgrade process when a user installs the Kibana 8.0 release:

Saved objects can optionally be encrypted by using the Encrypted Saved Objects plugin. Very few object types are encrypted, so most plugin developers will not be affected.

⚠️ This step must be completed in the 8.0 release (no earlier and no later). ⚠️

If you answered "Yes" to Question 3, you need to take additional steps to make sure that your objects can still be decrypted after the conversion process. Encrypted saved objects use some fields as part of "additionally authenticated data" (AAD) to defend against different types of cryptographic attacks. The object ID is part of this AAD, and so it follows that the after the object’s ID is changed, the object will not be able to be decrypted with the standard process.

To mitigate this, you need to add a "no-op" ESO migration that will be applied immediately after the object is converted during the 8.0 upgrade process. This will decrypt the object using its old ID and then re-encrypt it using its new ID:

This is not required for the 8.0 release; this additional information will be added in the near future!