[role="xpack"] [[spaces-api-copy-saved-objects]] === Copy saved objects to space API ++++ Copy saved objects to space ++++ experimental[] 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-sources}, 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 <> to do this on a per-object basis. [[spaces-api-copy-saved-objects-request]] ==== {api-request-title} `POST :/api/spaces/_copy_saved_objects` `POST :/s//api/spaces/_copy_saved_objects` [[spaces-api-copy-saved-objects-path-params]] ==== {api-path-parms-title} `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. [role="child_attributes"] [[spaces-api-copy-saved-objects-request-body]] ==== {api-request-body-title} `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` [%collapsible%open] ===== `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 is `false`. `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`. + NOTE: This cannot be used with the `overwrite` option. `overwrite`:: (Optional, boolean) When set to `true`, all conflicts are automatically overridden. When a saved object with a matching `type` and `id` exists in the target space, that version is replaced with the version from the source space. The default value is `false`. + NOTE: This cannot be used with the `createNewCopies` option. [role="child_attributes"] [[spaces-api-copy-saved-objects-response-body]] ==== {api-response-body-title} ``:: (object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response. + .Properties of `` [%collapsible%open] ===== `success`::: (boolean) The copy operation was successful. When set to `false`, some objects may have been copied. For additional information, refer to the `errors` and `successResults` 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 to `false`. + NOTE: One object may result in multiple errors, which requires separate steps to resolve. For instance, a `missing_references` error and a `conflict` error. + .Properties of `errors` [%collapsible%open] ====== `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` [%collapsible%open] ======= `type`:::: (string) The type of error. For example, `conflict`, `ambiguous_conflict`, `missing_references`, `unsupported_type`, or `unknown`. Errors marked as `conflict` or `ambiguous_conflict` may be resolved by using the <>. `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`, and `updatedAt` fields to describe each one. This is only present on `ambiguous_conflict` error types. ======= ====== `successResults`::: (Optional, array) Indicates successfully copied objects, with any applicable metadata. + NOTE: Objects are created when all resolvable errors are addressed, including conflict and missing references errors. For more information, refer to the <>. ===== [[spaces-api-copy-saved-objects-example]] ==== {api-examples-title} [[spaces-api-copy-saved-objects-example-1]] ===== Successful copy (with `createNewCopies` enabled) Copy 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-source}: [source,sh] ---- $ curl -X POST api/spaces/_copy_saved_objects { "objects": [{ "type": "dashboard", "id": "my-dashboard" }], "spaces": ["marketing"], "includeReferences": true } ---- // KIBANA The API returns the following: [source,sh] ---- { "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. [[spaces-api-copy-saved-objects-example-2]] ===== Successful copy (with `createNewCopies` disabled) Copy 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-source}: [source,sh] ---- $ curl -X POST api/spaces/_copy_saved_objects { "objects": [{ "type": "dashboard", "id": "my-dashboard" }], "spaces": ["marketing"], "includeReferences": true, "createNewCopies": false } ---- // KIBANA The API returns the following: [source,sh] ---- { "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. [[spaces-api-copy-saved-objects-example-3]] ===== Failed copy (with conflict errors) Copy 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: [source,sh] ---- $ curl -X POST api/spaces/_copy_saved_objects { "objects": [{ "type": "dashboard", "id": "my-dashboard" }], "spaces": ["marketing", "sales"], "includeReferences": true, "createNewCopies": false } ---- // KIBANA The API returns the following: [source,sh] ---- { "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-source}, visualization, and *Canvas* workpad each resulted in a conflict error: * A {data-source} 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 the `id` 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 <>. [[spaces-api-copy-saved-objects-example-4]] ===== Failed copy (with missing reference errors) Copy 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-source}: [source,sh] ---- $ curl -X POST api/spaces/_copy_saved_objects { "objects": [{ "type": "dashboard", "id": "my-dashboard" }], "spaces": ["marketing"], "includeReferences": true, "createNewCopies": false } ---- // KIBANA The API returns the following: [source,sh] ---- { "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 <>.