[[saved-objects-api-import]] === Import objects API ++++ Import objects ++++ experimental[] Create sets of {kib} saved objects from a file created by the export API. ==== Compatibility across versions 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 {kib}. See the table below for compatibility examples: |======= | Exporting version | Importing version | Compatible? | 6.7.0 | 6.8.1 | Yes | 6.8.1 | 7.3.0 | Yes | 7.3.0 | 7.11.1 | Yes | 7.11.1 | 7.6.0 | No | 6.8.1 | 8.0.0 | No |======= [[saved-objects-api-import-request]] ==== Request `POST :/api/saved_objects/_import` `POST :/s//api/saved_objects/_import` [[saved-objects-api-import-path-params]] ==== Path parameters `space_id`:: (Optional, string) An identifier for the <>. If `space_id` is not provided in the URL, the default space is used. [[saved-objects-api-import-query-params]] ==== Query parameters `createNewCopies`:: (Optional, boolean) Creates copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict errors are avoided. + NOTE: 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. + NOTE: This cannot be used with the `createNewCopies` option. [[saved-objects-api-import-request-body]] ==== Request body The request body must include the multipart/form-data type. `file`:: A file exported using the export API. + NOTE: The <> configuration setting limits the number of saved objects which may be included in this file. Similarly, the <> setting limits the overall size of the file that can be imported. [[saved-objects-api-import-response-body]] ==== Response body `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. + NOTE: 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. + NOTE: 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 <>. [[saved-objects-api-import-codes]] ==== Response code `200`:: Indicates a successful call. [[saved-objects-api-import-example]] ==== Examples [[saved-objects-api-import-example-1]] ===== Successful import with `createNewCopies` enabled Import an index pattern and dashboard: [source,sh] -------------------------------------------------- $ curl -X POST api/saved_objects/_import?createNewCopies=true -H "kbn-xsrf: true" --form file=@file.ndjson -------------------------------------------------- // KIBANA The `file.ndjson` file contains the following: [source,sh] -------------------------------------------------- {"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: [source,sh] -------------------------------------------------- { "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. [[saved-objects-api-import-example-2]] ===== Successful import with `createNewCopies` disabled Import an index pattern and dashboard: [source,sh] -------------------------------------------------- $ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson -------------------------------------------------- // KIBANA The `file.ndjson` file contains the following: [source,sh] -------------------------------------------------- {"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: [source,sh] -------------------------------------------------- { "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. [[saved-objects-api-import-example-3]] ===== Failed import with conflict errors Import an index pattern, visualization, *Canvas* workpad, and dashboard that include saved objects: [source,sh] -------------------------------------------------- $ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson -------------------------------------------------- // 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": 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 index pattern, visualization, *Canvas* workpad, and dashboard resulted in a conflict error: * An index pattern 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 <> 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 <>. [[saved-objects-api-import-example-4]] ===== Failed import with missing reference errors Import a visualization and dashboard when the index pattern for the visualization doesn't exist: [source,sh] -------------------------------------------------- $ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson -------------------------------------------------- // 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"},{"name":"ref_1","type":"search","id":"my-search"}]} -------------------------------------------------- The API returns the following: [source,sh] -------------------------------------------------- { "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 <>.