Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.x] [Actions][Doc] Clean up Actions README (#91789) #92557

Merged
merged 1 commit into from
Feb 24, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions docs/user/alerting/action-types/email.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand All @@ -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*.

Expand All @@ -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`.

|===

Expand Down
4 changes: 2 additions & 2 deletions docs/user/alerting/action-types/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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*<"]
|===
Expand All @@ -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*.
Expand Down
50 changes: 40 additions & 10 deletions docs/user/alerting/action-types/jira.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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*<"]
|===
Expand All @@ -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*<"]
|===
Expand All @@ -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
Expand Down
23 changes: 17 additions & 6 deletions docs/user/alerting/action-types/pagerduty.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
33 changes: 26 additions & 7 deletions docs/user/alerting/action-types/resilient.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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*<"]
|===
Expand All @@ -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*<"]
|===
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/user/alerting/action-types/server-log.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
37 changes: 29 additions & 8 deletions docs/user/alerting/action-types/servicenow.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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*<"]
|===
Expand All @@ -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*<"]
|===
Expand All @@ -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
Expand Down
14 changes: 9 additions & 5 deletions docs/user/alerting/action-types/slack.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
14 changes: 10 additions & 4 deletions docs/user/alerting/action-types/teams.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
17 changes: 10 additions & 7 deletions docs/user/alerting/action-types/webhook.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand All @@ -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*<"]
|===
Expand All @@ -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`.

|===

Expand Down
Loading