[Actions][Doc] Clean up Actions README (#91789)

ymao1 · gchaps · kibanamachine · kibanamachine · commit b323b267ddab · 2021-02-24T02:32:14.000Z
* Removing REST API from README. Updating configuration docs

* Updating action config docs

* Cleaning up action type configs in README and user docs

* Cleaning up action type configs in README and user docs

* Fixing formatting

* Apply suggestions from code review

Co-authored-by: gchaps &lt;33642766+gchaps@users.noreply.github.com&gt;

* PR fixes

* Update x-pack/plugins/actions/README.md

Co-authored-by: gchaps &lt;33642766+gchaps@users.noreply.github.com&gt;

Co-authored-by: gchaps &lt;33642766+gchaps@users.noreply.github.com&gt;
Co-authored-by: Kibana Machine &lt;42973632+kibanamachine@users.noreply.github.com&gt;
diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc
@@ -13,12 +13,12 @@ NOTE: For emails to have a footer with a link back to {kib}, set the <<server-pu
 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, specified in `user@host-name` format.
+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.
-Username::  username for 'login' type authentication.
-Password::  password for 'login' type authentication.
+User::  Username for login type authentication.
+Password::  Password for login type authentication.
 
 [float]
 [[Preconfigured-email-configuration]]
@@ -40,11 +40,14 @@ Password::  password for 'login' type authentication.
 --
 
 [[email-connector-config-properties]]
-`config` defines the action type specific to the configuration and contains the following properties:
+**`config`** defines the action type specific to the configuration and contains the following properties:
 
 [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*.
 
@@ -57,18 +60,21 @@ Password::  password for 'login' type authentication.
 | `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:
+**`secrets`** defines sensitive information for the action type and contains the following properties:
 
 [cols="2*<"]
 |===
 
 | `user`
-| A string that corresponds to *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>>.
+| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
 
 |===
 
diff --git a/docs/user/alerting/action-types/index.asciidoc b/docs/user/alerting/action-types/index.asciidoc
@@ -31,7 +31,7 @@ Execution time field::  This field will be automatically set to the time the ale
 --
 
 [[index-connector-config-properties]]
-`config` defines the action type specific to the configuration and contains the following properties:
+**`config`** defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]
 |===
@@ -40,7 +40,7 @@ Execution time field::  This field will be automatically set to the time the ale
 | A string that corresponds to *Index*.
 
 |`refresh`
-| A boolean that corresponds to *Refresh*.
+| A boolean that corresponds to *Refresh*. Defaults to `false`.
 
 |`executionTimeField`
 | A string that corresponds to *Execution time field*.
diff --git a/docs/user/alerting/action-types/jira.asciidoc b/docs/user/alerting/action-types/jira.asciidoc
@@ -34,7 +34,7 @@ API token (or password)::  Jira API authentication token (or password) for HTTP
 --
 
 [[jira-connector-config-properties]]
-`config` defines the action type specific to the configuration and contains the following properties:
+**`config`** defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]
 |===
@@ -47,7 +47,7 @@ API token (or password)::  Jira API authentication token (or password) for HTTP
 
 |===
 
-`secrets` defines sensitive information for the action type:
+**`secrets`** defines sensitive information for the action type and contains the following properties:
 
 [cols="2*<"]
 |===
@@ -65,14 +65,44 @@ API token (or password)::  Jira API authentication token (or password) for HTTP
 
 Jira actions have the following configuration properties:
 
-Issue type::              The type of the issue.
-Priority::              The priority of the incident.
-Labels::              The labels of the incident.
-Title::    A title for the issue, used for searching the contents of the knowledge base. 
-Description::          The details about the incident.
-Parent::              The parent issue id or key. Only for `Sub-task` issue types.
-Priority::              The priority of the incident.
-Additional comments::  Additional information for the client, such as how to troubleshoot the issue.
+Subaction::        The subaction to perform: `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`.
+Subaction params:: The parameters of the subaction.
+
+==== `pushToService` subaction configuration
+
+Incident:: A Jira incident has the following properties:
+* `summary` - The title of the issue.
+* `description` - A description of the issue.
+* `externalId` - The ID of the issue in Jira. If present, the issue is updated. Otherwise, a new issue is created.
+* `issueType` - The ID of the issue type in Jira.
+* `priority` - The priority level in Jira. Example: `Medium`.
+* `labels` - An array of labels. Labels cannot contain spaces.
+* `parent` - The parent issue ID or key. Only for subtask issue types.
+Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`.
+
+==== `getIncident` subaction configuration
+
+External ID:: The ID of the issue in Jira.
+
+==== `issueTypes` subaction configuration
+
+The `issueTypes` subaction has no parameters. Provide an empty object `{}`.
+
+==== `fieldsByIssueType` subaction configuration
+
+ID:: The ID of the issue in Jira.
+
+==== `issues` subaction configuration
+
+Title:: The title to search for.
+
+==== `issue` subaction configuration
+
+ID:: The ID of the issue in Jira.
+
+==== `getFields` subaction configuration
+
+The `getFields` subaction has no parameters. Provide an empty object `{}`.
 
 [[configuring-jira]]
 ==== Configuring and testing Jira
diff --git a/docs/user/alerting/action-types/pagerduty.asciidoc b/docs/user/alerting/action-types/pagerduty.asciidoc
@@ -151,14 +151,25 @@ Integration Key::   A 32 character PagerDuty Integration Key for an integration
 --
 
 [[pagerduty-connector-config-properties]]
-`config` defines the action type specific to the configuration.
-`config` contains
-`apiURL`, a string that corresponds to *API URL*.
+**`config`** defines the action type specific to the configuration and contains the following properties:
 
-`secrets` defines sensitive information for the action type.
-`secrets` contains
-`routingKey`, a string that corresponds to *Integration Key*.
+[cols="2*<"]
+|===
 
+|`apiURL`
+| A URL string that corresponds to *API URL*.
+
+|===
+
+**`secrets`** defines sensitive information for the action type and contains the following properties:
+
+[cols="2*<"]
+|===
+
+|`routingKey`
+| A string that corresponds to *Integration Key*.
+
+|===
 
 [float]
 [[pagerduty-action-configuration]]
diff --git a/docs/user/alerting/action-types/resilient.asciidoc b/docs/user/alerting/action-types/resilient.asciidoc
@@ -34,7 +34,7 @@ API key secret::  The authentication key secret for HTTP Basic authentication.
 --
 
 [[resilient-connector-config-properties]]
-`config` defines the action type specific to the configuration and contains the following properties:
+**`config`** defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]
 |===
@@ -47,7 +47,7 @@ API key secret::  The authentication key secret for HTTP Basic authentication.
 
 |===
 
-`secrets` defines sensitive information for the action type:
+**`secrets`** defines sensitive information for the action type and contains the following properties:
 
 [cols="2*<"]
 |===
@@ -65,11 +65,30 @@ API key secret::  The authentication key secret for HTTP Basic authentication.
 
 IBM Resilient actions have the following configuration properties:
 
-Incident types::              The incident types of the incident.
-Severity code::              The severity of the incident.
-Name::    A name for the issue, used for searching the contents of the knowledge base. 
-Description::          The details about the incident.
-Additional comments::  Additional information for the client, such as how to troubleshoot the issue.
+Subaction::        The subaction to perform: `pushToService`, `getFields`, `incidentTypes`, or `severity`.
+Subaction params:: The parameters of the subaction.
+
+==== `pushToService` subaction configuration
+
+Incident:: The IBM resilient incident has the following properties:
+* `name` - A name for the issue, used for searching the contents of the knowledge base.
+* `description` - The details about the incident.
+* `externalId` - The ID of the incident in IBM Resilient. If present, the incident is updated. Otherwise, a new incident is created.
+* `incidentTypes` - An array with the IDs of IBM Resilient incident types.
+* `severityCode` - The IBM Resilient ID of the severity code.
+Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`.
+
+===== `getFields` subaction configuration
+
+The `getFields` subaction has not parameters. Provide an empty object `{}`.
+
+===== `incidentTypes` subaction configuration
+
+The `incidentTypes` subaction has no parameters. Provide an empty object `{}`.
+
+===== `severity` subaction configuration
+
+The `severity` subaction has no parameters. Provide an empty object `{}`.
 
 [[configuring-resilient]]
 ==== Configuring and testing IBM Resilient
diff --git a/docs/user/alerting/action-types/server-log.asciidoc b/docs/user/alerting/action-types/server-log.asciidoc
@@ -30,3 +30,4 @@ Name::      The name of the connector. The name is used to identify a  connector
 Server log actions have the following properties:
 
 Message::   The message to log.
+Level::     The log level of the message: `trace`, `debug`, `info`, `warn`, `error` or `fatal`. Defaults to `info`.
diff --git a/docs/user/alerting/action-types/servicenow.asciidoc b/docs/user/alerting/action-types/servicenow.asciidoc
@@ -32,7 +32,7 @@ Password::  Password for HTTP Basic authentication.
 --
 
 [[servicenow-connector-config-properties]]
-`config` defines the action type specific to the configuration and contains the following properties:
+**`config`** defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]
 |===
@@ -42,7 +42,7 @@ Password::  Password for HTTP Basic authentication.
 
 |===
 
-`secrets` defines sensitive information for the action type:
+**`secrets`** defines sensitive information for the action type and contains the following properties:
 
 [cols="2*<"]
 |===
@@ -60,12 +60,33 @@ Password::  Password for HTTP Basic authentication.
 
 ServiceNow actions have the following configuration properties:
 
-Urgency::              The extent to which the incident resolution can delay.
-Severity::             The severity of the incident.
-Impact::               The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question.
-Short description::    A short description for the incident, used for searching the contents of the knowledge base. 
-Description::          The details about the incident.
-Additional comments::  Additional information for the client, such as how to troubleshoot the issue.
+Subaction::        The subaction to perform: `pushToService`, `getFields`, `getIncident`, or `getChoices`.
+Subaction params:: The parameters of the subaction.
+
+==== `pushToService` subaction configuration
+
+Incident:: The ServiceNow incident has the following properties:
+* `short_description` - A short description for the incident, used for searching the contents of the knowledge base.
+* `description` - The details about the incident.
+* `externalId` - The ID of the incident in ServiceNow. If present, the incident is updated. Otherwise, a new incident is created.
+* `severity` - The severity of the incident.
+* `urgency` - The extent to which the incident resolution can delay.
+* `impact` - The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question.
+* `category` - The name of the category in ServiceNow.
+* `subcategory` - The name of the subcategory in ServiceNow.
+Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`.
+
+===== `getFields` subaction configuration
+
+The `getFields` subaction has no parameters. Provide an empty object `{}`.
+
+===== `getIncident` subaction configuration
+
+External ID:: The ID of the incident in ServiceNow.
+
+===== `getChoices` subaction configuration
+
+Fields:: An array of fields. Example: `[priority, category, impact]`.
 
 [[configuring-servicenow]]
 ==== Configuring and testing ServiceNow
diff --git a/docs/user/alerting/action-types/slack.asciidoc b/docs/user/alerting/action-types/slack.asciidoc
@@ -22,15 +22,19 @@ Webhook URL::   The URL of the incoming webhook. See https://api.slack.com/messa
  my-slack:
    name: preconfigured-slack-action-type
    actionTypeId: .slack
-   config:
+   secrets:
      webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz'
 --
 
-[[slack-connector-config-properties]]
-`config` defines the action type specific to the configuration.
-`config` contains
-`webhookUrl`, a string that corresponds to *Webhook URL*.
+**`secrets`** defines sensitive information for the action type and contains the following properties:
 
+[cols="2*<"]
+|===
+
+| `webhookUrl`
+| A string that corresponds to *Webhook URL*.
+
+|===
 
 [float]
 [[slack-action-configuration]]
diff --git a/docs/user/alerting/action-types/teams.asciidoc b/docs/user/alerting/action-types/teams.asciidoc
@@ -22,14 +22,20 @@ Webhook URL::   The URL of the incoming webhook. See https://docs.microsoft.com/
  my-teams:
    name: preconfigured-teams-action-type
    actionTypeId: .teams
-   config:
+   secrets:
      webhookUrl: 'https://outlook.office.com/webhook/abcd@0123456/IncomingWebhook/abcdefgh/ijklmnopqrstuvwxyz'
 --
 
 [[teams-connector-config-properties]]
-`config` defines the action type specific to the configuration.
-`config` contains
-`webhookUrl`, a string that corresponds to *Webhook URL*.
+**`secrets`** defines sensitive information for the action type and contains the following properties:
+
+[cols="2*<"]
+|===
+
+| `webhookUrl`
+| A string that corresponds to *Webhook URL*.
+
+|===
 
 
 [float]
diff --git a/docs/user/alerting/action-types/webhook.asciidoc b/docs/user/alerting/action-types/webhook.asciidoc
@@ -12,10 +12,10 @@ Webhook 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.
 URL::       The request URL. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
-Method::    HTTP request method, either `post`(default) or `put`.
+Method::    HTTP request method, either `POST`(default) or `PUT`.
 Headers::   A set of key-value pairs sent as headers with the request
-User::      An optional username. If set, HTTP basic authentication is used. Currently only basic authentication is supported.
-Password::  An optional password. If set, HTTP basic authentication is used. Currently only basic authentication is supported.
+User::      Username for HTTP basic authentication.
+Password::  Password for HTTP basic authentication.
 
 [float]
 [[Preconfigured-webhook-configuration]]
@@ -37,7 +37,7 @@ Password::  An optional password. If set, HTTP basic authentication is used. Cur
 --
 
 [[webhook-connector-config-properties]]
-`config` defines the action type specific to the configuration and contains the following properties:
+**`config`** defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]
 |===
@@ -51,18 +51,21 @@ Password::  An optional password. If set, HTTP basic authentication is used. Cur
 |`headers`
 |A record<string, string> that corresponds to *Headers*.
 
+| `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:
+**`secrets`** defines sensitive information for the action type and contains the following properties:
 
 [cols="2*<"]
 |===
 
 |`user`
-|A string that corresponds to *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>>.
+|A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
 
 |===
 
diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc
diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md

Original file line number	Diff line number	Diff line change
`@@ -30,3 +30,4 @@ Name:: The name of the connector. The name is used to identify a connector`
`30`	`30`	`Server log actions have the following properties:`
`31`	`31`
`32`	`32`	`Message:: The message to log.`
	`33`	+Level:: The log level of the message: `trace`, `debug`, `info`, `warn`, `error` or `fatal`. Defaults to `info`.