Copy saved objects to space API
editCopy saved objects to space API
edit[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Copy saved objects between spaces.
It also allows you to automatically copy related objects, so when you copy a dashboard
, this can automatically copy over the
associated visualizations, data views, and saved searches, as required.
You can request to overwrite any objects that already exist in the target space if they share an ID, or you can use the Resolve copy saved objects conflicts API to do this on a per-object basis.
Request
editPOST <kibana host>:<port>/api/spaces/_copy_saved_objects
POST <kibana host>:<port>/s/<space_id>/api/spaces/_copy_saved_objects
Path parameters
edit-
space_id
-
(Optional, string) The ID of the space that contains the saved objects you want to copy. When
space_id
is unspecified in the URL, the default space is used.
Request body
edit-
spaces
- (Required, string array) The IDs of the spaces where you want to copy the specified objects.
-
objects
-
(Required, object array) The saved objects to copy.
Properties of
objects
-
type
- (Required, string) The saved object type.
-
id
- (Required, string) The saved object ID.
-
-
includeReferences
-
(Optional, boolean) When set to
true
, all saved objects related to the specified saved objects will also be copied into the target spaces. The default value isfalse
. -
createNewCopies
-
(Optional, boolean) Creates new copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict errors are avoided. The default value is
true
.This option cannot be used with the
overwrite
andcompatibilityMode
options. -
overwrite
-
(Optional, boolean) When set to
true
, all conflicts are automatically overridden. When a saved object with a matchingtype
andid
exists in the target space, that version is replaced with the version from the source space. The default value isfalse
.This option cannot be used with the
createNewCopies
option. -
compatibilityMode
-
(Optional, boolean) Applies various adjustments to the saved objects that are being copied to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with copied saved objects.
This option cannot be used with the
createNewCopies
option.
Response codes
edit-
200
- Indicates a successful call.
-
404
- Indicates that the request failed because one or more of the objects specified could not be found. A list of the unresolved objects are included in the 404 response attributes.
Response body
edit-
<space_id>
-
(object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response.
Properties of
<space_id>
-
success
-
(boolean) The copy operation was successful. When set to
false
, some objects may have been copied. For additional information, refer to theerrors
andsuccessResults
properties. -
successCount
- (number) The number of objects that successfully copied.
-
errors
-
(Optional, array) The errors that occurred during the copy operation. When errors are reported, the
success
flag is set tofalse
.One object may result in multiple errors, which requires separate steps to resolve. For instance, a
missing_references
error and aconflict
error.Properties of
errors
-
id
- (string) The saved object ID that failed to copy.
-
type
- (string) The type of saved object that failed to copy.
-
error
-
(object) The error that caused the copy operation to fail.
Properties of
error
-
type
-
(string) The type of error. For example,
conflict
,ambiguous_conflict
,missing_references
,unsupported_type
, orunknown
. Errors marked asconflict
orambiguous_conflict
may be resolved by using the Resolve copy saved objects conflicts API. -
destinationId
-
(Optional, string) The destination ID that was used during the copy attempt. This is only present on
conflict
error types. -
destinations
-
(Optional, array) A list of possible object destinations with
id
,title
, andupdatedAt
fields to describe each one. This is only present onambiguous_conflict
error types.
-
-
-
successResults
-
(Optional, array) Indicates successfully copied objects, with any applicable metadata.
Objects are created when all resolvable errors are addressed, including conflict and missing references errors. For more information, refer to the examples.
-
Examples
editSuccessful copy (with createNewCopies
enabled)
editCopy a dashboard with the my-dashboard
ID, including all references from the default
space to the marketing
space. In this example,
the dashboard has a reference to a visualization, and that has a reference to a data view:
$ curl -X POST api/spaces/_copy_saved_objects { "objects": [{ "type": "dashboard", "id": "my-dashboard" }], "spaces": ["marketing"], "includeReferences": true }
The API returns the following:
{ "marketing": { "success": true, "successCount": 3, "successResults": [ { "id": "my-dashboard", "type": "dashboard", "destinationId": "1e127098-5b80-417f-b0f1-c60c8395358f", "meta": { "icon": "dashboardApp", "title": "Look at my dashboard" } }, { "id": "my-vis", "type": "visualization", "destinationId": "a610ed80-1c73-4507-9e13-d3af736c8e04", "meta": { "icon": "visualizeApp", "title": "Look at my visualization" } }, { "id": "my-index-pattern", "type": "index-pattern", "destinationId": "bc3c9c70-bf6f-4bec-b4ce-f4189aa9e26b", "meta": { "icon": "indexPatternApp", "title": "my-pattern-*" } } ] } }
The result indicates a successful copy, and all three objects are created. Since these objects were created as new copies, each entry in the
successResults
array includes a destinationId
attribute.
Successful copy (with createNewCopies
disabled)
editCopy a dashboard with the my-dashboard
ID, including all references from the default
space to the marketing
space. In this example,
the dashboard has a reference to a visualization, and that has a reference to a data view:
$ curl -X POST api/spaces/_copy_saved_objects { "objects": [{ "type": "dashboard", "id": "my-dashboard" }], "spaces": ["marketing"], "includeReferences": true, "createNewCopies": false }
The API returns the following:
{ "marketing": { "success": true, "successCount": 3, "successResults": [ { "id": "my-dashboard", "type": "dashboard", "meta": { "icon": "dashboardApp", "title": "Look at my dashboard" } }, { "id": "my-vis", "type": "visualization", "meta": { "icon": "visualizeApp", "title": "Look at my visualization" } }, { "id": "my-index-pattern", "type": "index-pattern", "meta": { "icon": "indexPatternApp", "title": "my-pattern-*" } } ] } }
The result indicates a successful copy, and all three objects are created.
Failed copy (with conflict errors)
editCopy a dashboard with the my-dashboard
ID, including all references from the default
space to the marketing
and sales
spaces. In
this example, the dashboard has a reference to a visualization and a Canvas workpad, and the visualization has a reference to an index
pattern:
$ curl -X POST api/spaces/_copy_saved_objects { "objects": [{ "type": "dashboard", "id": "my-dashboard" }], "spaces": ["marketing", "sales"], "includeReferences": true, "createNewCopies": false }
The API returns the following:
{ "marketing": { "success": true, "successCount": 4, "successResults": [ { "id": "my-dashboard", "type": "dashboard", "meta": { "icon": "dashboardApp", "title": "Look at my dashboard" } }, { "id": "my-vis", "type": "visualization", "meta": { "icon": "visualizeApp", "title": "Look at my visualization" } }, { "id": "my-canvas", "type": "canvas-workpad", "meta": { "icon": "canvasApp", "title": "Look at my canvas" } }, { "id": "my-index-pattern", "type": "index-pattern", "meta": { "icon": "indexPatternApp", "title": "my-pattern-*" } } ] }, "sales": { "success": false, "successCount": 1, "errors": [ { "id": "my-pattern", "type": "index-pattern", "title": "my-pattern-*", "error": { "type": "conflict" }, "meta": { "icon": "indexPatternApp", "title": "my-pattern-*" } }, { "id": "my-visualization", "type": "my-vis", "title": "Look at my visualization", "error": { "type": "conflict", "destinationId": "another-vis" }, "meta": { "icon": "visualizeApp", "title": "Look at my visualization" } }, { "id": "my-canvas", "type": "canvas-workpad", "title": "Look at my canvas", "error": { "type": "ambiguous_conflict", "destinations": [ { "id": "another-canvas", "title": "Look at another canvas", "updatedAt": "2020-07-08T16:36:32.377Z" }, { "id": "yet-another-canvas", "title": "Look at yet another canvas", "updatedAt": "2020-07-05T12:29:54.849Z" } ] }, "meta": { "icon": "canvasApp", "title": "Look at my canvas" } } ], "successResults": [ { "id": "my-dashboard", "type": "dashboard", "meta": { "icon": "dashboardApp", "title": "Look at my dashboard" } } ] } }
The result indicates a successful copy for the marketing
space, and an unsuccessful copy for the sales
space because the data view,
visualization, and Canvas workpad each resulted in a conflict error:
- A data view with the same ID already exists, which resulted in a conflict error. To resolve the error, overwrite the existing object, or skip the object.
-
A visualization with a different ID, but the same origin already exists, which resulted in a conflict error. The
destinationId
field contains theid
of the other visualization, which caused the conflict. The behavior is added to make sure that new objects that can be shared between spaces behave in a similar way as legacy non-shareable objects. When a shareable object is copied into a new space, it retains its origin so that the conflicts are encountered as expected. To resolve, overwrite the specified destination object, or skip the object. -
Two Canvas workpads with different IDs, but the same origin, already exist, which resulted in a conflict error. The
destinations
array describes the other workpads which caused the conflict. When a shareable object is copied into a new space, then shared to another space where an object of the same origin exists, the conflict error occurs. To resolve, pick a destination object to overwrite, or skip the object.
Objects are created when the error is resolved using the Resolve copy conflicts API.
Failed copy (with missing reference errors)
editCopy a dashboard with the my-dashboard
ID, including all references from the default
space to the marketing
space. In this example,
the dashboard has a reference to a visualization and a Canvas workpad, and the visualization has a reference to a data view:
$ curl -X POST api/spaces/_copy_saved_objects { "objects": [{ "type": "dashboard", "id": "my-dashboard" }], "spaces": ["marketing"], "includeReferences": true, "createNewCopies": false }
The API returns the following:
{ "marketing": { "success": false, "successCount": 2, "errors": [ { "id": "my-vis", "type": "visualization", "title": "Look at my visualization", "error": { "type": "missing_references", "references": [ { "type": "index-pattern", "id": "my-pattern-*" } ] }, "meta": { "icon": "visualizeApp", "title": "Look at my visualization" } }, ] "successResults": [ { "id": "my-dashboard", "type": "dashboard", "meta": { "icon": "dashboardApp", "title": "Look at my dashboard" } }, { "id": "my-canvas", "type": "canvas-workpad", "meta": { "icon": "canvasApp", "title": "Look at my canvas" } } ], } }
The result indicates an unsuccessful copy because the visualization resulted in a missing references error.
Objects are created when the errors are resolved using the Resolve copy conflicts API.