--- type: api title: Run a connector description: You can use this API to test an action that involves interaction with Kibana services or integrations with third-party systems. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v0/operation/operation-post-actions-connector-id-execute resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v0/operation/operation-post-actions-connector-id-execute products: - Kibana --- # Run a connector - Server: `https://{kibana_url}` ## Paths - `POST` `/api/actions/connector/{id}/_execute` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v0/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v0/authentication#basicauth) #### Path Parameters - `id` (string) An identifier for the connector. ## Description You can use this API to test an action that involves interaction with Kibana services or integrations with third-party systems. ## Request Body `application/json` - `params` (union oneOf) — required - **run_acknowledge_resolve_pagerduty** Test an action that acknowledges or resolves a PagerDuty alert. - `dedupKey` (string · max: 255) — required The deduplication key for the PagerDuty alert. - `eventAction` (enum) — required The type of event. Values: `acknowledge`, `resolve` - **run_documents** Test an action that indexes a document into Elasticsearch. - `documents` ([] object) — required The documents in JSON format for index connectors. - **run_message_email** Test an action that sends an email message. There must be at least one recipient in `to`, `cc`, or `bcc`. - `bcc` ([] string) — optional A list of "blind carbon copy" email addresses. Addresses can be specified in `user@host-name` format or in name `` format - `cc` ([] string) — optional A list of "carbon copy" email addresses. Addresses can be specified in `user@host-name` format or in name `` format - `message` (string) — required The email message text. Markdown format is supported. - `subject` (string) — required The subject line of the email. - `to` ([] string) — optional A list of email addresses. Addresses can be specified in `user@host-name` format or in name `` format. - **run_message_serverlog** Test an action that writes an entry to the Kibana server log. - `level` (enum · default: info) — optional The log level of the message for server log connectors. Values: `debug`, `error`, `fatal`, `info`, `trace`, `warn` - `message` (string) — required The message for server log connectors. - **run_message_slack** Test an action that sends a message to Slack. It is applicable only when the connector type is `.slack`. - `message` (string) — required The Slack message text, which cannot contain Markdown, images, or other advanced formatting. - **run_trigger_pagerduty** Test an action that triggers a PagerDuty alert. - `class` (string) — optional The class or type of the event. - `component` (string) — optional The component of the source machine that is responsible for the event. - `customDetails` (object) — optional Additional details to add to the event. - `dedupKey` (string · max: 255) — optional All actions sharing this key will be associated with the same PagerDuty alert. This value is used to correlate trigger and resolution. - `eventAction` (enum) — required The type of event. Values: `trigger` - `group` (string) — optional The logical grouping of components of a service. - `links` ([] object) — optional A list of links to add to the event. - `href` (string) — optional The URL for the link. - `text` (string) — optional A plain text description of the purpose of the link. - `severity` (enum · default: info) — optional The severity of the event on the affected system. Values: `critical`, `error`, `info`, `warning` - `source` (string) — optional The affected system, such as a hostname or fully qualified domain name. Defaults to the Kibana saved object id of the action. - `summary` (string · max: 1024) — optional A summery of the event. - `timestamp` (string) — optional An ISO-8601 timestamp that indicates when the event was detected or generated. - **run_addevent** The `addEvent` subaction for ServiceNow ITOM connectors. - `subAction` (enum) — required The action to test. Values: `addEvent` - `subActionParams` (object) — optional The set of configuration properties for the action. - `additional_info` (string) — optional Additional information about the event. - `description` (string) — optional The details about the event. - `event_class` (string) — optional A specific instance of the source. - `message_key` (string) — optional All actions sharing this key are associated with the same ServiceNow alert. The default value is `:`. - `metric_name` (string) — optional The name of the metric. - `node` (string) — optional The host that the event was triggered for. - `resource` (string) — optional The name of the resource. - `severity` (string) — optional The severity of the event. - `source` (string) — optional The name of the event source type. - `time_of_event` (string) — optional The time of the event. - `type` (string) — optional The type of event. - **run_closealert** The `closeAlert` subaction for Opsgenie connectors. - `subAction` (enum) — required The action to test. Values: `closeAlert` - `subActionParams` (object) — required - `alias` (string) — required The unique identifier used for alert deduplication in Opsgenie. The alias must match the value used when creating the alert. - `note` (string) — optional Additional information for the alert. - `source` (string) — optional The display name for the source of the alert. - `user` (string) — optional The display name for the owner. - **run_closeincident** The `closeIncident` subaction for ServiceNow ITSM connectors. - `subAction` (enum) — required The action to test. Values: `closeIncident` - `subActionParams` (object) — required - `incident` (object) — required Requires at least one of: `correlation_id` or `externalId` - `correlation_id` (string · max: 100 · default: {{rule.id}}:{{alert.id}}) — optional — nullable An identifier that is assigned to the incident when it is created by the connector. NOTE: If you use the default value and the rule generates multiple alerts that use the same alert IDs, the latest open incident for this correlation ID is closed unless you specify the external ID. - `externalId` (string) — optional — nullable The unique identifier (`incidentId`) for the incident in ServiceNow. - **run_createalert** The `createAlert` subaction for Opsgenie and TheHive connectors. - `subAction` (enum) — required The action to test. Values: `createAlert` - `subActionParams` (object) — required - `actions` ([] string) — optional The custom actions available to the alert in Opsgenie connectors. - `alias` (string) — optional The unique identifier used for alert deduplication in Opsgenie. - `description` (string) — optional A description that provides detailed information about the alert. - `details` (object) — optional The custom properties of the alert in Opsgenie connectors. - `entity` (string) — optional The domain of the alert in Opsgenie connectors. For example, the application or server name. - `message` (string) — optional The alert message in Opsgenie connectors. - `note` (string) — optional Additional information for the alert in Opsgenie connectors. - `priority` (enum) — optional The priority level for the alert in Opsgenie connectors. Values: `P1`, `P2`, `P3`, `P4`, `P5` - `responders` ([] object) — optional The entities to receive notifications about the alert in Opsgenie connectors. If `type` is `user`, either `id` or `username` is required. If `type` is `team`, either `id` or `name` is required. - `id` (string) — optional The identifier for the entity. - `name` (string) — optional The name of the entity. - `type` (enum) — optional The type of responders, in this case `escalation`. Values: `escalation`, `schedule`, `team`, `user` - `username` (string) — optional A valid email address for the user. - `severity` (integer · min: 1 · max: 4) — optional The severity of the incident for TheHive connectors. The value ranges from 1 (low) to 4 (critical) with a default value of 2 (medium). - `source` (string) — optional The display name for the source of the alert in Opsgenie and TheHive connectors. - `sourceRef` (string) — optional A source reference for the alert in TheHive connectors. - `tags` ([] string) — optional The tags for the alert in Opsgenie and TheHive connectors. - `title` (string) — optional A title for the incident for TheHive connectors. It is used for searching the contents of the knowledge base. - `tlp` (integer · min: 0 · max: 4 · default: 2) — optional The traffic light protocol designation for the incident in TheHive connectors. Valid values include: 0 (clear), 1 (green), 2 (amber), 3 (amber and strict), and 4 (red). - `type` (string) — optional The type of alert in TheHive connectors. - `user` (string) — optional The display name for the owner. - `visibleTo` ([] object) — optional The teams and users that the alert will be visible to without sending a notification. Only one of `id`, `name`, or `username` is required. - `id` (string) — optional The identifier for the entity. - `name` (string) — optional The name of the entity. - `type` (enum) — required Valid values are `team` and `user`. Values: `team`, `user` - `username` (string) — optional The user name. This property is required only when the `type` is `user`. - **run_fieldsbyissuetype** The `fieldsByIssueType` subaction for Jira connectors. - `subAction` (enum) — required The action to test. Values: `fieldsByIssueType` - `subActionParams` (object) — required - `id` (string) — required The Jira issue type identifier. - **run_getagentdetails** The `getAgentDetails` subaction for CrowdStrike connectors. - `subAction` (enum) — required The action to test. Values: `getAgentDetails` - `subActionParams` (object) — required The set of configuration properties for the action. - `ids` ([] string) — required An array of CrowdStrike agent identifiers. - **run_getagents** The `getAgents` subaction for SentinelOne connectors. - `subAction` (enum) — required The action to test. Values: `getAgents` - **run_getchoices** The `getChoices` subaction for ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors. - `subAction` (enum) — required The action to test. Values: `getChoices` - `subActionParams` (object) — required The set of configuration properties for the action. - `fields` ([] string) — required An array of fields. - **run_getfields** The `getFields` subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors. - `subAction` (enum) — required The action to test. Values: `getFields` - **run_getincident** The `getIncident` subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors. - `subAction` (enum) — required The action to test. Values: `getIncident` - `subActionParams` (object) — required - `externalId` (string) — required The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. - **run_issue** The `issue` subaction for Jira connectors. - `subAction` (enum) — required The action to test. Values: `issue` - `subActionParams` (object) — optional - `id` (string) — required The Jira issue identifier. - **run_issues** The `issues` subaction for Jira connectors. - `subAction` (enum) — required The action to test. Values: `issues` - `subActionParams` (object) — required - `title` (string) — required The title of the Jira issue. - **run_issuetypes** The `issueTypes` subaction for Jira connectors. - `subAction` (enum) — required The action to test. Values: `issueTypes` - **run_postmessage** Test an action that sends a message to Slack. It is applicable only when the connector type is `.slack_api`. - `subAction` (enum) — required The action to test. Values: `postMessage` - `subActionParams` (object) — required The set of configuration properties for the action. - `channelIds` ([] string · max: 1) — optional The Slack channel identifier, which must be one of the `allowedChannels` in the connector configuration. - `channels` ([] string · max: 1) — optional — deprecated The name of a channel that your Slack app has access to. - `text` (string · min: 1) — optional The Slack message text. If it is a Slack webhook connector, the text cannot contain Markdown, images, or other advanced formatting. If it is a Slack web API connector, it can contain either plain text or block kit messages. - **run_pushtoservice** The `pushToService` subaction for Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, TheHive, and Webhook - Case Management connectors. - `subAction` (enum) — required The action to test. Values: `pushToService` - `subActionParams` (object) — required The set of configuration properties for the action. - `comments` ([] object) — optional Additional information that is sent to Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, or TheHive. - `comment` (string) — optional A comment related to the incident. For example, describe how to troubleshoot the issue. - `commentId` (integer) — optional A unique identifier for the comment. - `incident` (object) — optional Information necessary to create or update a Jira, ServiceNow ITSM, ServiveNow SecOps, Swimlane, or TheHive incident. - `additional_fields` (string · max: 20) — optional — nullable Additional fields for ServiceNow ITSM and ServiveNow SecOps connectors. The fields must exist in the Elastic ServiceNow application and must be specified in JSON format. - `alertId` (string) — optional The alert identifier for Swimlane connectors. - `caseId` (string) — optional The case identifier for the incident for Swimlane connectors. - `caseName` (string) — optional The case name for the incident for Swimlane connectors. - `category` (string) — optional The category of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. - `correlation_display` (string) — optional A descriptive label of the alert for correlation purposes for ServiceNow ITSM and ServiceNow SecOps connectors. - `correlation_id` (string) — optional The correlation identifier for the security incident for ServiceNow ITSM and ServiveNow SecOps connectors. Connectors using the same correlation ID are associated with the same ServiceNow incident. This value determines whether a new ServiceNow incident is created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as ``{{ruleID}}`:`{{alert ID}}`` to form the correlation ID value in ServiceNow. The maximum character length for this value is 100 characters. NOTE: Using the default configuration of ``{{ruleID}}`:`{{alert ID}}`` ensures that ServiceNow creates a separate incident record for every generated alert that uses a unique alert ID. If the rule generates multiple alerts that use the same alert IDs, ServiceNow creates and continually updates a single incident record for the alert. - `description` (string) — optional The description of the incident for Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, TheHive, and Webhook - Case Management connectors. - `dest_ip` (union string | [] string) — optional A list of destination IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident. - `externalId` (string) — optional The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. If present, the incident is updated. Otherwise, a new incident is created. - `id` (string) — optional The external case identifier for Webhook - Case Management connectors. - `impact` (string) — optional The impact of the incident for ServiceNow ITSM connectors. - `issueType` (integer) — optional The type of incident for Jira connectors. For example, 10006. To obtain the list of valid values, set `subAction` to `issueTypes`. - `labels` ([] string) — optional The labels for the incident for Jira connectors. NOTE: Labels cannot contain spaces. - `malware_hash` (union string | [] string) — optional A list of malware hashes related to the security incident for ServiceNow SecOps connectors. The hashes are added as observables to the security incident. - `malware_url` (union string | [] string) — optional A list of malware URLs related to the security incident for ServiceNow SecOps connectors. The URLs are added as observables to the security incident. - `otherFields` (object) — optional Custom field identifiers and their values for Jira connectors. - `parent` (string) — optional The ID or key of the parent issue for Jira connectors. Applies only to `Sub-task` types of issues. - `priority` (string) — optional The priority of the incident in Jira and ServiceNow SecOps connectors. - `ruleName` (string) — optional The rule name for Swimlane connectors. - `severity` (integer) — optional The severity of the incident for ServiceNow ITSM, Swimlane, and TheHive connectors. In TheHive connectors, the severity value ranges from 1 (low) to 4 (critical) with a default value of 2 (medium). - `short_description` (string) — optional A short description of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. It is used for searching the contents of the knowledge base. - `source_ip` (union string | [] string) — optional A list of source IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident. - `status` (string) — optional The status of the incident for Webhook - Case Management connectors. - `subcategory` (string) — optional The subcategory of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. - `summary` (string) — optional A summary of the incident for Jira connectors. - `tags` ([] string) — optional A list of tags for TheHive and Webhook - Case Management connectors. - `title` (string) — optional A title for the incident for Jira, TheHive, and Webhook - Case Management connectors. It is used for searching the contents of the knowledge base. - `tlp` (integer · min: 0 · max: 4 · default: 2) — optional The traffic light protocol designation for the incident in TheHive connectors. Valid values include: 0 (clear), 1 (green), 2 (amber), 3 (amber and strict), and 4 (red). - `urgency` (string) — optional The urgency of the incident for ServiceNow ITSM connectors. - **run_validchannelid** Retrieves information about a valid Slack channel identifier. It is applicable only when the connector type is `.slack_api`. - `subAction` (enum) — required The action to test. Values: `validChannelId` - `subActionParams` (object) — required - `channelId` (string) — required The Slack channel identifier. ## Responses #### `200` Indicates a successful call. `application/json` - `auth_mode` (enum) The authentication mode used for the connector. Values: `shared`, `per-user` - `config` (map string to object) - `connector_type_id` (string) The connector type identifier. - `id` (string) The identifier for the connector. - `is_connector_type_deprecated` (boolean) Indicates whether the connector type is deprecated. - `is_deprecated` (boolean) Indicates whether the connector is deprecated. - `is_missing_secrets` (boolean) Indicates whether the connector is missing secrets. - `is_preconfigured` (boolean) Indicates whether the connector is preconfigured. If true, the `config` and `is_missing_secrets` properties are omitted from the response. - `is_system_action` (boolean) Indicates whether the connector is used for system actions. - `name` (string) The name of the connector. #### `403` Indicates that this call is forbidden. ## Code Examples #### Console ```console POST /api/actions/connector/{id}/_execute { "params": { "documents": [ { "id": "my_doc_id", "name": "my_doc_name", "message": "hello, world" } ] } } ``` #### curl ```curl curl -X POST "https://{kibana_url}/api/actions/connector/{id}/_execute" \ -H "kbn-xsrf: true" \ -H "Content-Type: application/json" \ -d '{ "params": { "documents": [ { "id": "my_doc_id", "name": "my_doc_name", "message": "hello, world" } ] } }' ``` ## Response Examples #### Response from running an index connector. ```json { "connector_id": "fd38c600-96a5-11ed-bb79-353b74189cba", "data": { "errors": false, "items": [ { "create": { "_id": "4JtvwYUBrcyxt2NnfW3y", "_index": "my-index", "_primary_term": 1, "_seq_no": 0, "_shards": { "failed": 0, "successful": 1, "total": 2 }, "_version": 1, "result": "created", "status": 201 } } ], "took": 135 }, "status": "ok" } ``` #### Response from retrieving the list of issue types for a Jira connector. ```json { "connector_id": "b3aad810-edbe-11ec-82d1-11348ecbf4a6", "data": [ { "id": 10024, "name": "Improvement" }, { "id": 10006, "name": "Task" }, { "id": 10007, "name": "Sub-task" }, { "id": 10025, "name": "New Feature" }, { "id": 10023, "name": "Bug" }, { "id": 10000, "name": "Epic" } ], "status": "ok" } ``` #### Response from running a server log connector. ```json { "connector_id": "7fc7b9a0-ecc9-11ec-8736-e7d63118c907", "status": "ok" } ``` #### Response from retrieving the list of choices for a ServiceNow ITOM connector. ```json { "connector_id": "9d9be270-2fd2-11ed-b0e0-87533c532698", "data": [ { "dependent_value": "", "element": "severity", "label": "Critical", "value": 1 }, { "dependent_value": "", "element": "severity", "label": "Major", "value": 2 }, { "dependent_value": "", "element": "severity", "label": "Minor", "value": 3 }, { "dependent_value": "", "element": "severity", "label": "Warning", "value": 4 }, { "dependent_value": "", "element": "severity", "label": "OK", "value": 5 }, { "dependent_value": "", "element": "severity", "label": "Clear", "value": 0 }, { "dependent_value": "", "element": "urgency", "label": "1 - High", "value": 1 }, { "dependent_value": "", "element": "urgency", "label": "2 - Medium", "value": 2 }, { "dependent_value": "", "element": "urgency", "label": "3 - Low", "value": 3 } ], "status": "ok" } ``` #### Response from posting a message with a Slack connector. ```json { "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" } ``` #### Response from creating a Swimlane incident. ```json { "connector_id": "a4746470-2f94-11ed-b0e0-87533c532698", "data": { "id": "aKPmBHWzmdRQtx6Mx", "title": "TEST-457", "url": "https://elastic.swimlane.url.us/record/aNcL2xniGHGpa2AHb/aKPmBHWzmdRQtx6Mx", "pushedDate": "2022-09-08T16:52:27.866Z", "comments": [ { "commentId": 1, "pushedDate": "2022-09-08T16:52:27.865Z" } ] }, "status": "ok" } ```