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.

Sign up for GitHub

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

Jump to bottom

[7.8] [DOCS] Improves formatting in action types (#65932) #66300

Merged
merged 1 commit into from
May 12, 2020
Merged

[7.8] [DOCS] Improves formatting in action types (#65932) #66300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
6 changes: 3 additions & 3 deletions docs/user/alerting/action-types.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ see https://www.elastic.co/subscriptions[the subscription page].

[float]
[[create-connectors]]
=== Preconfigured connectors and action types
=== Preconfigured actions and connectors

For out-of-the-box and standardized connectors, you can <<preconfigured-connector-example, preconfigure connectors>>
For out-of-the-box and standardized connectors, you can <<preconfigured-connector-example, preconfigure the connector>>
before {kib} starts.

If you preconfigure a connector, you can also <<preconfigured-action-type-example, preconfigure its action type>>.
Expand All @@ -54,4 +54,4 @@ include::action-types/pagerduty.asciidoc[]
include::action-types/server-log.asciidoc[]
include::action-types/slack.asciidoc[]
include::action-types/webhook.asciidoc[]
include::pre-configured-connectors.asciidoc[]
include::action-types/pre-configured-connectors.asciidoc[]
55 changes: 37 additions & 18 deletions docs/user/alerting/action-types/email.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,31 +24,50 @@ Password:: password for 'login' type authentication.

[source,text]
--
id: 'my-email'
name: preconfigured-email-action-type
actionTypeId: .email
config:
from: testsender@test.com <1.1>
host: validhostname <1.2>
port: 8080 <1.3>
secure: false <1.4>
secrets:
user: testuser <2.1>
password: passwordkeystorevalue <2.2>
my-email:
name: preconfigured-email-action-type
actionTypeId: .email
config:
from: testsender@test.com
host: validhostname
port: 8080
secure: false
secrets:
user: testuser
password: passwordkeystorevalue
--

`config` defines the action type specific to the configuration and contains the following properties:

<1.1> `from:` is an email address and correspond to *Sender*.
<1.2> `host:` is a string and correspond to *Host*.
<1.3> `port:` is a number and correspond to *Port*.
<1.4> `secure:` is a boolean and correspond to *Secure*.
[cols="2*<"]
|===

`secrets` defines action type sensitive configuration:
| `from`
| An email address that corresponds to *Sender*.

<2.1> `user:` is a string and correspond to *User*.
<2.2> `password:` is a string and correspond to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.
| `host`
| A string that corresponds to *Host*.

| `port`
| A number that corresponds to *Port*.

| `secure`
| A boolean that corresponds to *Secure*.

|===

`secrets` defines sensitive information for the action type:

[cols="2*<"]
|===

| `user`
| A string that corresponds to *User*.

| `password`
| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.

|===

[[email-action-configuration]]
==== Action configuration
Expand Down
30 changes: 20 additions & 10 deletions docs/user/alerting/action-types/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,20 +21,30 @@ Execution time field:: This field will be automatically set to the time the ale

[source,text]
--
id: 'my-index'
name: action-type-index
actionTypeId: .index
config:
index: .kibana <1>
refresh: true <2>
executionTimeField: somedate <3>
my-index:
name: action-type-index
actionTypeId: .index
config:
index: .kibana
refresh: true
executionTimeField: somedate
--

`config` defines the action type specific to the configuration and contains the following properties:

<1> `index:` is a string and correspond to *Index*.
<2> `refresh:` is a boolean and correspond to *Refresh*.
<3> `executionTimeField:` is a string and correspond to *Execution time field*.
[cols="2*<"]
|===

|`index`
| A string that corresponds to *Index*.

|`refresh`
| A boolean that corresponds to *Refresh*.

|`executionTimeField`
| A string that corresponds to *Execution time field*.

|===


[float]
Expand Down
25 changes: 13 additions & 12 deletions docs/user/alerting/action-types/pagerduty.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,22 +141,23 @@ Integration Key:: A 32 character PagerDuty Integration Key for an integration

[source,text]
--
id: 'my-pagerduty'
name: preconfigured-pagerduty-action-type
actionTypeId: .pagerduty
config:
apiUrl: https://test.host <1.1>
secrets:
routingKey: testroutingkey <2.1>
my-pagerduty:
name: preconfigured-pagerduty-action-type
actionTypeId: .pagerduty
config:
apiUrl: https://test.host
secrets:
routingKey: testroutingkey
--

`config` defines the action type specific to the configuration and contains the following properties:
`config` defines the action type specific to the configuration.
`config` contains
`apiURL`, a string that corresponds to *API URL*.

<1.1> `apiUrl:` is URL string and correspond to *API URL*.
`secrets` defines sensitive information for the action type.
`secrets` contains
`routingKey`, a string that corresponds to *Integration Key*.

`secrets` defines action type sensitive configuration:

<2.1> `routingKey:` is a string and correspond to *Integration Key*.

[float]
[[pagerduty-action-configuration]]
Expand Down
99 changes: 46 additions & 53 deletions ...erting/pre-configured-connectors.asciidoc → ...-types/pre-configured-connectors.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
[role="xpack"]
[[pre-configured-action-types-and-connectors]]

== Preconfigured connectors and action types
=== Preconfigured connectors and action types

You can preconfigure an action type or a connector to have all the information it needs prior to startup
You can preconfigure a connector or action type to have all the information it needs prior to startup
by adding it to the `kibana.yml` file.

Preconfigured connectors offer the following capabilities:
Expand All @@ -13,15 +13,15 @@ action are predefined, including the connector name and ID.
- Appear in all spaces because they are not saved objects.
- Cannot be edited or deleted.

Sensitive configuration information, such as credentials, can use the <<creating-keystore, {kib} keystore>>.

A preconfigured action types has only preconfigured connectors. Preconfigured connectors can belong to either the preconfigured action type or to the regular action type.
A preconfigured action type has only preconfigured connectors. Preconfigured
connectors can belong to either the preconfigured action type or to the regular action type.

[float]
[[preconfigured-connector-example]]
=== Creating a preconfigured connector
==== Preconfigured connectors

The following example shows a valid configuration of two out-of-the box connectors: <<slack-action-type, Slack>> and <<webhook-action-type, Webhook>>.
This example shows a valid configuration for
two out-of-the box connectors: <<slack-action-type, Slack>> and <<webhook-action-type, Webhook>>.

```js
xpack.actions.preconfigured:
Expand All @@ -44,7 +44,7 @@ The following example shows a valid configuration of two out-of-the box connecto
password: changeme
```

<1> the key is the action connector identifier, eg `my-slack1` in this example.
<1> The key is the action connector identifier, `my-slack1` in this example.
<2> `actionTypeId` is the action type identifier.
<3> `name` is the name of the preconfigured connector.
<4> `config` is the action type specific to the configuration.
Expand All @@ -55,74 +55,67 @@ The following example shows a valid configuration of two out-of-the box connecto
Sensitive properties, such as passwords, can also be stored in the <<creating-keystore, {kib} keystore>>.
==============================================

[float]
[[preconfigured-action-type-example]]
=== Creating a preconfigured action type

In the `kibana.yml` file:

. Exclude the action type from `xpack.actions.enabledActionTypes`.
. Add all its preconfigured connectors.

The following example shows a valid configuration of preconfigured action type with one out-of-the box connector.

```js
xpack.actions.enabledActionTypes: ['.slack', '.email', '.index'] <1>
xpack.actions.preconfigured: <2>
- id: 'my-server-log'
actionTypeId: .server-log
name: 'Server log #xyz'
```

<1> `enabledActionTypes` should exclude preconfigured action type to prevent creating and deleting connectors.
<2> `preconfigured` is the setting for defining the list of available connectors for the preconfigured action type.

////
[float]
[[managing-pre-configured-connectors]]
=== Managing preconfigured connectors
==== View preconfigured connectors
////

Preconfigured connectors appear in the connector list, regardless of which space the user is in.
They are tagged as “preconfigured” and cannot be deleted.
In *Management > Alerts and Actions*, preconfigured connectors
appear in the <<connector-management, *Connectors* tab>>,
regardless of which space you are in.
They are tagged as “preconfigured”, and you cannot delete them.

[role="screenshot"]
image::images/pre-configured-connectors-managing.png[Connectors managing tab with pre-cofigured]

Clicking on a preconfigured connector shows the description, but not any of the configuration.
Clicking a preconfigured connector shows the description, but not the configuration.
A message indicates that this is a preconfigured connector.

[role="screenshot"]
image::images/pre-configured-connectors-view-screen.png[Pre-configured connector view details]

The connector details preview is disabled for preconfigured connectors.
The connector details preview is disabled for preconfigured connectors
of a preconfigured action type.

[role="screenshot"]
image::images/pre-configured-action-type-managing.png[Connectors managing tab with pre-cofigured]


[float]
[[managing-pre-configured-action-types]]
=== Managing preconfigured action types
[[preconfigured-action-type-example]]
==== Preconfigured action type

Clicking *Create connector* shows the list of available action types.
Disabled action types are not included.
This example shows a preconfigured action type with one out-of-the box connector.

[role="screenshot"]
image::images/pre-configured-action-type-select-type.png[Pre-configured connector create menu]
```js
xpack.actions.enabledActionTypes: ['.slack', '.email', '.index'] <1>
xpack.actions.preconfigured: <2>
my-server-log:
actionTypeId: .server-log
name: 'Server log #xyz'
```

[float]
[[pre-configured-connector-alert-form]]
=== Alert with a preconfigured connector
<1> `enabledActionTypes` excludes the preconfigured action type to prevent creating and deleting connectors.
<2> `preconfigured` is the setting for defining the list of available connectors for the preconfigured action type.

When attaching an action to an alert,
select from a list of available action types, and
then select the Slack or Webhook type. Those action types were configured previously.
The preconfigured connector is installed and is automatically selected.
[[managing-pre-configured-action-types]]
To attach a preconfigured action to an alert:

[role="screenshot"]
image::images/alert-pre-configured-slack-connector.png[Create alert with selected Slack action type]
. In *Management > Alerts and Actions*, open the *Connectors* tab.

The dropdown is populated with additional preconfigured Slack connectors.
The `preconfigured` label distinguishes them from space-aware connectors that use saved objects.
. Click *Create connector.*

. In the list of available action types, select the preconfigured action type you want.
+
[role="screenshot"]
image::images/pre-configured-action-type-select-type.png[Pre-configured connector create menu]

. In *Create alert*, open the connector dropdown, and then select the preconfigured
connector.
+
The `preconfigured` label distinguishes it from a space-aware connector.
+
[role="screenshot"]
image::images/alert-pre-configured-connectors-dropdown.png[Dropdown list with pre-cofigured connectors]

. Click *Add action*.
16 changes: 8 additions & 8 deletions docs/user/alerting/action-types/slack.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,16 @@ Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messa

[source,text]
--
id: 'my-slack'
name: preconfigured-slack-action-type
actionTypeId: .slack
config:
webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz' <1>
my-slack:
name: preconfigured-slack-action-type
actionTypeId: .slack
config:
webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz'
--

`config` defines the action type specific to the configuration and contains the following properties:

<1> `webhookUrl:` is URL string and correspond to *Webhook URL*.
`config` defines the action type specific to the configuration.
`config` contains
`webhookUrl`, a string that corresponds to *Webhook URL*.


[float]
Expand Down
Loading