kibana/docs/api/saved-objects/resolve_import_errors.asciidoc

[[saved-objects-api-resolve-import-errors]]
=== Resolve import errors API
++++
<titleabbrev>Resolve import errors</titleabbrev>
++++

experimental[] Resolve errors from the <<saved-objects-api-import,Import objects API>>.

To resolve errors, you can:

* Retry certain saved objects

* Overwrite specific saved objects

* Change references to different saved objects

[[saved-objects-api-resolve-import-errors-request]]
==== Request

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

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

[[saved-objects-api-resolve-import-errors-path-params]]
==== Path parameters

`space_id`::
  (Optional, string) An identifier for the <<xpack-spaces,space>>. When `space_id` is unspecified in the URL, the default space is used.

[[saved-objects-api-resolve-import-errors-query-params]]
==== Query parameters

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

[[saved-objects-api-resolve-import-errors-request-body]]
==== Request body

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>`
[%collapsible%open]
=====
    `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.
=====

[[saved-objects-api-resolve-import-errors-response-body]]
==== Response body

`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.
+
NOTE: 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.
+
NOTE: Objects are only created when all resolvable errors are addressed, including conflict and missing references. To resolve errors, refer
to the <<saved-objects-api-resolve-import-errors-example, examples>>.

[[saved-objects-api-resolve-import-errors-codes]]
==== Response code

`200`::
    Indicates a successful call.

[[saved-objects-api-resolve-import-errors-example]]
==== Examples

[[saved-objects-api-resolve-import-errors-example-1]]
===== Resolve conflict errors

This example builds upon the <<saved-objects-api-import-example-3,Import objects API example with conflict errors>>.

Resolve conflict errors for {a-data-source}, visualization, and *Canvas* workpad by overwriting the existing saved objects:

[source,sh]
--------------------------------------------------
$ 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"}]'
--------------------------------------------------
// KIBANA

The `file.ndjson` file contains the following:

[source,sh]
--------------------------------------------------
{"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:

[source,sh]
--------------------------------------------------
{
  "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.

TIP: 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.

[[saved-objects-api-resolve-import-errors-example-2]]
===== Resolve missing reference errors

This example builds upon the <<saved-objects-api-import-example-4,Import objects API example with missing reference errors>>.

Resolve a missing reference error for a visualization by replacing the {data-source} with another, and resolve a missing reference error for
a search by ignoring it:

[source,sh]
--------------------------------------------------
$ 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"}]'
--------------------------------------------------
// KIBANA

The `file.ndjson` file contains the following:

[source,sh]
--------------------------------------------------
{"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:

[source,sh]
--------------------------------------------------
{
  "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.

TIP: 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.