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

[RAM] Docs for slack improvements #153885

Merged
merged 32 commits into from
May 5, 2023
Merged

[RAM] Docs for slack improvements #153885

Show file tree
Hide file tree
Changes from 31 commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
3f88e68
add test which create auto snapshots for slack connector
guskovaue Mar 8, 2023
8d7ee38
add preconfigured web api connector section
guskovaue Mar 22, 2023
8815a62
create Configure a Slack account with Web AP
guskovaue Mar 28, 2023
81777d7
Merge branch 'main' into RAM-152880-change-docs-for-slack-improvements
guskovaue Mar 28, 2023
64f998b
addition to previous comment
guskovaue Mar 28, 2023
ef3df61
attempt to write openapi
guskovaue Mar 28, 2023
c6fbfea
[DOCS] Add enumerated data type in update_connector_request_slack.yaml
lcawl Mar 29, 2023
d42e63f
[DOCS] Uncomment update_connector_request_slack.yaml
lcawl Mar 29, 2023
b8b2397
[DOCS] Generate API doc output
lcawl Mar 29, 2023
005360e
Merge branch 'main' into RAM-152880-change-docs-for-slack-improvements
guskovaue Mar 29, 2023
c1d1fc9
[CI] Auto-commit changed files from 'node scripts/eslint --no-cache -…
kibanamachine Mar 29, 2023
156ee4c
write openapi docs
guskovaue Mar 29, 2023
bf55d9e
Merge branch 'RAM-152880-change-docs-for-slack-improvements' of githu…
guskovaue Mar 29, 2023
947291f
delete old file
guskovaue Mar 29, 2023
65c26c5
[DOCS] Re-add configuring-slack anchor
lcawl Mar 29, 2023
9ed200a
Merge branch 'main' into RAM-152880-change-docs-for-slack-improvements
guskovaue Apr 25, 2023
ef43470
[CI] Auto-commit changed files from 'node scripts/eslint --no-cache -…
kibanamachine Apr 25, 2023
7aeb227
Update docs/management/connectors/action-types/slack.asciidoc
guskovaue Apr 25, 2023
7c82f75
changes after separating slack connectors
guskovaue Apr 25, 2023
8a9d0c7
Merge branch 'main' into RAM-152880-change-docs-for-slack-improvements
guskovaue Apr 25, 2023
c1badca
test for automated screenshots
guskovaue Apr 27, 2023
f354bb2
change api docs
guskovaue Apr 27, 2023
739b7ce
[DOCS] Regenerate connector-apis-passthru.asciidoc
lcawl Apr 27, 2023
50a4f6b
uncomment what was commented
guskovaue Apr 28, 2023
6597de2
Merge branch 'RAM-152880-change-docs-for-slack-improvements' of githu…
guskovaue Apr 28, 2023
751ed10
[DOCS] Add automate screenshots
lcawl Apr 28, 2023
5276631
[DOCS] Describe differences between connector types
lcawl May 1, 2023
7a112a5
Merge branch 'main' into RAM-152880-change-docs-for-slack-improvements
lcawl May 2, 2023
4ba21d6
Edits slack connector message text
lcawl May 2, 2023
2032e4b
Edit channel validation message
lcawl May 2, 2023
eafb15c
Merge branch 'main' into RAM-152880-change-docs-for-slack-improvements
guskovaue May 3, 2023
0918ba9
fix a message line
guskovaue May 4, 2023
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
58 changes: 55 additions & 3 deletions docs/api-generated/connectors/connector-apis-passthru.asciidoc
View file
Open in desktop
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
85 changes: 57 additions & 28 deletions docs/management/connectors/action-types/slack.asciidoc
View file
Open in desktop
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,47 @@ 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 message text, converted to the `text` field in the Webhook JSON payload.
lcawl marked this conversation as resolved.
Show resolved Hide resolved
Currently only the text field is supported. Markdown, images, and other advanced formatting are not yet supported.

[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]]
lcawl marked this conversation as resolved.
Show resolved Hide resolved
==== 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.
lcawl marked this conversation as resolved.
Show resolved Hide resolved

[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
Open in desktop
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
Open in desktop
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
Open in desktop
Binary file not shown.
Binary file removed docs/management/connectors/images/slack-params-test.png
View file
Open in desktop
Binary file not shown.
Binary file added docs/management/connectors/images/slack-webhook-connector.png
View file
Open in desktop
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
Open in desktop
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