Skip to content

Commit

Permalink
Added help text where needed on connectors and alert actions UI (#69601)
Browse files Browse the repository at this point in the history
* Added help text where needed on connectors and alert actions UI

* fixed ui form

* Added index action type examples, fixed slack link

* Fixed email connector docs and links

* Additional cleanup on email

* Removed autofocus to avoid twice link click for opening in the new page

* Extended documentation for es index action type

* Fixed tests

* Fixed doc link

* fixed due to comments

* fixed due to comments

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

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

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

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

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

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

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/email.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/index.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Update docs/user/alerting/action-types/slack.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Fixed due to comments

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
  • Loading branch information
YulNaumenko and gchaps authored Jul 14, 2020
1 parent 835c13d commit 2009447
Show file tree
Hide file tree
Showing 22 changed files with 288 additions and 43 deletions.
119 changes: 119 additions & 0 deletions docs/user/alerting/action-types/email.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,122 @@ 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.
Subject:: The subject line of the email.
Message:: The message text of the email. Markdown format is supported.

[[configuring-email]]
==== Configuring email accounts

The email action can send email using many popular SMTP email services.

You configure the email action to send emails using the connector form.
For more information about configuring the email connector to work with different email
systems, refer to:

* <<gmail>>
* <<outlook>>
* <<exchange>>
* <<amazon-ses>>

[float]
[[gmail]]
===== Sending email from Gmail

Use the following email account settings to send email from the
https://mail.google.com[Gmail] SMTP service:

[source,text]
--------------------------------------------------
config:
host: smtp.gmail.com
port: 465
secure: true
secrets:
user: <username>
password: <password>
--------------------------------------------------
// CONSOLE

If you get an authentication error that indicates that you need to continue the
sign-in process from a web browser when the action attempts to send email, you need
to configure Gmail to https://support.google.com/accounts/answer/6010255?hl=en[allow
less secure apps to access your account].

If two-step verification is enabled for your account, you must generate and use
a unique App Password to send email from {watcher}. See
https://support.google.com/accounts/answer/185833?hl=en[Sign in using App Passwords]
for more information.

[float]
[[outlook]]
===== Sending email from Outlook.com

Use the following email account settings to send email action from the
https://www.outlook.com/[Outlook.com] SMTP service:

[source,text]
--------------------------------------------------
config:
host: smtp-mail.outlook.com
port: 465
secure: true
secrets:
user: <email.address>
password: <password>
--------------------------------------------------

When sending emails, you must provide a from address, either as the default
in your account configuration or as part of the email action in the watch.

NOTE: You must use a unique App Password if two-step verification is enabled.
See http://windows.microsoft.com/en-us/windows/app-passwords-two-step-verification[App
passwords and two-step verification] for more information.

[float]
[[amazon-ses]]
===== Sending email from Amazon SES (Simple Email Service)

Use the following email account settings to send email from the
http://aws.amazon.com/ses[Amazon Simple Email Service] (SES) SMTP service:

[source,text]
--------------------------------------------------
config:
host: email-smtp.us-east-1.amazonaws.com <1>
port: 465
secure: true
secrets:
user: <username>
password: <password>
--------------------------------------------------
<1> `smtp.host` varies depending on the region

NOTE: You must use your Amazon SES SMTP credentials to send email through
Amazon SES. For more information, see
http://docs.aws.amazon.com/ses/latest/DeveloperGuide/smtp-credentials.html[Obtaining
Your Amazon SES SMTP Credentials]. You might also need to verify
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html[your email address]
or https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domains.html[your whole domain]
at AWS.

[float]
[[exchange]]
===== Sending email from Microsoft Exchange

Use the following email account settings to send email action from Microsoft
Exchange:

[source,text]
--------------------------------------------------
config:
host: <your exchange server>
port: 465
secure: true
from: <email address of service account> <1>
secrets:
user: <email address of service account> <2>
password: <password>
--------------------------------------------------
<1> Some organizations configure Exchange to validate that the `from` field is a
valid local email account.
<2> Many organizations support use of your email address as your username.
Check with your system administrator if you receive
authentication-related failures.
38 changes: 36 additions & 2 deletions docs/user/alerting/action-types/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
[[index-action-type]]
=== Index action

The index action type will index a document into {es}.
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]]
Expand Down Expand Up @@ -53,4 +53,38 @@ Execution time field:: This field will be automatically set to the time the ale

Index actions have the following properties:

Document:: The document to index in json format.
Document:: The document to index in JSON format.

Example of the index document for Index Threshold alert:

[source,text]
--------------------------------------------------
{
"alert_id": "{{alertId}}",
"alert_name": "{{alertName}}",
"alert_instance_id": "{{alertInstanceId}}",
"context_message": "{{context.message}}"
}
--------------------------------------------------

Example of create test index using the API.

[source,text]
--------------------------------------------------
PUT test
{
"settings" : {
"number_of_shards" : 1
},
"mappings" : {
"_doc" : {
"properties" : {
"alert_id" : { "type" : "text" },
"alert_name" : { "type" : "text" },
"alert_instance_id" : { "type" : "text" },
"context_message": { "type" : "text" }
}
}
}
}
--------------------------------------------------
20 changes: 20 additions & 0 deletions docs/user/alerting/action-types/slack.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,23 @@ Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messa
Slack actions have the following properties:

Message:: The message text, converted to the `text` field in the Webhook JSON payload. Currently only the text field is supported. Markdown, images, and other advanced formatting are not yet supported.

[[configuring-slack]]
==== Configuring Slack Accounts

You configure the accounts Slack action type can use to communicate with Slack in the
connector form.

You need a https://api.slack.com/incoming-webhooks[Slack webhook URL] to
configure a Slack account. To create a webhook
URL, set up an an **Incoming Webhook Integration** through the Slack console:

. Log in to http://slack.com[slack.com] as a team administrator.
. Go to https://my.slack.com/services/new/incoming-webhook.
. Select a default channel for the integration.
+
image::images/slack-add-webhook-integration.png[]
. Click *Add Incoming Webhook Integration*.
. Copy the generated webhook URL so you can paste it into your Slack connector form.
+
image::images/slack-copy-webhook-url.png[]
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
19 changes: 9 additions & 10 deletions x-pack/plugins/actions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -437,23 +437,22 @@ The config and params properties are modelled after the [Watcher Index Action](h

### `config`

| Property | Description | Type |
| -------- | -------------------------------------- | ------------------- |
| index | The Elasticsearch index to index into. | string _(optional)_ |
| Property | Description | Type |
| -------------------- | ---------------------------------------------------------- | -------------------- |
| index | The Elasticsearch index to index into. | string _(optional)_ |
| doc_id | The optional \_id of the document. | string _(optional)_ |
| execution_time_field | The field that will store/index the action execution time. | string _(optional)_ |
| refresh | Setting of the refresh policy for the write request. | boolean _(optional)_ |

### `secrets`

This action type has no `secrets` properties.

### `params`

| Property | Description | Type |
| -------------------- | ---------------------------------------------------------- | -------------------- |
| index | The Elasticsearch index to index into. | string _(optional)_ |
| doc_id | The optional \_id of the document. | string _(optional)_ |
| execution_time_field | The field that will store/index the action execution time. | string _(optional)_ |
| refresh | Setting of the refresh policy for the write request | boolean _(optional)_ |
| body | The documument body/bodies to index. | object or object[] |
| Property | Description | Type |
| --------- | ---------------------------------------- | ------------------- |
| documents | JSON object that describes the [document](https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started-index.html#getting-started-batch-processing). | object[] |

---

Expand Down
18 changes: 15 additions & 3 deletions x-pack/plugins/triggers_actions_ui/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -900,10 +900,23 @@ export function getActionType(): ActionTypeModel {

![Index connector card](https://i.imgur.com/fflsmu5.png)

![Index connector form](https://i.imgur.com/tbgyvAL.png)
![Index connector form](https://i.imgur.com/IkixGMV.png)

and action params form available in Create Alert form:
![Index action form](https://i.imgur.com/VsWMLeU.png)
![Index action form](https://i.imgur.com/mpxnPOF.png)

Example of the index document for Index Threshold alert:

```
{
"alert_id": "{{alertId}}",
"alert_name": "{{alertName}}",
"alert_instance_id": "{{alertInstanceId}}",
"context_title": "{{context.title}}",
"context_value": "{{context.value}}",
"context_message": "{{context.message}}"
}
```

### Webhook

Expand Down Expand Up @@ -1582,4 +1595,3 @@ export interface ActionsConnectorsContextValue {
|capabilities|Property, which is defining action current user usage capabilities like canSave or canDelete.|
|toastNotifications|Toast messages.|
|reloadConnectors|Optional function, which will be executed if connector was saved sucsessfuly, like reload list of connecotrs.|

Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,14 @@ import {
EuiFormRow,
} from '@elastic/eui';
import { i18n } from '@kbn/i18n';
import { FormattedMessage } from '@kbn/i18n/react';
import { EuiLink } from '@elastic/eui';
import { ActionConnectorFieldsProps } from '../../../../types';
import { EmailActionConnector } from '../types';

export const EmailActionConnectorFields: React.FunctionComponent<ActionConnectorFieldsProps<
EmailActionConnector
>> = ({ action, editActionConfig, editActionSecrets, errors }) => {
>> = ({ action, editActionConfig, editActionSecrets, errors, docLinks }) => {
const { from, host, port, secure } = action.config;
const { user, password } = action.secrets;

Expand All @@ -38,6 +40,17 @@ export const EmailActionConnectorFields: React.FunctionComponent<ActionConnector
defaultMessage: 'Sender',
}
)}
helpText={
<EuiLink
href={`${docLinks.ELASTIC_WEBSITE_URL}guide/en/kibana/${docLinks.DOC_LINK_VERSION}/email-action-type.html#configuring-email`}
target="_blank"
>
<FormattedMessage
id="xpack.triggersActionsUI.components.builtinActionTypes.emailAction.configureAccountsHelpLabel"
defaultMessage="Configuring email accounts."
/>
</EuiLink>
}
>
<EuiFieldText
fullWidth
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
*/
import React from 'react';
import { mountWithIntl } from 'test_utils/enzyme_helpers';
import { DocLinksStart } from 'kibana/public';
import EmailParamsFields from './email_params';

describe('EmailParamsFields renders', () => {
Expand All @@ -22,6 +23,7 @@ describe('EmailParamsFields renders', () => {
errors={{ to: [], cc: [], bcc: [], subject: [], message: [] }}
editAction={() => {}}
index={0}
docLinks={{ ELASTIC_WEBSITE_URL: '', DOC_LINK_VERSION: '' } as DocLinksStart}
/>
);
expect(wrapper.find('[data-test-subj="toEmailAddressInput"]').length > 0).toBeTruthy();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import {
EuiSelect,
EuiTitle,
EuiIconTip,
EuiLink,
} from '@elastic/eui';
import { FormattedMessage } from '@kbn/i18n/react';
import { i18n } from '@kbn/i18n';
Expand All @@ -28,7 +29,7 @@ import {

const IndexActionConnectorFields: React.FunctionComponent<ActionConnectorFieldsProps<
EsIndexActionConnector
>> = ({ action, editActionConfig, errors, http }) => {
>> = ({ action, editActionConfig, errors, http, docLinks }) => {
const { index, refresh, executionTimeField } = action.config;
const [hasTimeFieldCheckbox, setTimeFieldCheckboxState] = useState<boolean>(
executionTimeField != null
Expand Down Expand Up @@ -77,10 +78,22 @@ const IndexActionConnectorFields: React.FunctionComponent<ActionConnectorFieldsP
isInvalid={errors.index.length > 0 && index !== undefined}
error={errors.index}
helpText={
<FormattedMessage
id="xpack.triggersActionsUI.components.builtinActionTypes.indexAction.howToBroadenSearchQueryDescription"
defaultMessage="Use * to broaden your query."
/>
<>
<FormattedMessage
id="xpack.triggersActionsUI.components.builtinActionTypes.indexAction.howToBroadenSearchQueryDescription"
defaultMessage="Use * to broaden your query."
/>
<EuiSpacer size="s" />
<EuiLink
href={`${docLinks.ELASTIC_WEBSITE_URL}guide/en/kibana/${docLinks.DOC_LINK_VERSION}/index-action-type.html`}
target="_blank"
>
<FormattedMessage
id="xpack.triggersActionsUI.components.builtinActionTypes.indexAction.configureIndexHelpLabel"
defaultMessage="Configuring index connector."
/>
</EuiLink>
</>
}
>
<EuiComboBox
Expand Down Expand Up @@ -186,9 +199,9 @@ const IndexActionConnectorFields: React.FunctionComponent<ActionConnectorFieldsP
</>
}
/>
<EuiSpacer size="m" />
{hasTimeFieldCheckbox ? (
<>
<EuiSpacer size="m" />
<EuiFormRow
id="executionTimeField"
fullWidth
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
import React from 'react';
import { mountWithIntl } from 'test_utils/enzyme_helpers';
import ParamsFields from './es_index_params';
import { DocLinksStart } from 'kibana/public';

describe('IndexParamsFields renders', () => {
test('all params fields is rendered', () => {
Expand All @@ -18,6 +19,7 @@ describe('IndexParamsFields renders', () => {
errors={{ index: [] }}
editAction={() => {}}
index={0}
docLinks={{ ELASTIC_WEBSITE_URL: '', DOC_LINK_VERSION: '' } as DocLinksStart}
/>
);
expect(wrapper.find('[data-test-subj="documentsJsonEditor"]').first().prop('value')).toBe(`{
Expand Down
Loading

0 comments on commit 2009447

Please sign in to comment.