From ea22deff4335fe6a753ea3f6acc2dce33101d423 Mon Sep 17 00:00:00 2001 From: ymao1 Date: Fri, 19 Feb 2021 18:43:18 -0500 Subject: [PATCH] Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- .../user/alerting/action-types/email.asciidoc | 8 +++--- docs/user/alerting/action-types/jira.asciidoc | 26 +++++++++---------- .../alerting/action-types/resilient.asciidoc | 18 ++++++------- .../alerting/action-types/server-log.asciidoc | 2 +- .../alerting/action-types/servicenow.asciidoc | 12 ++++----- docs/user/alerting/defining-alerts.asciidoc | 6 ++--- x-pack/plugins/actions/README.md | 4 +-- 7 files changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc index 62ce57cb74bda..199118018f0e8 100644 --- a/docs/user/alerting/action-types/email.asciidoc +++ b/docs/user/alerting/action-types/email.asciidoc @@ -11,12 +11,12 @@ The email action type uses the SMTP protocol to send mail message, using an inte 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 "` format. See the [nodemailer address documentation](https://nodemailer.com/message/addresses/) for more information. +Sender:: The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human 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 <> 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. -Password:: Password for 'login' type authentication. +User:: Username for login type authentication. +Password:: Password for login type authentication. [float] [[Preconfigured-email-configuration]] @@ -44,7 +44,7 @@ Password:: Password for 'login' type authentication. |=== | `service` -| The name of a [well-known email service provider](https://nodemailer.com/smtp/well-known/) value. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value specifically, see the [nodemailer gmail documentation](https://nodemailer.com/usage/using-gmail/). +| 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*. diff --git a/docs/user/alerting/action-types/jira.asciidoc b/docs/user/alerting/action-types/jira.asciidoc index 3bbe5536a545a..02f2a9be89254 100644 --- a/docs/user/alerting/action-types/jira.asciidoc +++ b/docs/user/alerting/action-types/jira.asciidoc @@ -65,32 +65,32 @@ API token (or password):: Jira API authentication token (or password) for HTTP Jira actions have the following configuration properties: -Subaction:: The subaction to perform. Either `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`. +Subaction:: The subaction to perform: `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`. Subaction Params:: The parameters of the subaction. ==== `pushToService` subaction configuration -Incident:: The Jira incident which has the following properties: +Incident:: A Jira incident has the following properties: * `summary` - The title of the issue. -* `description` - The description of the issue. -* `externalId` - The id of the issue in Jira. If present the issue will be updated. Otherwise a new issue will be created. -* `issueType` - The id of the issue type in Jira. -* `priority` - The name of the priority in Jira. Example: `Medium`. +* `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 Sub-task issue types. -Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. +* `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. +External ID:: The ID of the issue in Jira. ==== `issueTypes` subaction configuration -No parameters for `issueTypes` subaction. Provide an empty object `{}`. +The `issueTypes` subaction has no parameters. Provide an empty object `{}`. ==== `fieldsByIssueType` subaction configuration -ID:: The id of the issue in Jira. +ID:: The ID of the issue in Jira. ==== `issues` subaction configuration @@ -98,11 +98,11 @@ Title:: The title to search for. ==== `issue` subaction configuration -ID:: The id of the issue in Jira. +ID:: The ID of the issue in Jira. ==== `getFields` subaction configuration -No parameters for `getFields` subaction. Provide an empty object `{}`. +The `getFields` subaction has no parameters. Provide an empty object `{}`. [[configuring-jira]] ==== Configuring and testing Jira diff --git a/docs/user/alerting/action-types/resilient.asciidoc b/docs/user/alerting/action-types/resilient.asciidoc index 6754dc0ddb50e..4b0b0a9730a2c 100644 --- a/docs/user/alerting/action-types/resilient.asciidoc +++ b/docs/user/alerting/action-types/resilient.asciidoc @@ -65,30 +65,30 @@ API key secret:: The authentication key secret for HTTP Basic authentication. IBM Resilient actions have the following configuration properties: -Subaction:: The subaction to perform. Either `pushToService`, `getFields`, `incidentTypes`, or `severity`. +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 which has the following properties: +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 will be updated. Otherwise a new incident will be created. -* `incidentTypes` - An array with the ids of IBM Resilient incident types. -* `severityCode` - IBM Resilient id of the severity code. -Comments:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. +* `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 -No parameters for `getFields` subaction. Provide an empty object `{}`. +The `getFields` subaction has not parameters. Provide an empty object `{}`. ===== `incidentTypes` subaction configuration -No parameters for `incidentTypes` subaction. Provide an empty object `{}`. +The `incidentTypes` subaction has no parameters. Provide an empty object `{}`. ===== `severity` subaction configuration -No parameters for `severity` subaction. Provide an empty object `{}`. +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 index f66e1714b8c73..276f64e7786bd 100644 --- a/docs/user/alerting/action-types/server-log.asciidoc +++ b/docs/user/alerting/action-types/server-log.asciidoc @@ -30,4 +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. Either `trace`, `debug`, `info`, `warn`, `error` or `fatal`. Defaults to `info`. +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 index a3447a3310d97..1e4923a7d449e 100644 --- a/docs/user/alerting/action-types/servicenow.asciidoc +++ b/docs/user/alerting/action-types/servicenow.asciidoc @@ -60,29 +60,29 @@ Password:: Password for HTTP Basic authentication. ServiceNow actions have the following configuration properties: -Subaction:: The subaction to perform. Either `pushToService`, `getFields`, `getIncident`, or `getChoices`. +Subaction:: The subaction to perform: `pushToService`, `getFields`, `getIncident`, or `getChoices`. Subaction Params:: The parameters of the subaction. ==== `pushToService` subaction configuration -Incident:: The ServiceNow incident which has the following properties: +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 will be updated. Otherwise a new incident will be created. +* `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:: The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. +Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`. ===== `getFields` subaction configuration -No parameters for `getFields` subaction. Provide an empty object `{}`. +The `getFields` subaction has no parameters. Provide an empty object `{}`. ===== `getIncident` subaction configuration -External ID:: The id of the incident in ServiceNow. +External ID:: The ID of the incident in ServiceNow. ===== `getChoices` subaction configuration diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index f88e4cd19c65f..01bf6a35597be 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -91,10 +91,10 @@ If you are using a cloud deployment, you can set these via the console. Here's a list of the available global configuration options and an explanation of what each one does: -* `xpack.actions.enabled`: Feature toggle which enables Actions in {kib}. Default: `true` +* `xpack.actions.enabled`: Feature toggle that enables Actions in {kib}. Default: `true` * `xpack.actions.allowedHosts`: Specifies an array of host names which actions such as email, Slack, PagerDuty, and webhook can connect to. An element of * indicates any host can be connected to. An empty array indicates no hosts can be connected to. Default: [ {asterisk} ] -* `xpack.actions.enabledActionTypes`: Specifies to an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are: `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, `.webhook`. Default: [ {asterisk} ] -* `xpack.actions.preconfigured`: Specifies preconfigured action ids and configs. Default: {} +* `xpack.actions.enabledActionTypes`: Specifies an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, and `.webhook`. Default: [ {asterisk} ] +* `xpack.actions.preconfigured`: Specifies preconfigured action IDs and configs. Default: {} * `xpack.actions.proxyUrl`: Specifies the proxy URL to use, if using a proxy for actions. * `xpack.actions.proxyHeader`: Specifies HTTP headers for proxy, if using a proxy for actions. * `xpack.actions.proxyRejectUnauthorizedCertificates`: Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 4905835388fe1..6546f625af889 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -116,7 +116,7 @@ Built-In-Actions are configured using the _xpack.actions_ namespace under _kiban #### **allowedHosts** configuration -- You may use the string "*" in the **allowedHosts** configuration in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential to use such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. +- You can use the string "*" in the **allowedHosts** configuration in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential to use such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. - The **allowedHosts** configuration applies to built-in action types (such as Slack, or PagerDuty) as well. Uniquely, the _PagerDuty Action Type_ has been configured to support the service's Events API (at _https://events.pagerduty.com/v2/enqueue_, which you can read about [here](https://v2.developer.pagerduty.com/docs/events-api-v2)) as a default, but this too, must be included in the allowedHosts before the PagerDuty action can be used. @@ -326,4 +326,4 @@ Instead of `schema.maybe()`, use `schema.nullable()`, which is the same as `sche ## user interface -In order to make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui). \ No newline at end of file +In order to make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui).