IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Delete space API Resolve copy saved objects to space conflicts API »
Elastic Docs ›Kibana Guide [7.17] ›REST API ›Kibana spaces APIs

Copy saved objects to space API

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Copy 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, index patterns, 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

edit

POST <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 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.

This cannot be used with the overwrite option.

overwrite

(Optional, boolean) When set to true, all conflicts are automatically overidden. 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.

This 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 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.

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
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, or unknown. Errors marked as conflict or ambiguous_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, 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.

Objects are created when all resolvable errors are addressed, including conflict and missing references errors. For more information, refer to the examples.

Examples

edit

Successful copy (with createNewCopies enabled)

edit

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 an index pattern:

$ 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)

edit

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 an index pattern:

$ 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)

edit

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:

$ 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 index pattern, visualization, and Canvas workpad each resulted in a conflict error:

  • An index pattern 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 Resolve copy conflicts API.

Failed copy (with missing reference errors)

edit

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 an index pattern:

$ 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.

« Delete space API Resolve copy saved objects to space conflicts API »