[DOCS] Clarify Opsgenie and PagerDuty connector actions (#163548)

docs/management/action-types.asciidoc

@@ -27,9 +27,9 @@ a| <<teams-action-type,Microsoft Teams>>
 
 | Send a message to a Microsoft Teams channel.
 
-a| <<opsgenie-action-type,Opsgenie>>
+a| <<opsgenie-action-type,{opsgenie}>>
 
-| Create or close an alert in Opsgenie.
+| Create or close an alert in {opsgenie}.
 
 a| <<pagerduty-action-type,PagerDuty>>
 

docs/management/connectors/action-types/opsgenie.asciidoc

@@ -3,8 +3,16 @@
 ++++
 <titleabbrev>Opsgenie</titleabbrev>
 ++++
+:frontmatter-description: Add a connector that can create and close alerts in {opsgenie}.
+:frontmatter-tags-products: [alerting]
+:frontmatter-tags-content-type: [how-to]
+:frontmatter-tags-user-goals: [configure]
 
-The Opsgenie connector uses the https://docs.opsgenie.com/docs/alert-api[Opsgenie alert API].
+An {opsgenie} connector enables you to create and close alerts in {opsgenie}.
+In particular, it uses the https://docs.opsgenie.com/docs/alert-api[{opsgenie} alert API].
+
+To create this connector, you must have a valid {opsgenie} URL and API key.
+For configuration tips, refer to <<configuring-opsgenie>>.
 
 [float]
 [[define-opsgenie-ui]]
@@ -27,28 +35,28 @@ Name:: The name of the connector. The name is used to identify a connector in th
 URL:: The Opsgenie URL. For example, https://api.opsgenie.com or https://api.eu.opsgenie.com.
 +
 NOTE: If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
-API Key::   The Opsgenie API authentication key for HTTP Basic authentication. For more details about generating Opsgenie API keys, refer to https://support.atlassian.com/opsgenie/docs/create-a-default-api-integration/[Opsgenie documentation].
+
+API Key:: The Opsgenie API authentication key for HTTP basic authentication. For more details about generating Opsgenie API keys, refer to https://support.atlassian.com/opsgenie/docs/create-a-default-api-integration/[Opsgenie documentation].
 
 [float]
 [[opsgenie-action-configuration]]
 === Test connectors
 
-You can test connectors with the <<execute-connector-api,run connector API>> or
-as you're creating or editing the connector in {kib}. For example:
+After you create a connector, use the *Test* tab to test its actions:
 
-[role="screenshot"]
-image::management/connectors/images/opsgenie-params-test.png[Opsgenie params test]
-// NOTE: This is an autogenerated screenshot. Do not edit it directly.
-
-The Opsgenie connector supports two types of actions: Create alert and Close alert. The properties supported for each action are different because Opsgenie defines different properties for each operation.
-
-When testing the Opsgenie connector, choose the appropriate action from the selector. Each action has different properties that can be configured.
-
-Action:: Select *Create alert* to configure the actions that occur when a rule's conditions are met. Select *Close alert* to define the recovery actions that occur when a rule's conditions are no longer met.
+* <<opsgenie-action-create-alert-configuration,Create alert>>
+* <<opsgenie-action-close-alert-configuration,Close alert>>
 
 [float]
 [[opsgenie-action-create-alert-configuration]]
-==== Configure the create alert action
+==== Create alert action
+
+When you create a rule that uses an {opsgenie} connector, its actions (with the exception of recovery actions) create {opsgenie} alerts.
+You can test this type of action when you create or edit your connector:
+
+[role="screenshot"]
+image::management/connectors/images/opsgenie-create-alert-test.png[{opsgenie} create alert action test]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
 You can configure the create alert action through the form view or using a JSON editor.
 
@@ -115,7 +123,14 @@ Example JSON editor contents
 
 [float]
 [[opsgenie-action-close-alert-configuration]]
-==== Close alert configuration
+==== Close alert action
+
+When you create a rule that uses an {opsgenie} connector, its recovery actions close {opsgenie} alerts.
+You can test this type of action when you create or edit your connector:
+
+[role="screenshot"]
+image::management/connectors/images/opsgenie-close-alert-test.png[{opsgenie} close alert action test]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
 The close alert action has the following configuration properties.
 

docs/management/connectors/action-types/pagerduty.asciidoc

@@ -8,7 +8,11 @@
 :frontmatter-tags-content-type: [how-to] 
 :frontmatter-tags-user-goals: [configure]
 
-The PagerDuty connector uses the https://v2.developer.pagerduty.com/docs/events-api-v2[v2 Events API] to trigger, acknowledge, and resolve PagerDuty alerts.
+The PagerDuty connector enables you to trigger, acknowledge, and resolve PagerDuty alerts.
+In particular, it uses the https://v2.developer.pagerduty.com/docs/events-api-v2[v2 Events API].
+
+To create this connector, you must have a valid PagerDuty integration key.
+For configuration tips, refer to <<configuring-opsgenie>>
 
 [float]
 [[define-pagerduty-ui]]
@@ -35,24 +39,58 @@ Integration Key::   A 32 character PagerDuty Integration Key for an integration
 [[pagerduty-action-configuration]]
 === Test connectors
 
-You can test connectors with the <<execute-connector-api,run connector API>> or
-as you're creating or editing the connector in {kib}. For example:
+After you create a connector, use the *Test* tab to test its actions:
+
+* <<pagerduty-action-resolve,Acknowledge>>
+* <<pagerduty-action-resolve,Resolve>>
+* <<pagerduty-action-trigger,Trigger>>
+
+When you create a rule that uses a PagerDuty connector, you can use any of these types of actions.
+Rule recovery actions also support all types.
+
+[float]
+[[pagerduty-action-acknowledge]]
+==== Acknowledge action
+
+When you test the acknowlege action, you must provide the de-duplication key for a PagerDuty alert:
 
 [role="screenshot"]
-image::management/connectors/images/pagerduty-params-test.png[PagerDuty params test]
+image::management/connectors/images/pagerduty-acknowledge-test.png[PagerDuty params test]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
-PagerDuty actions have the following properties.
+[float]
+[[pagerduty-action-resolve]]
+==== Resolve action
+
+Likewise when you test the resolve action, you must provide the de-duplication key:
+
+[role="screenshot"]
+image::management/connectors/images/pagerduty-resolve-test.png[PagerDuty params test]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+[float]
+[[pagerduty-action-trigger]]
+==== Trigger action
+
+When you test the trigger action, you must provide a summary for the PagerDuty alert:
+
+[role="screenshot"]
+image::management/connectors/images/pagerduty-trigger-test.png[PagerDuty params test]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+This action has the following properties:
 
 Severity::      The perceived severity of on the affected system. This can be one of `Critical`, `Error`, `Warning` or `Info`(default).
 Event action::  One of `Trigger` (default), `Resolve`, or `Acknowledge`. See https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[event action] for more details.
-Dedup Key::     All actions sharing this key will be associated with the same PagerDuty alert. This value is used to correlate trigger and resolution. This value is *optional*, and if not set, defaults to `<rule ID>:<alert ID>`. The maximum length is *255* characters. See https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication[alert deduplication] for details. 
-Timestamp::     An *optional* https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format date-time], indicating the time the event was detected or generated.
-Component::     An *optional* value indicating the component of the source machine that is responsible for the event, for example `mysql` or `eth0`.
-Group::         An *optional* value indicating the logical grouping of components of a service, for example `app-stack`.
-Source::        An *optional* value indicating the affected system, preferably a hostname or fully qualified domain name. Defaults to the {kib} saved object id of the action.
-Summary::       An *optional* text summary of the event, defaults to `No summary provided`. The maximum length is 1024 characters.
-Class::         An *optional* value indicating the class/type of the event, for example `ping failure` or `cpu load`.
+Dedup Key::     All actions sharing this key will be associated with the same PagerDuty alert. This value is used to correlate trigger and resolution. This value is optional, and if not set, defaults to `<rule ID>:<alert ID>`. The maximum length is 255 characters. See https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication[alert deduplication] for details.
++
+By default, when you create rules that use the PagerDuty connector, the de-duplication key is used to create a new PagerDuty incident for each alert and reuse the incident when a recovered alert reactivates.
+Timestamp::     An optional https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format date-time], indicating the time the event was detected or generated.
+Component::     An optional value indicating the component of the source machine that is responsible for the event, for example `mysql` or `eth0`.
+Group::         An optional value indicating the logical grouping of components of a service, for example `app-stack`.
+Source::        An optional value indicating the affected system, preferably a hostname or fully qualified domain name. Defaults to the {kib} saved object id of the action.
+Summary::       An optional text summary of the event, defaults to `No summary provided`. The maximum length is 1024 characters.
+Class::         An optional value indicating the class/type of the event, for example `ping failure` or `cpu load`.
 
 For more details on these properties, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty v2 event parameters].
 
@@ -62,7 +100,6 @@ For more details on these properties, see https://v2.developer.pagerduty.com/v2/
 
 Use the <<action-settings, Action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.
 
-
 [float]
 [[pagerduty-benefits]]
 === Configure PagerDuty
@@ -70,22 +107,11 @@ Use the <<action-settings, Action configuration settings>> to customize connecto
 By integrating PagerDuty with rules, you can:
 
 * Route your rules to the right PagerDuty responder within your team, based on your structure, escalation policies, and workflows.
-* Automatically generate incidents of different types and severity based on each rule’s context.
-* Tailor the incident data to match your needs by easily passing the rule context from Kibana to PagerDuty.
-
-[float]
-[[pagerduty-support]]
-=== Support
-If you need help with this integration, get in touch with the {kib} team by visiting
-https://support.elastic.co[support.elastic.co] or by using the *Ask Elastic* option in the {kib} Help menu.
-You can also select the {kib} category at https://discuss.elastic.co/[discuss.elastic.co].
-
-[float]
-[[pagerduty-integration-walkthrough]]
-=== Integration with PagerDuty walkthrough
+* Automatically generate incidents of different types and severity based on each rule's context.
+* Tailor the incident data to match your needs by easily passing the rule context from {kib} to PagerDuty.
 
 [[pagerduty-in-pagerduty]]
-*In PagerDuty*
+To set up PagerDuty:
 
 . From the *Configuration* menu, select *Services*.
 . Add an integration to a service:
@@ -96,8 +122,8 @@ Then, select the *Integrations* tab and click the *New Integration* button.
 * If you are creating a new service for your integration,
 go to
 https://support.pagerduty.com/docs/services-and-integrations#section-configuring-services-and-integrations[Configuring Services and Integrations]
-and follow the steps outlined in the *Create a New Service* section, selecting *Elastic Alerts* as the *Integration Type* in step 4.
-Continue with the <<pagerduty-in-elastic, In Elastic>> section once you have finished these steps.
+and follow the steps outlined in the *Create a New Service* section, selecting *Elastic Alerts* as the *Integration Type*.
+Continue with the connector creation in {kib} after you have finished these steps.
 
 . Enter an *Integration Name* in the format Elastic-service-name (for example, Elastic-Alerting or Kibana-APM-Alerting)
 and select *Elastic Alerts* from the *Integration Type* menu.
@@ -108,33 +134,4 @@ You will be redirected to the *Integrations* tab for your service. An Integratio
 [role="screenshot"]
 image::images/pagerduty-integration.png[PagerDuty Integrations tab]
 
-. Save this key, as you will use it when you configure the integration with Elastic in the next section.
-
-[[pagerduty-in-elastic]]
-*In Elastic*
-
-. Create a PagerDuty connector in Kibana.  You can:
-+
-* Create a connector as part of creating an rule by selecting PagerDuty in the *Actions*
-section of the rule configuration and selecting *Add new*.
-* Alternatively, create a connector. To create a connector, go to *{stack-manage-app} > {connectors-ui}*, click *Create connector*, then select the PagerDuty option.
-
-. Configure the connector by giving it a name and entering the Integration Key, optionally entering a custom API URL.
-+
-See <<pagerduty-in-pagerduty,In PagerDuty>> for how to obtain the endpoint and key information from PagerDuty and
-<<pagerduty-connector-configuration,Connector configuration>> for more details.
-
-. Save the connector.
-
-. To create a rule, go to *{stack-manage-app} > {rules-ui}* or the application of your choice.
-
-. Set up an action using your PagerDuty connector, by determining:
-+
-* The action's type: Trigger, Resolve, or Acknowledge.
-* The event's severity: Info, warning, error, or critical.
-* An array of different fields, including the timestamp, group, class, component, and your dedup key. By default, the dedup is configured to create a new PagerDuty incident for each alert and reuse the incident when a recovered alert reactivates.
-Depending on your custom needs, assign them variables from the rule context.
-To see the available context variables, click on the *Add variable* icon next
-to each corresponding field. For more details on these parameters, see the
-<<pagerduty-action-configuration,Actions configuration>> and the PagerDuty
-https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[API v2 documentation].
+. Save this key for use when you configure the connector in {kib}.

docs/user/alerting/create-and-manage-rules.asciidoc

@@ -94,7 +94,8 @@ For example, you can set *Run when* to `Query matched` or `Recovered` for the {e
 image::images/es-query-rule-recovery-action.png[UI for defining a recovery action,500]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
-Each connector enables different action properties. For example, an email connector enables you to set the recipients, the subject, and a message body in markdown format. For more information about connectors, refer to <<action-types>>.
+Each connector supports a specific set of actions for each action group and enables different action properties.
+For example, you can have actions that create an {opsgenie} alert when rule conditions are met and recovery actions that close the {opsgenie} alert. For more information about connectors, refer to <<action-types>>.
 
 [[alerting-concepts-suppressing-duplicate-notifications]]
 [TIP]

docs/user/alerting/rule-types/es-query.asciidoc

@@ -72,6 +72,9 @@ For example:
 image::images/es-query-rule-action-query-matched.png[UI for defining a recovery action]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
+Each connector supports a specific set of actions for each action group.
+For more details, refer to <<action-types>>.
+
 [float]
 === Add action variables
 

docs/user/alerting/rule-types/index-threshold.asciidoc

@@ -9,7 +9,7 @@
 The index threshold rule type runs an {es} query. It aggregates field values from documents, compares them to threshold values, and schedules actions to run when the thresholds are met.
 
 [float]
-=== Rule conditions
+=== Define the conditions
 
 [role="screenshot"]
 image::user/alerting/images/rule-types-index-threshold-conditions.png[Defining index threshold rule conditions in {kib}]
@@ -28,10 +28,23 @@ It also defines a time window, which determines how far back to search for docum
 If data is available and all clauses have been defined, a preview chart will render the threshold value and display a line chart showing the value for the last 30 intervals. This can provide an indication of recent values and their proximity to the threshold, and help you tune the clauses.
 
 [float]
-[[action-variables-index-threshold]]
-=== Action variables
+[[actions-index-threshold]]
+=== Add actions
 
-The following action variables are specific to the index threshold rule. You can also specify <<rule-action-variables,variables common to all rules>>.
+You can <<defining-rules-actions-details,add actions>> to your rule to generate notifications.
+
+Each action uses a connector, which provides connection information for a {kib} service or third party integration, depending on where you want to send the notifications.
+
+After you choose a connector, you must choose an action group, which affects when the action runs.
+The valid action groups for an index threshold rule are: `Threshold met` and `Recovered`.
+Each connector supports a specific set of actions for each action group. For more details, refer to <<action-types>>.
+
+[float]
+[[action-variables-index-threshold]]
+=== Add action variables
+
+The following action variables are specific to the index threshold rule.
+You can also specify <<rule-action-variables,variables common to all rules>>.
 
 `context.conditions`:: A description of the threshold condition. Example: `count greater than 4`
 `context.date`:: The date, in ISO format, that the rule met the threshold condition. Example: `2020-01-01T00:00:00.000Z`.

x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/opsgenie_connector.ts

@@ -29,7 +29,10 @@ export default function ({ getService, getPageObjects }: FtrProviderContext) {
       await commonScreenshots.takeScreenshot('opsgenie-connector', screenshotDirectories);
       await testSubjects.click('create-connector-flyout-save-test-btn');
       await testSubjects.click('toastCloseButton');
-      await commonScreenshots.takeScreenshot('opsgenie-params-test', screenshotDirectories);
+      await commonScreenshots.takeScreenshot('opsgenie-create-alert-test', screenshotDirectories);
+      await testSubjects.click('opsgenie-subActionSelect-close-alert');
+      await testSubjects.click('opsgenie-display-more-options');
+      await commonScreenshots.takeScreenshot('opsgenie-close-alert-test', screenshotDirectories);
       await testSubjects.click('euiFlyoutCloseButton');
     });
   });

x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/pagerduty_connector.ts

@@ -30,7 +30,11 @@ export default function ({ getService, getPageObjects }: FtrProviderContext) {
       await testSubjects.click('create-connector-flyout-save-test-btn');
       await testSubjects.click('toastCloseButton');
       await testSubjects.setValue('eventActionSelect', 'trigger');
-      await commonScreenshots.takeScreenshot('pagerduty-params-test', screenshotDirectories);
+      await commonScreenshots.takeScreenshot('pagerduty-trigger-test', screenshotDirectories);
+      await testSubjects.setValue('eventActionSelect', 'resolve');
+      await commonScreenshots.takeScreenshot('pagerduty-resolve-test', screenshotDirectories);
+      await testSubjects.setValue('eventActionSelect', 'acknowledge');
+      await commonScreenshots.takeScreenshot('pagerduty-acknowledge-test', screenshotDirectories);
       await testSubjects.click('euiFlyoutCloseButton');
     });
   });