Resolve copy saved objects to space conflicts API

edit

Resolve copy saved objects to space conflicts 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. Overwrite saved objects that are returned as errors from the copy saved objects to space API.

Request

edit

POST <kibana host>:<port>/api/spaces/_resolve_copy_saved_objects_errors

POST <kibana host>:<port>/s/<space_id>/api/spaces/_resolve_copy_saved_objects_errors

Prerequisites

edit

Execute the copy saved objects to space API, which returns the errors for you to resolve.

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. The space_id must be the same value used during the failed copy saved objects to space API operation.

Request body

edit
objects

(Required, object array) The saved objects to copy. The objects must be the same values used during the failed copy saved objects to space API operation.

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 are copied into the target spaces. The includeReferences must be the same values used during the failed copy saved objects to space API operation. The default value is false.
createNewCopies
(Optional, boolean) Creates new copies of the saved objects, regenerates each object ID, and resets the origin. When enabled during the initial copy, also enable when resolving copy errors. The default value is true.
retries

(Required, object) The retry operations to attempt, which can specify how to resolve different types of errors. Object keys represent the target space IDs.

Properties of retries
<space_id>

(Required, array) The errors to resolve for the specified <space_id>.

Properties of <space_id>
type
(Required, string) The saved object type.
id
(Required, string) The saved object ID.
overwrite
(Required, boolean) When set to true, the saved object from the source space (desigated by the space_id path parameter) overwrites the conflicting object in the destination space. When set to false, this does nothing.
destinationId

(Optional, string) Specifies the destination ID that the copied object should have, if different from the current ID.

ignoreMissingReferences
(Optional, boolean) When set to true, any missing references errors are ignored. When set to false, does nothing.

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 successCount and errors 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.
destinationId
(Optional, string) The destination ID that was used during the copy attempt. This is only present on conflict errors 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

Resolve conflict errors

edit

This example builds upon the Copy objects API example with conflict errors.

Resolve conflict errors for an index pattern, visualization, and Canvas workpad by overwriting the existing saved objects:

$ curl -X POST api/spaces/_resolve_copy_saved_objects_errors
{
  "objects": [{
    "type": "dashboard",
    "id": "my-dashboard"
  }],
  "includeReferences": true,
  "createNewCopies": false,
  "retries": {
    "sales": [
      {
        "type": "index-pattern",
        "id": "my-pattern",
        "overwrite": true
      },
      {
        "type": "visualization",
        "id": "my-vis",
        "overwrite": true,
        "destinationId": "another-vis"
      },
      {
        "type": "canvas",
        "id": "my-canvas",
        "overwrite": true,
        "destinationId": "yet-another-canvas"
      },
      {
        "type": "dashboard",
        "id": "my-dashboard"
      }
    ]
  }
}

The API returns the following:

{
  "sales": {
    "success": true,
    "successCount": 4,
    "successResults": [
      {
        "id": "my-pattern",
        "type": "index-pattern",
        "meta": {
          "icon": "indexPatternApp",
          "title": "my-pattern-*"
        }
      },
      {
        "id": "my-vis",
        "type": "visualization",
        "destinationId": "another-vis",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        }
      },
      {
        "id": "my-canvas",
        "type": "canvas-workpad",
        "destinationId": "yet-another-canvas",
        "meta": {
          "icon": "canvasApp",
          "title": "Look at my canvas"
        }
      },
      {
        "id": "my-dashboard",
        "type": "dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        }
      }
    ]
  }
}

The result indicates a successful copy, and all four objects are created.

If a prior copy attempt resulted in resolvable errors, you must include a retry for each object you want to copy, including any that were returned in the successResults array. In this example, we retried copying the dashboard accordingly.

Resolve missing reference errors

edit

This example builds upon the Copy objects API example with missing reference errors.

Resolve missing reference errors for a visualization by ignoring the error:

$ curl -X POST api/spaces/_resolve_copy_saved_objects_errors
{
  "objects": [{
    "type": "dashboard",
    "id": "my-dashboard"
  }],
  "includeReferences": true,
  "createNewCopies": false,
  "retries": {
    "marketing": [
      {
        "type": "visualization",
        "id": "my-vis",
        "ignoreMissingReferences": true
      },
      {
        "type": "canvas",
        "id": "my-canvas"
      },
      {
        "type": "dashboard",
        "id": "my-dashboard"
      }
    ]
  }
}

The API returns the following:

{
  "marketing": {
    "success": true,
    "successCount": 3,
    "successResults": [
      {
        "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-dashboard",
        "type": "dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        }
      }
    ]
  }
}

The result indicates a successful copy and all three objects are created.

If a prior copy attempt resulted in resolvable errors, you must include a retry for each object you want to copy, including any that were returned in the successResults array. In this example, we retried copying the dashboard and canvas accordingly.