[Alerting][Docs] Adding template for documenting alert and action typ…

…es (elastic#92830) * Alert type template * Action type template * Cleanup * Cleanup * Removing callout list * Cleanup * Apply suggestions from code review Co-authored-by: gchaps <[email protected]> * Adding title to actions page * PR fixes * PR fixes * PR fixes * PR fixes Co-authored-by: Kibana Machine <[email protected]> Co-authored-by: gchaps <[email protected]>
ymao1 · Mar 2, 2021 · 13a0a4d · 13a0a4d
1 parent a4011ba
commit 13a0a4d
Show file tree

Hide file tree

Showing 19 changed files with 335 additions and 377 deletions.
diff --git a/docs/action-type-template.asciidoc b/docs/action-type-template.asciidoc
@@ -0,0 +1,73 @@
+[[<ACTION-TYPE>-action-type]]
+=== <ACTION-TYPE> action
+++++
+<titleabbrev><ACTION-TYPE></titleabbrev>
+++++
+
+Include a short description of the action type.
+
+[float]
+[[<ACTION-TYPE>-connector-configuration]]
+==== Connector configuration
+
+<ACTION-TYPE> connectors have the following configuration properties.
+
+////
+List of user-facing connector configurations. This should align with the fields available in the Create connector flyout form for this action type.
+////
+
+Property1:: A short description of this property.
+Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
+
+[float]
+[[Preconfigured-<ACTION-TYPE>-configuration]]
+==== Preconfigured action type
+
+////
+Example preconfigured format for this action type
+////
+
+[source,text]
+--
+ my-<ACTION-TYPE>:
+   name: preconfigured-<ACTION-TYPE>-action-type
+   actionTypeId: .<ACTION-TYPE>
+   config:
+     property1: value1
+     property2: value2
+   secrets:
+     property3: value3
+--
+
+[float]
+[[<ACTION-TYPE>-connector-config-properties]]
+////
+List of properties from the ConfigSchema and SecretsSchema for this action type.
+////
+Config defines information for the action type.
+
+`property1`:: A short description of this property.
+`property2`:: A short descriptionn of this property.
+
+Secrets defines sensitive information for the action type.
+
+`property3`:: A short descriptionn of this property.
+
+[float]
+[[<ACTION-TYPE>-action-configuration]]
+==== Action configuration
+
+<ACTION-TYPE> actions have the following configuration properties.
+
+////
+List of user-facing action configurations. This should align with the fields available in the Action section of the Create/Update alert flyout.
+////
+
+Property1:: A short description of this property.
+Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
+
+////
+Optional - additional configuration details here
+[[configuring-<ACTION-TYPE>]]
+==== Configure <ACTION-TYPE>
+////
diff --git a/docs/alert-type-template.asciidoc b/docs/alert-type-template.asciidoc
@@ -0,0 +1,39 @@
+[[alert-type-<ALERT TYPE>]]
+=== <ALERT TYPE>
+
+Include a short description of the alert type.
+
+[float]
+==== Create the alert
+
+Fill in the <<defining-alerts-general-details, alert details>>, then select *<ALERT TYPE>*.
+
+[float]
+==== Define the conditions
+
+Define properties to detect the condition.
+
+////
+Optional, include a screenshot
+[role="screenshot"]
+image::user/alerting/images/alert-types-<ALERT TYPE>-conditions.png[Conditions for <ALERT TYPE> alert type]
+////
+
+Condition1:: This is a condition the user must define.
+Condition2:: This is another condition the user must define.
+
+[float]
+==== Add action variables
+
+<<defining-alerts-actions-details, Add an action>> to run when the alert condition is met. The following variables are specific to the <ALERT TYPE> alert. You can also specify <<defining-alerts-actions-variables, variables common to all alerts>>.
+
+`context.variableA`:: A short description of the context variable defined by the alert type.
+`context.variableB`:: A short description of the context variable defined by the alert type with an example. Example: `this is what variableB outputs`.
+
+////
+Optional, include a step-by-step example for creating this alert 
+[float]
+==== Example
+
+In this section, you will use the {kib} <<add-sample-data, weblog sample dataset>> to setup and tune the conditions on an <ALERT TYPE> alert. For this example, we want to detect when <DESCRIBE THE CONDITIONS>.
+////
diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc
@@ -1,6 +1,9 @@
 [role="xpack"]
 [[email-action-type]]
 === Email action
+++++
+<titleabbrev>Email</titleabbrev>
+++++
 
 The email action type uses the SMTP protocol to send mail message, using an integration of https://nodemailer.com/[Nodemailer]. Email message text is sent as both plain text and html text.
 
@@ -10,14 +13,15 @@ NOTE: For emails to have a footer with a link back to {kib}, set the <<server-pu
 [[email-connector-configuration]]
 ==== Connector configuration
 
-Email connectors have the following configuration properties:
+Email connectors have the following configuration properties.
 
 Name::      The name of the connector. The name is used to identify a  connector in the management UI connector listing, or in the connector list when configuring an action.
 Sender::    The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human name <user@host-name>"` format. See the https://nodemailer.com/message/addresses/[Nodemailer address documentation] for more information.
 Host::      Host name of the service provider. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure this hostname is added to the allowed hosts.
 Port::      The port to connect to on the service provider.
 Secure::    If true, the connection will use TLS when connecting to the service provider. Refer to the https://nodemailer.com/smtp/#tls-options[Nodemailer TLS documentation] for more information.  If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command.
-User::  Username for login type authentication.
+Require authentication:: If true, a username and password for login type authentication must be provided.
+Username::  Username for login type authentication.
 Password::  Password for login type authentication.
 
 [float]
@@ -39,56 +43,33 @@ Password::  Password for login type authentication.
      password: passwordkeystorevalue
 --
 
-[[email-connector-config-properties]]
-**`config`** defines the action type specific to the configuration and contains the following properties:
+Config defines information for the action type.
 
-[cols="2*<"]
-|===
+`service`:: The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the https://nodemailer.com/usage/using-gmail/[Nodemailer Gmail documentation].
+`from`:: An email address that corresponds to *Sender*.
+`host`:: A string that corresponds to *Host*.
+`port`:: A number that corresponds to *Port*.
+`secure`:: A boolean that corresponds to *Secure*.
+`hasAuth`:: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
 
-| `service`
-| The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the (https://nodemailer.com/usage/using-gmail/)[Nodemailer Gmail documentation].
+Secrets defines sensitive information for the action type.
 
-| `from`
-| An email address that corresponds to *Sender*.
+`user`:: A string that corresponds to *Username*. Required if `hasAuth` is set to `true`.
+`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
 
-| `host`
-| A string that corresponds to *Host*.
-
-| `port`
-| A number that corresponds to *Port*.
-
-| `secure`
-| A boolean that corresponds to *Secure*.
-
-| `hasAuth`
-| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
-
-|===
-
-**`secrets`** defines sensitive information for the action type and contains the following properties:
-
-[cols="2*<"]
-|===
-
-| `user`
-| A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
-
-| `password`
-| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
-
-|===
 
+[float]
 [[email-action-configuration]]
 ==== Action configuration
 
-Email actions have the following configuration properties:
+Email actions have the following configuration properties.
 
-To, CC, BCC::    Each is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name <user@host-name>` format. One of To, CC, or BCC must contain an entry.
+To, CC, BCC::    Each item is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name <user@host-name>` format. One of To, CC, or BCC must contain an entry.
 Subject::       The subject line of the email.
 Message::       The message text of the email. Markdown format is supported.
 
 [[configuring-email]]
-==== Configuring email accounts
+==== Configuring email accounts for well-known services
 
 The email action can send email using many popular SMTP email services.
 

diff --git a/docs/user/alerting/action-types/index.asciidoc b/docs/user/alerting/action-types/index.asciidoc
@@ -1,14 +1,17 @@
 [role="xpack"]
 [[index-action-type]]
 === Index action
+++++
+<titleabbrev>Index</titleabbrev>
+++++
 
 The index action type will index a document into {es}. See also the {ref}/indices-create-index.html[create index API].
 
 [float]
 [[index-connector-configuration]]
 ==== Connector configuration
 
-Index connectors have the following configuration properties:
+Index connectors have the following configuration properties.
 
 Name::      The name of the connector. The name is used to identify a  connector in the management UI connector listing, or in the connector list when configuring an action.
 Index::     The {es} index to be written to.
@@ -30,32 +33,24 @@ Execution time field::  This field will be automatically set to the time the ale
      executionTimeField: somedate
 --
 
-[[index-connector-config-properties]]
-**`config`** defines the action type specific to the configuration and contains the following properties:
-
-[cols="2*<"]
-|===
-
-|`index`
-| A string that corresponds to *Index*.
-
-|`refresh`
-| A boolean that corresponds to *Refresh*. Defaults to `false`.
-
-|`executionTimeField`
-| A string that corresponds to *Execution time field*.
-
-|===
+Config defines information for the action type.
 
+`index`:: A string that corresponds to *Index*.
+`refresh`:: A boolean that corresponds to *Refresh*. Defaults to `false`.
+`executionTimeField`:: A string that corresponds to *Execution time field*.
 
 [float]
 [[index-action-configuration]]
 ==== Action configuration
 
-Index actions have the following properties:
+Index actions have the following properties.
 
 Document::  The document to index in JSON format.
 
+[float]
+[[index-action-example]]
+==== Example
+
 Example of the index document for Index Threshold alert:
 
 [source,text]

diff --git a/docs/user/alerting/action-types/jira.asciidoc b/docs/user/alerting/action-types/jira.asciidoc
@@ -1,14 +1,17 @@
 [role="xpack"]
 [[jira-action-type]]
 === Jira action
+++++
+<titleabbrev>Jira</titleabbrev>
+++++
 
 The Jira action type uses the https://developer.atlassian.com/cloud/jira/platform/rest/v2/[REST API v2] to create Jira issues.
 
 [float]
 [[jira-connector-configuration]]
 ==== Connector configuration
 
-Jira connectors have the following configuration properties:
+Jira connectors have the following configuration properties.
 
 Name::      The name of the connector. The name is used to identify a  connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
 URL::       Jira instance URL.
@@ -33,37 +36,21 @@ API token (or password)::  Jira API authentication token (or password) for HTTP
      apiToken: tokenkeystorevalue
 --
 
-[[jira-connector-config-properties]]
-**`config`** defines the action type specific to the configuration and contains the following properties:
+Config defines information for the action type.
 
-[cols="2*<"]
-|===
+`apiUrl`:: An address that corresponds to *URL*.
+`projectKey`:: A key that corresponds to *Project Key*.
 
-| `apiUrl`
-| An address that corresponds to *URL*.
+Secrets defines sensitive information for the action type.
 
-| `projectKey`
-| A key that corresponds to *Project Key*.
-
-|===
-
-**`secrets`** defines sensitive information for the action type and contains the following properties:
-
-[cols="2*<"]
-|===
-
-| `email`
-| A string that corresponds to *Email*.
-
-| `apiToken`
-| A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.
-
-|===
+`email`:: A string that corresponds to *Email*.
+`apiToken`:: A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.
 
+[float]
 [[jira-action-configuration]]
 ==== Action configuration
 
-Jira actions have the following configuration properties:
+Jira actions have the following configuration properties.
 
 Issue type:: The type of the issue.
 Priority:: The priority of the incident.
@@ -74,6 +61,6 @@ Parent:: The ID or key of the parent issue. Only for `Subtask` issue types.
 Additional comments:: Additional information for the client, such as how to troubleshoot the issue.
 
 [[configuring-jira]]
-==== Configuring and testing Jira
+==== Configure Jira
 
 Jira offers free https://www.atlassian.com/software/jira/free[Instances], which you can use to test incidents.