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

« Export objects API Resolve import errors API »

› › ›

Import objects API

edit

Import objects 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. Create sets of Kibana saved objects from a file created by the export API.

Compatibility across versions

edit

Saved objects can only be imported into the same version, a newer minor on the same major, or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of Kibana. See the table below for compatibility examples:

Exporting version	Importing version	Compatible?
6.7.x	6.8.x	Yes
6.x.x	7.x.x	Yes
7.x.x	8.x.x	Yes
7.1.x	7.15.x	Yes
7.x.x	6.x.x	No
7.15.x	7.1.x	No
6.x.x	8.x.x	No

Request

edit

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

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

Path parameters

edit

space_id: (Optional, string) An identifier for the space. If space_id is not provided in the URL, the default space is used.

Query parameters

edit

createNewCopies: (Optional, boolean) Creates copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict errors are avoided.

This cannot be used with the overwrite option.
overwrite: (Optional, boolean) Overwrites saved objects when they already exist. When used, potential conflict errors are automatically resolved by overwriting the destination object.

This cannot be used with the createNewCopies option.

Request body

edit

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

file: A file exported using the export API.

The savedObjects.maxImportExportSize configuration setting limits the number of saved objects which may be included in this file. Similarly, the savedObjects.maxImportPayloadBytes setting limits the overall size of the file that can be imported.

Response body

edit

success: (boolean) Indicates when the import was successfully completed. 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 imported records.
errors: (Optional, array) Indicates the import was unsuccessful and specifies the objects that failed to import.

One object may result in multiple errors, which requires separate steps to resolve. For instance, a missing_references error and 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 conflicts and missing references. For information on how to resolve errors, refer to the examples.

Response code

edit

200: Indicates a successful call.

Examples

edit

Successful import with `createNewCopies` enabled

edit

Import a data view and dashboard:

$ curl -X POST api/saved_objects/_import?createNewCopies=true -H "kbn-xsrf: true" --form file=@file.ndjson

The file.ndjson file contains the following:

{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}

The API returns the following:

{
  "success": true,
  "successCount": 2,
  "successResults": [
    {
      "id": "my-pattern",
      "type": "index-pattern",
      "destinationId": "4aba3770-0d04-45e1-9e34-4cf0fd2165ae",
      "meta": {
        "icon": "indexPatternApp",
        "title": "my-pattern-*"
      }
    },
    {
      "id": "my-dashboard",
      "type": "dashboard",
      "destinationId": "c31d1eca-9bc0-4a81-b5f9-30c442824c48",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      }
    }
  ]
}

The result indicates a successful import, and both objects are created. Since these objects are created as new copies, each entry in the successResults array includes a destinationId attribute.

Successful import with `createNewCopies` disabled

edit

Import a data view and dashboard:

$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson

The file.ndjson file contains the following:

{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}

The API returns the following:

{
  "success": true,
  "successCount": 2,
  "successResults": [
    {
      "id": "my-pattern",
      "type": "index-pattern",
      "meta": {
        "icon": "indexPatternApp",
        "title": "my-pattern-*"
      }
    },
    {
      "id": "my-dashboard",
      "type": "dashboard",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      }
    }
  ]
}

The result indicates a successful import, and both objects are created.

Failed import with conflict errors

edit

Import a data view, visualization, Canvas workpad, and dashboard that include saved objects:

$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson

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": 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 an unsuccessful import because the data view, visualization, Canvas workpad, and dashboard resulted in a conflict error:

A data view 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 exported and then imported 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 exported, imported 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 import errors API.

Failed import with missing reference errors

edit

Import a visualization and dashboard when the data view for the visualization doesn’t exist:

$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson

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"},{"name":"ref_1","type":"search","id":"my-search"}]}

The API returns the following:

{
  "success": false,
  "successCount": 1,
  "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"
      }
    },
    {
      "id": "my-search",
      "type": "search",
      "title": "Look at my search",
      "error": {
        "type": "missing_references",
        "references": [
          {
            "type": "index-pattern",
            "id": "another-pattern-*"
          }
        ]
      },
      "meta": {
        "icon": "searchApp",
        "title": "Look at my search"
      }
    }
  ],
  "successResults": [
    {
      "id": "my-dashboard",
      "type": "dashboard",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      }
    }
  ]
}

The result indicates an unsuccessful import because the visualization and search resulted in a missing references error.

Objects are created when the errors are resolved using the Resolve import errors API.

« Export objects API Resolve import errors API »

Import objects API

Import objects API

Compatibility across versions

Request

Path parameters

Query parameters

Request body

Response body

Response code

Examples

Successful import with createNewCopies enabled

Successful import with createNewCopies disabled

Failed import with conflict errors

Failed import with missing reference errors

Successful import with `createNewCopies` enabled

Successful import with `createNewCopies` disabled