Action connectors can be imported/exported with rules (#3021)

Co-authored-by: Joe Peeples <[email protected]>
(cherry picked from commit e79d882)

docs/detections/api/rules/rules-api-export.asciidoc

@@ -10,7 +10,9 @@ You cannot export prebuilt rules, but they are available at https://github.com/e
 
 [IMPORTANT]
 =================
-Although detection rule actions are included in the exported file, the connectors used by the actions are not included. Use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI in Kibana (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors _before_ you export and import the detection rules.
+Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) _is not_ included. You must re-add missing connector details after importing detection rules.
+
+You can use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors before importing detection rules.
 
 Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <<edit-value-lists, Import value lists>> UI (*Manage* -> *Rules* -> *Import value lists*) to export and import value lists separately.
 =================

docs/detections/api/rules/rules-api-import.asciidoc

@@ -8,11 +8,13 @@ Imports rules from an `.ndjson` file. The following configuration items are also
 
 NOTE: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
 
-NOTE: You need at least `Read` privileges for the `Action and Connectors` feature to import rules with actions. If you're importing rules without actions, `Action and Connectors` feature privileges are not required. Refer to <<enable-detections-ui>> for more information.
+NOTE: To import rules with actions, you need at least `Read` privileges for the `Action and Connectors` feature. To overwrite or add new connectors, you need `All` privileges for the `Actions and Connectors` feature. To import rules without actions,  you don't need `Actions and Connectors` privileges. Refer to <<enable-detections-ui>> for more information.
 
 [IMPORTANT]
 =================
-Although detection rule actions are included in the exported file, the connectors used by the actions are not included. Use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI in Kibana (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors _before_ you export and import the detection rules.
+Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) _is not_ included. You must re-add missing connector details after importing detection rules.
+
+You can use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) or the Saved Objects APIs (experimental) to {kibana-ref}/saved-objects-api-export.html[export] and {kibana-ref}/saved-objects-api-import.html[import] any necessary connectors before importing detection rules.
 
 Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the <<edit-value-lists, Import value lists>> UI (*Manage* -> *Rules* -> *Import value lists*) to export and import value lists separately.
 =================
@@ -48,6 +50,8 @@ curl -X POST "<KibanaURL>/api/detection_engine/rules/_import"
 |`overwrite_exceptions` |Boolean |Determines whether existing exception lists
 with the same `list_id` are overwritten. Both the exception list container and
 its items are overwritten. |No, defaults to `false`.
+|`overwrite_action_connectors` |Boolean |Determines whether existing actions with the same
+`kibana.alert.rule.actions.id` are overwritten. |No, defaults to `false`.
 |==============================================
 
 ===== Example request

docs/detections/rules-ui-manage.asciidoc

@@ -172,13 +172,15 @@ You cannot export Elastic prebuilt rules, but you can duplicate a prebuilt rule,
 If you try to export with both prebuilt and custom rules selected, only the custom rules are exported.
 ====
 
-The `.ndjson` file also includes any actions and exception lists related to the exported rules. However, other configuration items require additional handling when exporting and importing rules:
+The `.ndjson` file also includes any actions, connectors, and exception lists related to the exported rules. However, other configuration items require additional handling when exporting and importing rules:
 
 - *Data views*: For rules that use a {kib} data view as a data source, the exported file contains the associated `data_view_id`, but does _not_ include any other data view configuration. To export/import between {kib} spaces, first use the {kibana-ref}/managing-saved-objects.html#managing-saved-objects-share-to-space[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) to share the data view with the destination space.
 +
 To import into a different {stack} deployment, the destination cluster must include a data view with a matching data view ID (configured in the {kibana-ref}/data-views.html[data view's advanced settings]). Alternatively, after importing, you can manually reconfigure the rule to use an appropriate data view in the destination system.
 
-- *Actions and connectors*: Rule actions are included in the exported file, but the connectors used by the actions are _not_ included. Use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) to export and import any necessary connectors _before_ you export and import the detection rules.
+- *Actions and connectors*: Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) _is not_ included. You must re-add missing connector details after importing detection rules.
++
+TIP: You can also use {kib}'s {kibana-ref}/managing-saved-objects.html#managing-saved-objects-export-objects[Saved Objects] UI (*Stack Management* -> *Kibana* -> *Saved Objects*) to export and import necessary connectors before importing detection rules.
 
 - *Value lists*: Any value lists used for rule exceptions are _not_ included in rule exports or imports. Use the <<edit-value-lists, Import value lists>> UI (*Manage* -> *Rules* -> *Import value lists*) to export and import value lists separately.
 
@@ -190,16 +192,17 @@ To export and import detection rules:
 .. Select *Bulk actions* -> *Export*, then save the exported file.
 . To import rules:
 +
-NOTE: You need at least `Read` privileges for the `Action and Connectors` feature to import rules with actions. If you're importing rules without actions, `Action and Connectors` feature privileges are not required. Refer to <<enable-detections-ui>> for more information.
+NOTE: To import rules with actions, you need at least `Read` privileges for the `Action and Connectors` feature. To overwrite or add new connectors, you need `All` privileges for the `Actions and Connectors` feature. To import rules without actions,  you don't need `Actions and Connectors` privileges. Refer to <<enable-detections-ui>> for more information.
 
 .. Click *Import rules*.
 .. Drag and drop the file that contains the detection rules.
 +
 NOTE: Imported rules must be in an `.ndjson` file.
 .. (Optional) Select *Overwrite existing detection rules with conflicting "rule_id"* to update existing rules if they match the `rule_id` value of any rules in the import file. Configuration data included with the rules, such as actions, is also overwritten.
 .. (Optional) Select *Overwrite existing exception lists with conflicting "list_id"* to replace existing exception lists with exception lists from the import file if they have a matching `list_id` value.
+.. (Optional) Select *Overwrite existing connectors with conflicting action "id"* to update existing connectors if they match the `action id` value of any rule actions in the import file. Configuration data included with the actions is also overwritten.
 .. Click *Import rule*.
-
+.. (Optional) If a connector is missing sensitive information after the import, a warning displays and you're prompted to fix the connector. In the warning, click *Go to connector*. On the Connectors page, find the connector that needs to be updated, click *Fix*, then add the necessary details.  
 
 [float]
 [[enable-detection-rules]]

docs/getting-started/detections-req.asciidoc

@@ -108,7 +108,7 @@ a| {kib} space `All` privileges for the `Security` feature (refer to
 
 * To provide full access to rule actions and connectors, give your role `All` privileges. With `Read` privileges, you can edit rule actions, but will have limited capabilities to manage connectors. For example, `Read` privileges allow you to add or remove an existing connector from a rule, but does not allow you to create a new connector.
 
-* To import rules with actions and connectors, your role needs at least `Read` privileges. To import rules without actions or connectors, your role does not require `Action and Connectors` feature privileges.
+* To import rules with actions, you need at least `Read` privileges for the `Action and Connectors` feature. To overwrite or add new connectors, you need `All` privileges for the `Actions and Connectors` feature. To import rules without actions,  you don't need `Actions and Connectors` privileges. 
 
 |Manage alerts