From 2bb30870ff020524cbfb2da3661dccf5ade854d4 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 13 Feb 2024 15:00:15 -0800 Subject: [PATCH] [OAS] Add details for running Slack connector actions (#169712) (cherry picked from commit 1b65592c0e77b71f897d83660f2c0a6e1c688a90) --- .../actions-and-connectors/execute.asciidoc | 40 ++++ .../plugins/actions/docs/openapi/bundled.json | 224 +++++++++++++++++- .../plugins/actions/docs/openapi/bundled.yaml | 161 ++++++++++++- .../docs/openapi/bundled_serverless.json | 43 +++- .../docs/openapi/bundled_serverless.yaml | 32 ++- .../run_slack_api_connector_request.yaml | 8 + .../run_slack_api_connector_response.yaml | 48 ++++ .../schemas/config_properties_slack_api.yaml | 23 ++ ...nnector_response_properties_slack_api.yaml | 2 + .../create_connector_request_slack_api.yaml | 4 +- .../run_connector_params_message_slack.yaml | 11 + .../schemas/run_connector_request.yaml | 3 + .../run_connector_subaction_postmessage.yaml | 38 +++ ...un_connector_subaction_validchannelid.yaml | 23 ++ .../update_connector_request_slack_api.yaml | 2 + ...ions@connector@{connectorid}@_execute.yaml | 4 + ...ions@connector@{connectorid}@_execute.yaml | 8 + 17 files changed, 669 insertions(+), 5 deletions(-) create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_slack_api_connector_request.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_slack_api_connector_response.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/config_properties_slack_api.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_message_slack.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_postmessage.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_validchannelid.yaml diff --git a/docs/api/actions-and-connectors/execute.asciidoc b/docs/api/actions-and-connectors/execute.asciidoc index aa04a0d6ef9b6..d820b5e2e122c 100644 --- a/docs/api/actions-and-connectors/execute.asciidoc +++ b/docs/api/actions-and-connectors/execute.asciidoc @@ -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] ===== diff --git a/x-pack/plugins/actions/docs/openapi/bundled.json b/x-pack/plugins/actions/docs/openapi/bundled.json index 635c0e9484192..c61742e9ffc6e 100644 --- a/x-pack/plugins/actions/docs/openapi/bundled.json +++ b/x-pack/plugins/actions/docs/openapi/bundled.json @@ -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" } @@ -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" } @@ -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" } @@ -1009,6 +1018,12 @@ } ] }, + "message": { + "type": "string" + }, + "service_message": { + "type": "string" + }, "status": { "type": "string", "description": "The status of the action.", @@ -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" } @@ -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`.", @@ -2586,7 +2636,7 @@ }, "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", @@ -2594,6 +2644,9 @@ "secrets" ], "properties": { + "config": { + "$ref": "#/components/schemas/config_properties_slack_api" + }, "connector_type_id": { "type": "string", "description": "The type of connector.", @@ -4046,6 +4099,9 @@ "name" ], "properties": { + "config": { + "$ref": "#/components/schemas/config_properties_slack_api" + }, "connector_type_id": { "type": "string", "description": "The type of connector.", @@ -4717,6 +4773,9 @@ "secrets" ], "properties": { + "config": { + "$ref": "#/components/schemas/config_properties_slack_api" + }, "name": { "type": "string", "description": "The display name for the connector." @@ -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.", @@ -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", @@ -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.", @@ -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" }, @@ -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": { @@ -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": { @@ -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": { diff --git a/x-pack/plugins/actions/docs/openapi/bundled.yaml b/x-pack/plugins/actions/docs/openapi/bundled.yaml index 295b9bfbb0308..fe1a02864d8e9 100644 --- a/x-pack/plugins/actions/docs/openapi/bundled.yaml +++ b/x-pack/plugins/actions/docs/openapi/bundled.yaml @@ -192,6 +192,8 @@ paths: $ref: '#/components/examples/run_server_log_connector_request' 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' responses: @@ -236,6 +238,8 @@ paths: $ref: '#/components/examples/run_server_log_connector_response' 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' '401': @@ -607,6 +611,8 @@ paths: $ref: '#/components/examples/run_server_log_connector_request' 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' responses: @@ -632,6 +638,10 @@ paths: description: An array of information returned from the action. items: type: object + message: + type: string + service_message: + type: string status: type: string description: The status of the action. @@ -647,6 +657,8 @@ paths: $ref: '#/components/examples/run_server_log_connector_response' 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' '401': @@ -1766,6 +1778,30 @@ components: - my-connector secrets: $ref: '#/components/schemas/secrets_properties_servicenow' + 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`. @@ -1778,13 +1814,15 @@ components: description: Slack bot user OAuth token. 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. @@ -2837,6 +2875,8 @@ components: - is_preconfigured - name properties: + config: + $ref: '#/components/schemas/config_properties_slack_api' connector_type_id: type: string description: The type of connector. @@ -3291,6 +3331,8 @@ components: - name - secrets properties: + config: + $ref: '#/components/schemas/config_properties_slack_api' name: type: string description: The display name for the connector. @@ -3517,6 +3559,17 @@ components: message: type: string description: The message for server log connectors. + 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`. + 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. @@ -3952,6 +4005,43 @@ components: description: The action to test. enum: - issueTypes + 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`. + 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. + items: + type: string + channels: + type: array + deprecated: true + description: | + The name of a channel that your Slack app has access to. + 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 @@ -4082,6 +4172,29 @@ components: urgency: type: string description: The urgency of the incident for ServiceNow ITSM connectors. + 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`. + 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. @@ -4095,6 +4208,7 @@ components: - $ref: '#/components/schemas/run_connector_params_documents' - $ref: '#/components/schemas/run_connector_params_message_email' - $ref: '#/components/schemas/run_connector_params_message_serverlog' + - $ref: '#/components/schemas/run_connector_params_message_slack' - $ref: '#/components/schemas/run_connector_params_trigger_pagerduty' - title: Subaction parameters description: Test an action that involves a subaction. @@ -4110,7 +4224,9 @@ components: - $ref: '#/components/schemas/run_connector_subaction_issue' - $ref: '#/components/schemas/run_connector_subaction_issues' - $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: propertyName: subAction features: @@ -4354,6 +4470,15 @@ components: fields: - severity - urgency + 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: @@ -4486,6 +4611,40 @@ components: label: 3 - Low value: 3 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: diff --git a/x-pack/plugins/actions/docs/openapi/bundled_serverless.json b/x-pack/plugins/actions/docs/openapi/bundled_serverless.json index 769fdf2d258e9..f627a8364caa4 100644 --- a/x-pack/plugins/actions/docs/openapi/bundled_serverless.json +++ b/x-pack/plugins/actions/docs/openapi/bundled_serverless.json @@ -1562,6 +1562,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`.", @@ -1578,7 +1610,7 @@ }, "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", @@ -1586,6 +1618,9 @@ "secrets" ], "properties": { + "config": { + "$ref": "#/components/schemas/config_properties_slack_api" + }, "connector_type_id": { "type": "string", "description": "The type of connector.", @@ -3038,6 +3073,9 @@ "name" ], "properties": { + "config": { + "$ref": "#/components/schemas/config_properties_slack_api" + }, "connector_type_id": { "type": "string", "description": "The type of connector.", @@ -3709,6 +3747,9 @@ "secrets" ], "properties": { + "config": { + "$ref": "#/components/schemas/config_properties_slack_api" + }, "name": { "type": "string", "description": "The display name for the connector." diff --git a/x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml b/x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml index 15a9dfb0be293..34532a85099bc 100644 --- a/x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml +++ b/x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml @@ -1129,6 +1129,30 @@ components: - my-connector secrets: $ref: '#/components/schemas/secrets_properties_servicenow' + 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`. @@ -1141,13 +1165,15 @@ components: description: Slack bot user OAuth token. 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. @@ -2200,6 +2226,8 @@ components: - is_preconfigured - name properties: + config: + $ref: '#/components/schemas/config_properties_slack_api' connector_type_id: type: string description: The type of connector. @@ -2654,6 +2682,8 @@ components: - name - secrets properties: + config: + $ref: '#/components/schemas/config_properties_slack_api' name: type: string description: The display name for the connector. diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_slack_api_connector_request.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_slack_api_connector_request.yaml new file mode 100644 index 0000000000000..929a0d2c7b57c --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_slack_api_connector_request.yaml @@ -0,0 +1,8 @@ +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. \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_slack_api_connector_response.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_slack_api_connector_response.yaml new file mode 100644 index 0000000000000..d600bb190e870 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_slack_api_connector_response.yaml @@ -0,0 +1,48 @@ +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" + } diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/config_properties_slack_api.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/config_properties_slack_api.yaml new file mode 100644 index 0000000000000..4e3e5d3bfe7d8 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/config_properties_slack_api.yaml @@ -0,0 +1,23 @@ +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 diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/connector_response_properties_slack_api.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/connector_response_properties_slack_api.yaml index 56c4f488a35af..49f266ae6a3bb 100644 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/connector_response_properties_slack_api.yaml +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/connector_response_properties_slack_api.yaml @@ -7,6 +7,8 @@ required: - is_preconfigured - name properties: + config: + $ref: 'config_properties_slack_api.yaml' connector_type_id: type: string description: The type of connector. diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/create_connector_request_slack_api.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/create_connector_request_slack_api.yaml index 07dbadbef9891..2044087fba78c 100644 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/create_connector_request_slack_api.yaml +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/create_connector_request_slack_api.yaml @@ -1,11 +1,13 @@ 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: 'config_properties_slack_api.yaml' connector_type_id: type: string description: The type of connector. diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_message_slack.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_message_slack.yaml new file mode 100644 index 0000000000000..a5e0c999df151 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_message_slack.yaml @@ -0,0 +1,11 @@ +title: Slack connector parameters +description: > + Test an action that sends a message to Slack. + It is applicable only when the connector type is `.slack`. +type: object +required: + - message +properties: + message: + type: string + description: The Slack message text, which cannot contain Markdown, images, or other advanced formatting. diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_request.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_request.yaml index a3764b93a642e..e82d2419713da 100644 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_request.yaml +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_request.yaml @@ -10,6 +10,7 @@ properties: - $ref: 'run_connector_params_documents.yaml' - $ref: 'run_connector_params_message_email.yaml' - $ref: 'run_connector_params_message_serverlog.yaml' + - $ref: 'run_connector_params_message_slack.yaml' - $ref: 'run_connector_params_trigger_pagerduty.yaml' - title: Subaction parameters description: Test an action that involves a subaction. @@ -25,6 +26,8 @@ properties: - $ref: 'run_connector_subaction_issue.yaml' - $ref: 'run_connector_subaction_issues.yaml' - $ref: 'run_connector_subaction_issuetypes.yaml' + - $ref: 'run_connector_subaction_postmessage.yaml' - $ref: 'run_connector_subaction_pushtoservice.yaml' + - $ref: 'run_connector_subaction_validchannelid.yaml' discriminator: propertyName: subAction \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_postmessage.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_postmessage.yaml new file mode 100644 index 0000000000000..ef2730169f416 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_postmessage.yaml @@ -0,0 +1,38 @@ +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`. +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. + items: + type: string + channels: + type: array + deprecated: true + description: > + The name of a channel that your Slack app has access to. + maxItems: 1 + items: + type: string + text: + type: string + description: The Slack message text, which cannot contain Markdown, images, or other advanced formatting. + minLength: 1 + \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_validchannelid.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_validchannelid.yaml new file mode 100644 index 0000000000000..3b8babe7f7a4a --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_validchannelid.yaml @@ -0,0 +1,23 @@ +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`. +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 diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/update_connector_request_slack_api.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/update_connector_request_slack_api.yaml index 1a0c99c1847a0..dd9f0986618f9 100644 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/update_connector_request_slack_api.yaml +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/update_connector_request_slack_api.yaml @@ -4,6 +4,8 @@ required: - name - secrets properties: + config: + $ref: 'config_properties_slack_api.yaml' name: type: string description: The display name for the connector. diff --git a/x-pack/plugins/actions/docs/openapi/paths/api@actions@connector@{connectorid}@_execute.yaml b/x-pack/plugins/actions/docs/openapi/paths/api@actions@connector@{connectorid}@_execute.yaml index a276f30292daf..18d4b93d0102b 100644 --- a/x-pack/plugins/actions/docs/openapi/paths/api@actions@connector@{connectorid}@_execute.yaml +++ b/x-pack/plugins/actions/docs/openapi/paths/api@actions@connector@{connectorid}@_execute.yaml @@ -29,6 +29,8 @@ post: $ref: '../components/examples/run_server_log_connector_request.yaml' runServiceNowITOMConnectorRequest: $ref: '../components/examples/run_servicenow_itom_connector_request.yaml' + runSlackConnectorRequest: + $ref: '../components/examples/run_slack_api_connector_request.yaml' runSwimlaneConnectorRequest: $ref: '../components/examples/run_swimlane_connector_request.yaml' responses: @@ -73,6 +75,8 @@ post: $ref: '../components/examples/run_server_log_connector_response.yaml' runServiceNowITOMConnectorResponse: $ref: '../components/examples/run_servicenow_itom_connector_response.yaml' + runSlackConnectorResponse: + $ref: '../components/examples/run_slack_api_connector_response.yaml' runSwimlaneConnectorResponse: $ref: '../components/examples/run_swimlane_connector_response.yaml' '401': diff --git a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml index be5fbd42e588a..507194f31c380 100644 --- a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml +++ b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml @@ -26,6 +26,8 @@ post: $ref: '../components/examples/run_server_log_connector_request.yaml' runServiceNowITOMConnectorRequest: $ref: '../components/examples/run_servicenow_itom_connector_request.yaml' + runSlackConnectorRequest: + $ref: '../components/examples/run_slack_api_connector_request.yaml' runSwimlaneConnectorRequest: $ref: '../components/examples/run_swimlane_connector_request.yaml' responses: @@ -51,6 +53,10 @@ post: description: An array of information returned from the action. items: type: object + message: + type: string + service_message: + type: string status: type: string description: The status of the action. @@ -66,6 +72,8 @@ post: $ref: '../components/examples/run_server_log_connector_response.yaml' runServiceNowITOMConnectorResponse: $ref: '../components/examples/run_servicenow_itom_connector_response.yaml' + runSlackConnectorResponse: + $ref: '../components/examples/run_slack_api_connector_response.yaml' runSwimlaneConnectorResponse: $ref: '../components/examples/run_swimlane_connector_response.yaml' '401':