Docs
Kibana Guide [7.12] » REST API » Saved objects APIs » Resolve import errors API
« Import objects API Resolve object API »

Resolve import errors APIedit

[experimental] This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features. Resolve errors from the Import objects API.

To resolve errors, you can:

  • Retry certain saved objects
  • Overwrite specific saved objects
  • Change references to different saved objects

Requestedit

POST <kibana host>:<port>/api/saved_objects/_resolve_import_errors

POST <kibana host>:<port>/s/<space_id>/api/saved_objects/_resolve_import_errors

Path parametersedit

space_id
(Optional, string) An identifier for the space. When space_id is unspecfied in the URL, the default space is used.

Query parametersedit

createNewCopies
(Optional, boolean) Creates copies of the saved objects, regenerates each object ID, and resets the origin. When enabled during the initial import, also enable when resolving import errors.

Request bodyedit

The request body must include the multipart/form-data type.

file
The same file given to the import API.
retries

(Required, array) The retry operations, which can specify how to resolve different types of errors.

Properties of <retries>
type
(Required, string) The saved object type.
id
(Required, string) The saved object ID.
overwrite
(Optional, boolean) When set to true, the source object overwrites the conflicting destination object. When set to false, does nothing.
destinationId
(Optional, string) Specifies the destination ID that the imported object should have, if different from the current ID.
replaceReferences
(Optional, array) A list of type, from, and to used to change the object references.
ignoreMissingReferences
(Optional, boolean) When set to true, ignores missing reference errors. When set to false, does nothing.

Response bodyedit

success
(boolean) Indicates a successful import. When set to false, some objects may not have been created. For additional information, refer to the errors and successResults properties.
successCount
(number) Indicates the number of successfully resolved records.
errors

(Optional, array) Specifies the objects that failed to resolve.

One object can result in multiple errors, which requires separate steps to resolve. For instance, a missing_references error and a conflict error.

successResults

(Optional, array) Indicates the objects that are successfully imported, with any metadata if applicable.

Objects are only created when all resolvable errors are addressed, including conflict and missing references. To resolve errors, refer to the examples.

Response codeedit

200
Indicates a successful call.

Examplesedit

Resolve conflict errorsedit

This example builds upon the Import 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/saved_objects/_resolve_import_errors -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"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 file.ndjson file contains the following:

{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"visualization","id":"my-vis","attributes":{"title":"Look at my visualization"}}
{"type":"canvas-workpad","id":"my-canvas","attributes":{"name":"Look at my canvas"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}

The API returns the following:

{
  "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 import, and all four objects were created.

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

Resolve missing reference errorsedit

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

Resolve a missing reference error for a visualization by replacing the index pattern with another, and resolve a missing reference error for a search by ignoring it:

$ curl -X POST api/saved_objects/_resolve_import_errors -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"visualization","id":"my-vis","replaceReferences":[{"type":"index-pattern","from":"my-pattern-*","to":"existing-pattern"}]},{"type":"search","id":"my-search","ignoreMissingReferences":true},{"type":"dashboard","id":"my-dashboard"}]'

The file.ndjson file contains the following:

{"type":"visualization","id":"my-vis","attributes":{"title":"Look at my visualization"},"references":[{"name":"ref_0","type":"index-pattern","id":"my-pattern-*"}]}
{"type":"search","id":"my-search","attributes":{"title":"Look at my search"},"references":[{"name":"ref_0","type":"index-pattern","id":"another-pattern-*"}]}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"},"references":[{"name":"ref_0","type":"visualization","id":"my-vis"}]}

The API returns the following:

{
  "success": true,
  "successCount": 3,
  "successResults": [
    {
      "id": "my-vis",
      "type": "visualization",
      "meta": {
        "icon": "visualizeApp",
        "title": "Look at my visualization"
      }
    },
    {
      "id": "my-search",
      "type": "search",
      "meta": {
        "icon": "searchApp",
        "title": "Look at my search"
      }
    },
    {
      "id": "my-dashboard",
      "type": "dashboard",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      }
    }
  ]
}

The result indicates a successful import, and all three objects were created.

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

« Import objects API Resolve object API »