IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Import objects API Rotate encryption key API »

› › ›

Resolve import errors API

edit

Resolve import errors 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. 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

Request

edit

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

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

Path parameters

edit

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

Query parameters

edit

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.
compatibilityMode: (Optional, boolean) Applies various adjustments to the saved objects that are being imported to maintain compatibility between different Kibana versions. When enabled during the initial import, also enable when resolving import errors.

This option cannot be used with the createNewCopies option.

Request body

edit

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 body

edit

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 code

edit

200: Indicates a successful call.

Examples

edit

Resolve conflict errors

edit

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

Resolve conflict errors for a data view, 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 errors

edit

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

Resolve a missing reference error for a visualization by replacing the data view 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.

« Import objects API Rotate encryption key API »