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

[8.12] [OAS] Add details for running Slack connector actions (#169712) #176876

Merged
merged 2 commits into from
Mar 8, 2024
Merged

[8.12] [OAS] Add details for running Slack connector actions (#169712) #176876

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2bb3087
[OAS] Add details for running Slack connector actions (#169712)
lcawl Feb 13, 2024
d3b5f39
Merge branch '8.12' into backport/8.12/pr-169712
lcawl Feb 20, 2024
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
40 changes: 40 additions & 0 deletions docs/api/actions-and-connectors/execute.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -587,6 +587,46 @@ the security incident. The IPs are added as observables to the security incident
(Required, string) The message to log.
=====

.Slack connectors
[%collapsible%open]
=====
`message`::
(Required^*^, string) The Slack message text, which cannot contain Markdown, images, or other advanced formatting.
It is applicable only when the connector type is `.slack`.

`subAction`::
(Required^*^, string) The action to test.
It is applicable only when the connector type is `.slack_api`.
Valid values include: `postMessage`, `validChannelId`.
======

`subActionParams`::
(Required, object) The set of configuration properties, which vary depending
on the `subAction` value.
+
.Properties when `subAction` is `postMessage`
[%collapsible%open]
=======
`channelIds`:::
(Optional, array of strings) The Slack channel identifier, which must be one of the allowed channels in the connector configuration.

`channels`:::
(Optional, array of strings)
The name of a channel that your Slack app has access to. deprecated:[8.12.0]

`text`:::
(Optional, string) The Slack message text, which cannot contain Markdown, images, or other advanced formatting.
=======
+
.Properties when `subAction` is `validChannelId`
[%collapsible%open]
=======
`channelId`:::
(Required, string) The Slack channel identifier. For example, `C123ABC456`.
=======
======
=====

.{swimlane} connectors
[%collapsible%open]
=====
Expand Down
224 changes: 223 additions & 1 deletion 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 @@ -314,6 +314,9 @@
"runServiceNowITOMConnectorRequest": {
"$ref": "#/components/examples/run_servicenow_itom_connector_request"
},
"runSlackConnectorRequest": {
"$ref": "#/components/examples/run_slack_api_connector_request"
},
"runSwimlaneConnectorRequest": {
"$ref": "#/components/examples/run_swimlane_connector_request"
}
Expand Down Expand Up @@ -382,6 +385,9 @@
"runServiceNowITOMConnectorResponse": {
"$ref": "#/components/examples/run_servicenow_itom_connector_response"
},
"runSlackConnectorResponse": {
"$ref": "#/components/examples/run_slack_api_connector_response"
},
"runSwimlaneConnectorResponse": {
"$ref": "#/components/examples/run_swimlane_connector_response"
}
Expand Down Expand Up @@ -970,6 +976,9 @@
"runServiceNowITOMConnectorRequest": {
"$ref": "#/components/examples/run_servicenow_itom_connector_request"
},
"runSlackConnectorRequest": {
"$ref": "#/components/examples/run_slack_api_connector_request"
},
"runSwimlaneConnectorRequest": {
"$ref": "#/components/examples/run_swimlane_connector_request"
}
Expand Down Expand Up @@ -1009,6 +1018,12 @@
}
]
},
"message": {
"type": "string"
},
"service_message": {
"type": "string"
},
"status": {
"type": "string",
"description": "The status of the action.",
Expand All @@ -1032,6 +1047,9 @@
"runServiceNowITOMConnectorResponse": {
"$ref": "#/components/examples/run_servicenow_itom_connector_response"
},
"runSlackConnectorResponse": {
"$ref": "#/components/examples/run_slack_api_connector_response"
},
"runSwimlaneConnectorResponse": {
"$ref": "#/components/examples/run_swimlane_connector_response"
}
Expand Down Expand Up @@ -2570,6 +2588,38 @@
}
}
},
"config_properties_slack_api": {
"title": "Connector request properties for a Slack connector",
"description": "Defines properties for connectors when type is `.slack_api`.",
"type": "object",
"properties": {
"allowedChannels": {
"type": "array",
"description": "A list of valid Slack channels.",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"maxItems": 25,
"properties": {
"id": {
"type": "string",
"description": "The Slack channel ID.",
"example": "C123ABC456",
"minLength": 1
},
"name": {
"type": "string",
"description": "The Slack channel name.",
"minLength": 1
}
}
}
}
}
},
"secrets_properties_slack_api": {
"title": "Connector secrets properties for a Web API Slack connector",
"description": "Defines secrets for connectors when type is `.slack`.",
Expand All @@ -2586,14 +2636,17 @@
},
"create_connector_request_slack_api": {
"title": "Create Slack connector request",
"description": "The Slack connector uses Slack Incoming Webhooks.",
"description": "The Slack connector uses an API method to send Slack messages.",
"type": "object",
"required": [
"connector_type_id",
"name",
"secrets"
],
"properties": {
"config": {
"$ref": "#/components/schemas/config_properties_slack_api"
},
"connector_type_id": {
"type": "string",
"description": "The type of connector.",
Expand Down Expand Up @@ -4046,6 +4099,9 @@
"name"
],
"properties": {
"config": {
"$ref": "#/components/schemas/config_properties_slack_api"
},
"connector_type_id": {
"type": "string",
"description": "The type of connector.",
Expand Down Expand Up @@ -4717,6 +4773,9 @@
"secrets"
],
"properties": {
"config": {
"$ref": "#/components/schemas/config_properties_slack_api"
},
"name": {
"type": "string",
"description": "The display name for the connector."
Expand Down Expand Up @@ -5065,6 +5124,20 @@
}
}
},
"run_connector_params_message_slack": {
"title": "Slack connector parameters",
"description": "Test an action that sends a message to Slack. It is applicable only when the connector type is `.slack`.\n",
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "The Slack message text, which cannot contain Markdown, images, or other advanced formatting."
}
}
},
"run_connector_params_trigger_pagerduty": {
"title": "PagerDuty connector parameters",
"description": "Test an action that triggers a PagerDuty alert.",
Expand Down Expand Up @@ -5671,6 +5744,52 @@
}
}
},
"run_connector_subaction_postmessage": {
"title": "The postMessage subaction",
"type": "object",
"description": "Test an action that sends a message to Slack. It is applicable only when the connector type is `.slack_api`.\n",
"required": [
"subAction",
"subActionParams"
],
"properties": {
"subAction": {
"type": "string",
"description": "The action to test.",
"enum": [
"postMessage"
]
},
"subActionParams": {
"type": "object",
"description": "The set of configuration properties for the action.",
"properties": {
"channelIds": {
"type": "array",
"maxItems": 1,
"description": "The Slack channel identifier, which must be one of the `allowedChannels` in the connector configuration.\n",
"items": {
"type": "string"
}
},
"channels": {
"type": "array",
"deprecated": true,
"description": "The name of a channel that your Slack app has access to.\n",
"maxItems": 1,
"items": {
"type": "string"
}
},
"text": {
"type": "string",
"description": "The Slack message text, which cannot contain Markdown, images, or other advanced formatting.",
"minLength": 1
}
}
}
}
},
"run_connector_subaction_pushtoservice": {
"title": "The pushToService subaction",
"type": "object",
Expand Down Expand Up @@ -5858,6 +5977,37 @@
}
}
},
"run_connector_subaction_validchannelid": {
"title": "The validChannelId subaction",
"type": "object",
"description": "Retrieves information about a valid Slack channel identifier. It is applicable only when the connector type is `.slack_api`.\n",
"required": [
"subAction",
"subActionParams"
],
"properties": {
"subAction": {
"type": "string",
"description": "The action to test.",
"enum": [
"validChannelId"
]
},
"subActionParams": {
"type": "object",
"required": [
"channelId"
],
"properties": {
"channelId": {
"type": "string",
"description": "The Slack channel identifier.",
"example": "C123ABC456"
}
}
}
}
},
"run_connector_request": {
"title": "Run connector request body properties",
"description": "The properties vary depending on the connector type.",
Expand All @@ -5880,6 +6030,9 @@
{
"$ref": "#/components/schemas/run_connector_params_message_serverlog"
},
{
"$ref": "#/components/schemas/run_connector_params_message_slack"
},
{
"$ref": "#/components/schemas/run_connector_params_trigger_pagerduty"
},
Expand Down Expand Up @@ -5920,8 +6073,14 @@
{
"$ref": "#/components/schemas/run_connector_subaction_issuetypes"
},
{
"$ref": "#/components/schemas/run_connector_subaction_postmessage"
},
{
"$ref": "#/components/schemas/run_connector_subaction_pushtoservice"
},
{
"$ref": "#/components/schemas/run_connector_subaction_validchannelid"
}
],
"discriminator": {
Expand Down Expand Up @@ -6249,6 +6408,20 @@
}
}
},
"run_slack_api_connector_request": {
"summary": "Run a Slack connector that uses the web API method to post a message on a channel.",
"value": {
"params": {
"subAction": "postMessage",
"subActionParams": {
"channelIds": [
"C123ABC456"
],
"text": "A test message."
}
}
}
},
"run_swimlane_connector_request": {
"summary": "Run a Swimlane connector to create an incident.",
"value": {
Expand Down Expand Up @@ -6444,6 +6617,55 @@
"status": "ok"
}
},
"run_slack_api_connector_response": {
"summary": "Response from posting a message with a Slack connector.",
"value": {
"status": "ok",
"data": {
"ok": true,
"channel": "C123ABC456",
"ts": "1234567890.123456",
"message": {
"bot_id": "B12BCDEFGHI",
"type": "message",
"text": "A test message",
"user": "U12A345BC6D",
"ts": "1234567890.123456",
"app_id": "A01BC2D34EF",
"blocks": [
{
"type": "rich_text",
"block_id": "/NXe",
"elements": [
{
"type": "rich_text_section",
"elements": [
{
"type": "text",
"text": "A test message."
}
]
}
]
}
],
"team": "T01ABCDE2F",
"bot_profile": {
"id": "B12BCDEFGHI",
"app_id": "A01BC2D34EF",
"name": "test",
"icons": {
"image_36": "https://a.slack-edge.com/80588/img/plugins/app/bot_36.png"
},
"deleted": false,
"updated": 1672169705,
"team_id": "T01ABCDE2F"
}
}
},
"connector_id": ".slack_api"
}
},
"run_swimlane_connector_response": {
"summary": "Response from creating a Swimlane incident.",
"value": {
Expand Down
Loading