Skip to content

Commit

Permalink
[OAS] Add details for running Slack connector actions (#169712)
Browse files Browse the repository at this point in the history 
(cherry picked from commit 1b65592)
  • Loading branch information
@lcawl
lcawl committed Feb 13, 2024
1 parent fd2f4ee commit 2bb3087
Show file tree
Hide file tree
Showing 17 changed files with 669 additions and 5 deletions.
40 changes: 40 additions & 0 deletions docs/api/actions-and-connectors/execute.asciidoc
View file
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
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

0 comments on commit 2bb3087

Please sign in to comment.