Rename resolve import conflicts API to resolve import errors (#33024)

docs/api/saved-objects/resolve_import_errors.asciidoc

@@ -0,0 +1,104 @@
+[[saved-objects-api-resolve-import-errors]]
+=== Resolve Import Errors
+
+experimental[This functionality is *experimental* and may be changed or removed completely in a future release.]
+
+The resolve import errors API enables you to resolve errors given by the import API by either overwriting specific saved objects or changing references to a newly created object.
+
+Note: You cannot access this endpoint via the Console in Kibana.
+
+==== Request
+
+`POST /api/saved_objects/_resolve_import_errors`
+
+==== Request body
+
+The request body must be of type multipart/form-data.
+
+`file`::
+  (ndjson) The same new line delimited JSON objects given to the import API.
+
+`overwrites` (optional)::
+  (array) A list of `type` and `id` objects allowed to be overwritten on import.
+
+`replaceReferences` (optional)::
+  (array) A list of `type`, `from` and `to` used to change imported saved object references to.
+
+`skips` (optional)::
+  (array) A list of `type` and `id` objects to skip importing.
+
+==== Response body
+
+The response body will have a top level `success` property that indicates
+if the import was successful or not as well as a `successCount` indicating how many records are successfully resolved.
+In the scenario the import wasn't successful a top level `errors` array will contain the objects that failed to import.
+
+==== Examples
+
+The following example resolves errors for an index pattern and dashboard but indicates to skip the index pattern.
+This will cause the index pattern to not be in the system and the dashboard to overwrite the existing saved object.
+
+[source,js]
+--------------------------------------------------
+POST api/saved_objects/_resolve_import_errors
+Content-Type: multipart/form-data; boundary=EXAMPLE
+--EXAMPLE
+Content-Disposition: form-data; name="file"; filename="export.ndjson"
+Content-Type: application/ndjson
+
+{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
+{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}
+--EXAMPLE
+Content-Disposition: form-data; name="skips"
+
+[{"type":"index-pattern","id":"my-pattern"}]
+--EXAMPLE
+Content-Disposition: form-data; name="overwrites"
+
+[{"type":"dashboard","id":"my-dashboard"}]
+--EXAMPLE--
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200` and a response body
+containing a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "success": true,
+  "successCount": 1
+}
+--------------------------------------------------
+
+The following example resolves errors for a visualization and dashboard but indicates
+to replace the dashboard references to another visualization.
+
+[source,js]
+--------------------------------------------------
+POST api/saved_objects/_resolve_import_errors
+Content-Type: multipart/form-data; boundary=EXAMPLE
+--EXAMPLE
+Content-Disposition: form-data; name="file"; filename="export.ndjson"
+Content-Type: application/ndjson
+
+{"type":"visualization","id":"my-vis","attributes":{"title":"Look at my visualization"}}
+{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"},"references":[{"name":"panel_0","type":"visualization","id":"my-vis"}]}
+--EXAMPLE
+Content-Disposition: form-data; name="replaceReferences"
+
+[{"type":"visualization","from":"my-vis","to":"my-vis-2"}]
+--EXAMPLE--
+--------------------------------------------------
+// KIBANA
+
+A successful call returns a response code of `200` and a response body
+containing a JSON structure similar to the following example:
+
+[source,js]
+--------------------------------------------------
+{
+  "success": true,
+  "successCount": 1
+}
+--------------------------------------------------