Skip to content

Commit

Permalink
[RAM] Docs for slack improvements (elastic#153885)
Browse files Browse the repository at this point in the history 
## Summary

Docs for new Slack connector

### Preview

https://kibana_153885.docs-preview.app.elstc.co/guide/en/kibana/master/slack-action-type.html

---------

Co-authored-by: lcawl <lcawley@elastic.co>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
(cherry picked from commit 4dd6d1a)
  • Loading branch information
@guskovaue
guskovaue committed May 5, 2023
1 parent e76daa4 commit ff73906
Show file tree
Hide file tree
Showing 25 changed files with 345 additions and 51 deletions.
58 changes: 55 additions & 3 deletions docs/api-generated/connectors/connector-apis-passthru.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -951,7 +951,8 @@ Any modifications made to this file will be overwritten.
<li><a href="#connector_response_properties_servicenow"><code>connector_response_properties_servicenow</code> - Connector response properties for a ServiceNow ITSM connector</a></li>
<li><a href="#connector_response_properties_servicenow_itom"><code>connector_response_properties_servicenow_itom</code> - Connector response properties for a ServiceNow ITOM connector</a></li>
<li><a href="#connector_response_properties_servicenow_sir"><code>connector_response_properties_servicenow_sir</code> - Connector response properties for a ServiceNow SecOps connector</a></li>
<li><a href="#connector_response_properties_slack"><code>connector_response_properties_slack</code> - Connector response properties for a Slack connector</a></li>
<li><a href="#connector_response_properties_slack_api"><code>connector_response_properties_slack_api</code> - Connector response properties for a Slack connector</a></li>
<li><a href="#connector_response_properties_slack_webhook"><code>connector_response_properties_slack_webhook</code> - Connector response properties for a Slack connector</a></li>
<li><a href="#connector_response_properties_swimlane"><code>connector_response_properties_swimlane</code> - Connector response properties for a Swimlane connector</a></li>
<li><a href="#connector_response_properties_teams"><code>connector_response_properties_teams</code> - Connector response properties for a Microsoft Teams connector</a></li>
<li><a href="#connector_response_properties_tines"><code>connector_response_properties_tines</code> - Connector response properties for a Tines connector</a></li>
Expand Down Expand Up @@ -1015,6 +1016,9 @@ Any modifications made to this file will be overwritten.
<li><a href="#secrets_properties_opsgenie"><code>secrets_properties_opsgenie</code> - Connector secrets properties for an Opsgenie connector</a></li>
<li><a href="#secrets_properties_resilient"><code>secrets_properties_resilient</code> - Connector secrets properties for IBM Resilient connector</a></li>
<li><a href="#secrets_properties_servicenow"><code>secrets_properties_servicenow</code> - Connector secrets properties for ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors</a></li>
<li><a href="#secrets_properties_slack"><code>secrets_properties_slack</code> - Connector secrets properties for a Slack connector</a></li>
<li><a href="#secrets_properties_slack_oneOf"><code>secrets_properties_slack_oneOf</code> - </a></li>
<li><a href="#secrets_properties_slack_oneOf_1"><code>secrets_properties_slack_oneOf_1</code> - </a></li>
<li><a href="#secrets_properties_swimlane"><code>secrets_properties_swimlane</code> - Connector secrets properties for a Swimlane connector</a></li>
<li><a href="#updateConnector_400_response"><code>updateConnector_400_response</code> - </a></li>
<li><a href="#update_connector_request_cases_webhook"><code>update_connector_request_cases_webhook</code> - Update Webhook - Case Managment connector request</a></li>
Expand All @@ -1025,6 +1029,7 @@ Any modifications made to this file will be overwritten.
<li><a href="#update_connector_request_serverlog"><code>update_connector_request_serverlog</code> - Update server log connector request</a></li>
<li><a href="#update_connector_request_servicenow"><code>update_connector_request_servicenow</code> - Update ServiceNow ITSM connector or ServiceNow SecOps request</a></li>
<li><a href="#update_connector_request_servicenow_itom"><code>update_connector_request_servicenow_itom</code> - Create ServiceNow ITOM connector request</a></li>
<li><a href="#update_connector_request_slack"><code>update_connector_request_slack</code> - Update Slack connector request</a></li>
<li><a href="#update_connector_request_swimlane"><code>update_connector_request_swimlane</code> - Update Swimlane connector request</a></li>
</ol>
Expand Down Expand Up @@ -1543,7 +1548,21 @@ Any modifications made to this file will be overwritten.
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="connector_response_properties_slack"><code>connector_response_properties_slack</code> - Connector response properties for a Slack connector</a> <a class="up" href="#__Models">Up</a></h3>
<h3><a name="connector_response_properties_slack_api"><code>connector_response_properties_slack_api</code> - Connector response properties for a Slack connector</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>
<div class="field-items">
<div class="param">connector_type_id </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The type of connector. </div>
<div class="param-enum-header">Enum:</div>
<div class="param-enum">.slack_api</div>
<div class="param">id </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The identifier for the connector. </div>
<div class="param">is_deprecated </div><div class="param-desc"><span class="param-type"><a href="#boolean">Boolean</a></span> Indicates whether the connector type is deprecated. </div>
<div class="param">is_missing_secrets (optional)</div><div class="param-desc"><span class="param-type"><a href="#boolean">Boolean</a></span> Indicates whether secrets are missing for the connector. Secrets configuration properties vary depending on the connector type. </div>
<div class="param">is_preconfigured </div><div class="param-desc"><span class="param-type"><a href="#boolean">Boolean</a></span> Indicates whether it is a preconfigured connector. If true, the <code>config</code> and <code>is_missing_secrets</code> properties are omitted from the response. </div>
<div class="param">name </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The display name for the connector. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="connector_response_properties_slack_webhook"><code>connector_response_properties_slack_webhook</code> - Connector response properties for a Slack connector</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>
<div class="field-items">
<div class="param">connector_type_id </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The type of connector. </div>
Expand Down Expand Up @@ -1773,7 +1792,7 @@ Any modifications made to this file will be overwritten.
<div class="param-enum-header">Enum:</div>
<div class="param-enum">.slack</div>
<div class="param">name </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The display name for the connector. </div>
<div class="param">secrets </div><div class="param-desc"><span class="param-type"><a href="#AnyType">map[String, oas_any_type_not_mapped]</a></span> Defines secrets for connectors when type is <code>.slack</code>. </div>
<div class="param">secrets </div><div class="param-desc"><span class="param-type"><a href="#secrets_properties_slack">secrets_properties_slack</a></span> </div>
</div> <!-- field-items -->
</div>
<div class="model">
Expand Down Expand Up @@ -2220,6 +2239,28 @@ Any modifications made to this file will be overwritten.
<div class="param">username (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The username for HTTP basic authentication. This property is required when <code>isOAuth</code> is <code>false</code>. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="secrets_properties_slack"><code>secrets_properties_slack</code> - Connector secrets properties for a Slack connector</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>Defines secrets for connectors when type is <code>.slack</code>.</div>
<div class="field-items">
<div class="param">token </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The Slack bot user OAuth token. </div>
<div class="param">webhookUrl </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The Slack webhook url. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="secrets_properties_slack_oneOf"><code>secrets_properties_slack_oneOf</code> - </a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>
<div class="field-items">
<div class="param">token </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The Slack bot user OAuth token. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="secrets_properties_slack_oneOf_1"><code>secrets_properties_slack_oneOf_1</code> - </a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>
<div class="field-items">
<div class="param">webhookUrl </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The Slack webhook url. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="secrets_properties_swimlane"><code>secrets_properties_swimlane</code> - Connector secrets properties for a Swimlane connector</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>Defines secrets for connectors when type is <code>.swimlane</code>.</div>
Expand Down Expand Up @@ -2305,6 +2346,17 @@ Any modifications made to this file will be overwritten.
<div class="param">secrets </div><div class="param-desc"><span class="param-type"><a href="#secrets_properties_servicenow">secrets_properties_servicenow</a></span> </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="update_connector_request_slack"><code>update_connector_request_slack</code> - Update Slack connector request</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>
<div class="field-items">
<div class="param">name </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The display name for the connector. </div>
<div class="param">config (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> </div>
<div class="param-enum-header">Enum:</div>
<div class="param-enum">web_api</div><div class="param-enum">webhook</div>
<div class="param">secrets </div><div class="param-desc"><span class="param-type"><a href="#secrets_properties_slack">secrets_properties_slack</a></span> </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3><a name="update_connector_request_swimlane"><code>update_connector_request_swimlane</code> - Update Swimlane connector request</a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'></div>
Expand Down
84 changes: 56 additions & 28 deletions docs/management/connectors/action-types/slack.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,48 +4,60 @@
<titleabbrev>Slack</titleabbrev>
++++

The Slack connector uses https://api.slack.com/incoming-webhooks[Slack Incoming Webhooks].
The Slack connector uses incoming webhooks or an API method to send Slack messages.

[float]
[[define-slack-ui]]
=== Create connectors in {kib}

You can create connectors in *{stack-manage-app} > {connectors-ui}*
or as needed when you're creating a rule. For example:
You can create connectors in *{stack-manage-app} > {connectors-ui}* or as needed when you're creating a rule.
You can choose to use a webhook URL that's specific to a single channel. For example:

[role="screenshot"]
image::management/connectors/images/slack-connector.png[Slack connector]
image::management/connectors/images/slack-webhook-connector.png[Slack connector]
// NOTE: This is an autogenerated screenshot. Do not edit it directly.

[float]
[[slack-connector-configuration]]
==== Connector configuration
Alternatively, you can create a connector that supports multiple channels. For example:

[role="screenshot"]
image::management/connectors/images/slack-api-connector.png[Slack API connector]
// NOTE: This is an autogenerated screenshot. Do not edit it directly.

Slack connectors have the following configuration properties:
If you use the latter method, you choose your channel when you create a rule action.
Thus a connector can be used in multiple rules and actions to communicate with different channels.

Name:: The name of the connector.
Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messaging/webhooks#getting_started[Slack Incoming Webhooks] for instructions on generating this URL. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
For Slack setup details, go to <<configuring-slack>>.

[float]
[[preconfigured-slack-configuration]]
=== Create preconfigured connectors

If you are running {kib} on-prem, you can define connectors by
adding `xpack.actions.preconfigured` settings to your `kibana.yml` file.
For example:

.Example Slack connector with webhook
[source,text]
--
xpack.actions.preconfigured:
my-slack:
name: preconfigured-slack-connector-type
name: preconfigured-slack-webhook-connector-type
actionTypeId: .slack
secrets:
webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz'
webhookUrl: 'https://hooks.slack.com/services/xxxx/xxxx/xxxx' <1>
--
<1> To obtain this value, go to <<configuring-slack-webhook>>.

Secrets defines sensitive information for the connector type.

`webhookUrl`:: A string that corresponds to *Webhook URL*.
.Example Slack connector with web API
[source,text]
--
xpack.actions.preconfigured:
my-slack:
name: preconfigured-slack-api-connector-type
actionTypeId: .slack_api
secrets:
token: 'xoxb-xxxx-xxxx-xxxx' <1>
--
<1> To obtain this value, go to <<configuring-slack-web-api>>.

[float]
[[slack-action-configuration]]
Expand All @@ -55,30 +67,46 @@ You can test connectors with the <<execute-connector-api,run connector API>> or
as you're creating or editing the connector in {kib}. For example:

[role="screenshot"]
image::management/connectors/images/slack-params-test.png[Slack params test]
image::management/connectors/images/slack-api-params.png[Slack API connector test]
// NOTE: This is an autogenerated screenshot. Do not edit it directly.

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.
Channels::
One or more channels that your Slack app has access to.
This option is available only in the web API type of connector.

Message:: The Slack message text, which cannot contain Markdown, images, or other advanced formatting.

[float]
[[slack-connector-networking-configuration]]
=== Connector networking configuration

Use the <<action-settings,Action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.
Use the <<action-settings,Action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings.
You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.

[float]
[[configuring-slack]]
==== Configure a Slack account
=== Configure a Slack account

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:
Before you can create a Slack connector, you must configure your account and obtain the necessary URL or token.

[float]
[[configuring-slack-webhook]]
==== Configure a Slack account for incoming webhooks

. 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*.
. Create a Slack app, enable incoming webhooks, then create an incoming webhook. Refer to https://api.slack.com/messaging/webhooks.
. Copy the generated webhook URL so you can paste it into your Slack connector form.
. If you are using the <<action-settings,`xpack.actions.allowedHosts`>> setting, make sure the hostname from the URL is added to the allowed hosts.

[float]
[[configuring-slack-web-api]]
==== Configure a Slack account for Web API

. Create a Slack app. Refer to https://api.slack.com/authentication/basics#creating.
. Add scope: `channels:read`, `groups:read`, `chat:write` and `chat:write.public`. Refer to https://api.slack.com/authentication/basics#scopes.
. Install the app to a workspace. Refer to https://api.slack.com/authentication/basics#installing.
. Copy the `Bot User OAuth Token` so you can paste it into your Slack connector form.
. If you need to send messages to a private channel, you need to write `/invite @App_name` in it.
Putting "@" triggers Slack to start auto-suggesting, which is why it then becomes easy to find your app name in the list.
Binary file added docs/management/connectors/images/slack-api-connector.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/management/connectors/images/slack-api-params.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/management/connectors/images/slack-connector.png
View file
Binary file not shown.
Binary file removed docs/management/connectors/images/slack-params-test.png
View file
Binary file not shown.
Binary file added docs/management/connectors/images/slack-webhook-connector.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
55 changes: 53 additions & 2 deletions x-pack/plugins/actions/docs/openapi/bundled.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,9 @@
{
"$ref": "#/components/schemas/update_connector_request_servicenow_itom"
},
{
"$ref": "#/components/schemas/update_connector_request_slack"
},
{
"$ref": "#/components/schemas/update_connector_request_swimlane"
}
Expand Down Expand Up @@ -1948,8 +1951,32 @@
"secrets_properties_slack": {
"title": "Connector secrets properties for a Slack connector",
"description": "Defines secrets for connectors when type is `.slack`.",
"type": "object",
"additionalProperties": true
"oneOf": [
{
"type": "object",
"required": [
"token"
],
"properties": {
"token": {
"type": "string",
"description": "The Slack bot user OAuth token."
}
}
},
{
"type": "object",
"required": [
"webhookUrl"
],
"properties": {
"webhookUrl": {
"type": "string",
"description": "The Slack webhook url."
}
}
}
]
},
"create_connector_request_slack": {
"title": "Create Slack connector request",
Expand Down Expand Up @@ -3348,6 +3375,30 @@
}
}
},
"update_connector_request_slack": {
"title": "Update Slack connector request",
"type": "object",
"required": [
"name",
"secrets"
],
"properties": {
"name": {
"type": "string",
"description": "The display name for the connector."
},
"config": {
"type": "string",
"enum": [
"web_api",
"webhook"
]
},
"secrets": {
"$ref": "#/components/schemas/secrets_properties_slack"
}
}
},
"update_connector_request_swimlane": {
"title": "Update Swimlane connector request",
"type": "object",
Expand Down
Loading

0 comments on commit ff73906

Please sign in to comment.