Enhance documentation on accessing hidden SO types (#199046)

Saved objects declared as `hidden` can only be accessed with a client that explicitly includes hidden types. ### Checklist - [x] [Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html) was added for features that require explanation or tutorials --------- Co-authored-by: Alejandro Fernández Haro <[email protected]>
elastic · Nov 6, 2024 · 73f3154 · 73f3154
1 parent 199792f
commit 73f3154
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 2 deletions.
diff --git a/dev_docs/tutorials/saved_objects.mdx b/dev_docs/tutorials/saved_objects.mdx
@@ -18,7 +18,7 @@ import { SavedObjectsType } from 'src/core/server';
 
 export const dashboardVisualization: SavedObjectsType = {
   name: 'dashboard_visualization', [1]
-  hidden: true,
+  hidden: true, [3]
   switchToModelVersionAt: '8.10.0', // this is the default, feel free to omit it unless you intend to switch to using model versions before 8.10.0
   namespaceType: 'multiple-isolated', [2]
   mappings: {
@@ -46,6 +46,9 @@ these should follow our API URL path convention and always be written in snake c
 that objects of this type can only exist in a single space. See
 <DocLink id="kibDevDocsSavedObjectsIntro" section="sharing-saved-objects" text="Sharing Saved Objects"/> for more information.
 
+[3] This field determines whether repositories have access to the type by default. Hidden types will not be automatically exposed via the Saved Objects Client APIs.
+Hidden types must be listed in `SavedObjectsClientProviderOptions[includedHiddenTypes]` to be accessible by the client.
+
 **src/plugins/my_plugin/server/saved_objects/index.ts**
 
 ```ts
@@ -301,4 +304,4 @@ export const foo: SavedObjectsType = {
 
 [1] Needs to be `false` to use the `hiddenFromHttpApis` option
 
-[2] Set this to `true` to build your own HTTP API and have complete control over the route handler.
+[2] Set this to `true` to build your own HTTP API and have complete control over the route handler.
diff --git a/packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts b/packages/core/saved-objects/core-saved-objects-server/src/saved_objects_type.ts
@@ -37,7 +37,12 @@ export interface SavedObjectsType<Attributes = any> {
    * The hidden types will not be automatically exposed via the HTTP API.
    * Therefore, that should prevent unexpected behavior in the client code, as all the interactions will be done via the plugin API.
    *
+   * Hidden types must be listed to be accessible by the client.
+   *
+   * (await context.core).savedObjects.getClient({ includeHiddenTypes: [MY_PLUGIN_HIDDEN_SAVED_OBJECT_TYPE] })
+   *
    * See {@link SavedObjectsServiceStart.createInternalRepository | createInternalRepository}.
+   *
    */
   hidden: boolean;
   /**