From d559c99c6261d4f5c5648f378ab7eb371d25a64b Mon Sep 17 00:00:00 2001 From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Date: Tue, 23 Feb 2021 23:44:00 -0500 Subject: [PATCH] [Actions][Doc] Clean up Actions README (#91789) (#92556) * Removing REST API from README. Updating configuration docs * Updating action config docs * Cleaning up action type configs in README and user docs * Cleaning up action type configs in README and user docs * Fixing formatting * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * PR fixes * Update x-pack/plugins/actions/README.md Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: ymao1 Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- .../user/alerting/action-types/email.asciidoc | 20 +- .../user/alerting/action-types/index.asciidoc | 4 +- docs/user/alerting/action-types/jira.asciidoc | 50 +- .../alerting/action-types/pagerduty.asciidoc | 23 +- .../alerting/action-types/resilient.asciidoc | 33 +- .../alerting/action-types/server-log.asciidoc | 1 + .../alerting/action-types/servicenow.asciidoc | 37 +- .../user/alerting/action-types/slack.asciidoc | 14 +- .../user/alerting/action-types/teams.asciidoc | 14 +- .../alerting/action-types/webhook.asciidoc | 17 +- docs/user/alerting/defining-alerts.asciidoc | 5 +- x-pack/plugins/actions/README.md | 561 ++---------------- 12 files changed, 204 insertions(+), 575 deletions(-) diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc index 8a5d8d156245e..0c238da1b39e3 100644 --- a/docs/user/alerting/action-types/email.asciidoc +++ b/docs/user/alerting/action-types/email.asciidoc @@ -13,12 +13,12 @@ NOTE: For emails to have a footer with a link back to {kib}, set the <"` format. See the https://nodemailer.com/message/addresses/[Nodemailer address documentation] for more information. Host:: Host name of the service provider. If you are using the <> setting, make sure this hostname is added to the allowed hosts. Port:: The port to connect to on the service provider. Secure:: If true, the connection will use TLS when connecting to the service provider. Refer to the https://nodemailer.com/smtp/#tls-options[Nodemailer TLS documentation] for more information. If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command. -Username:: username for 'login' type authentication. -Password:: password for 'login' type authentication. +User:: Username for login type authentication. +Password:: Password for login type authentication. [float] [[Preconfigured-email-configuration]] @@ -40,11 +40,14 @@ Password:: password for 'login' type authentication. -- [[email-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== +| `service` +| The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the (https://nodemailer.com/usage/using-gmail/)[Nodemailer Gmail documentation]. + | `from` | An email address that corresponds to *Sender*. @@ -57,18 +60,21 @@ Password:: password for 'login' type authentication. | `secure` | A boolean that corresponds to *Secure*. +| `hasAuth` +| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`. + |=== -`secrets` defines sensitive information for the action type: +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== | `user` -| A string that corresponds to *User*. +| A string that corresponds to *User*. Required if `hasAuth` is set to `true`. | `password` -| A string that corresponds to *Password*. Should be stored in the <>. +| A string that corresponds to *Password*. Should be stored in the <>. Required if `hasAuth` is set to `true`. |=== diff --git a/docs/user/alerting/action-types/index.asciidoc b/docs/user/alerting/action-types/index.asciidoc index 2f459edea28f1..7ecc1cdb4f74e 100644 --- a/docs/user/alerting/action-types/index.asciidoc +++ b/docs/user/alerting/action-types/index.asciidoc @@ -31,7 +31,7 @@ Execution time field:: This field will be automatically set to the time the ale -- [[index-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -40,7 +40,7 @@ Execution time field:: This field will be automatically set to the time the ale | A string that corresponds to *Index*. |`refresh` -| A boolean that corresponds to *Refresh*. +| A boolean that corresponds to *Refresh*. Defaults to `false`. |`executionTimeField` | A string that corresponds to *Execution time field*. diff --git a/docs/user/alerting/action-types/jira.asciidoc b/docs/user/alerting/action-types/jira.asciidoc index 6e47d5618d598..0740cf7838b15 100644 --- a/docs/user/alerting/action-types/jira.asciidoc +++ b/docs/user/alerting/action-types/jira.asciidoc @@ -34,7 +34,7 @@ API token (or password):: Jira API authentication token (or password) for HTTP -- [[jira-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -47,7 +47,7 @@ API token (or password):: Jira API authentication token (or password) for HTTP |=== -`secrets` defines sensitive information for the action type: +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== @@ -65,14 +65,44 @@ API token (or password):: Jira API authentication token (or password) for HTTP Jira actions have the following configuration properties: -Issue type:: The type of the issue. -Priority:: The priority of the incident. -Labels:: The labels of the incident. -Title:: A title for the issue, used for searching the contents of the knowledge base. -Description:: The details about the incident. -Parent:: The parent issue id or key. Only for `Sub-task` issue types. -Priority:: The priority of the incident. -Additional comments:: Additional information for the client, such as how to troubleshoot the issue. +Subaction:: The subaction to perform: `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, or `getFields`. +Subaction params:: The parameters of the subaction. + +==== `pushToService` subaction configuration + +Incident:: A Jira incident has the following properties: +* `summary` - The title of the issue. +* `description` - A description of the issue. +* `externalId` - The ID of the issue in Jira. If present, the issue is updated. Otherwise, a new issue is created. +* `issueType` - The ID of the issue type in Jira. +* `priority` - The priority level in Jira. Example: `Medium`. +* `labels` - An array of labels. Labels cannot contain spaces. +* `parent` - The parent issue ID or key. Only for subtask issue types. +Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`. + +==== `getIncident` subaction configuration + +External ID:: The ID of the issue in Jira. + +==== `issueTypes` subaction configuration + +The `issueTypes` subaction has no parameters. Provide an empty object `{}`. + +==== `fieldsByIssueType` subaction configuration + +ID:: The ID of the issue in Jira. + +==== `issues` subaction configuration + +Title:: The title to search for. + +==== `issue` subaction configuration + +ID:: The ID of the issue in Jira. + +==== `getFields` subaction configuration + +The `getFields` subaction has no parameters. Provide an empty object `{}`. [[configuring-jira]] ==== Configuring and testing Jira diff --git a/docs/user/alerting/action-types/pagerduty.asciidoc b/docs/user/alerting/action-types/pagerduty.asciidoc index e1078a55ddd0d..c3185aaad553a 100644 --- a/docs/user/alerting/action-types/pagerduty.asciidoc +++ b/docs/user/alerting/action-types/pagerduty.asciidoc @@ -151,14 +151,25 @@ Integration Key:: A 32 character PagerDuty Integration Key for an integration -- [[pagerduty-connector-config-properties]] -`config` defines the action type specific to the configuration. -`config` contains -`apiURL`, a string that corresponds to *API URL*. +**`config`** defines the action type specific to the configuration and contains the following properties: -`secrets` defines sensitive information for the action type. -`secrets` contains -`routingKey`, a string that corresponds to *Integration Key*. +[cols="2*<"] +|=== +|`apiURL` +| A URL string that corresponds to *API URL*. + +|=== + +**`secrets`** defines sensitive information for the action type and contains the following properties: + +[cols="2*<"] +|=== + +|`routingKey` +| A string that corresponds to *Integration Key*. + +|=== [float] [[pagerduty-action-configuration]] diff --git a/docs/user/alerting/action-types/resilient.asciidoc b/docs/user/alerting/action-types/resilient.asciidoc index 112246ab91162..dfa95e2deec00 100644 --- a/docs/user/alerting/action-types/resilient.asciidoc +++ b/docs/user/alerting/action-types/resilient.asciidoc @@ -34,7 +34,7 @@ API key secret:: The authentication key secret for HTTP Basic authentication. -- [[resilient-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -47,7 +47,7 @@ API key secret:: The authentication key secret for HTTP Basic authentication. |=== -`secrets` defines sensitive information for the action type: +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== @@ -65,11 +65,30 @@ API key secret:: The authentication key secret for HTTP Basic authentication. IBM Resilient actions have the following configuration properties: -Incident types:: The incident types of the incident. -Severity code:: The severity of the incident. -Name:: A name for the issue, used for searching the contents of the knowledge base. -Description:: The details about the incident. -Additional comments:: Additional information for the client, such as how to troubleshoot the issue. +Subaction:: The subaction to perform: `pushToService`, `getFields`, `incidentTypes`, or `severity`. +Subaction params:: The parameters of the subaction. + +==== `pushToService` subaction configuration + +Incident:: The IBM resilient incident has the following properties: +* `name` - A name for the issue, used for searching the contents of the knowledge base. +* `description` - The details about the incident. +* `externalId` - The ID of the incident in IBM Resilient. If present, the incident is updated. Otherwise, a new incident is created. +* `incidentTypes` - An array with the IDs of IBM Resilient incident types. +* `severityCode` - The IBM Resilient ID of the severity code. +Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`. + +===== `getFields` subaction configuration + +The `getFields` subaction has not parameters. Provide an empty object `{}`. + +===== `incidentTypes` subaction configuration + +The `incidentTypes` subaction has no parameters. Provide an empty object `{}`. + +===== `severity` subaction configuration + +The `severity` subaction has no parameters. Provide an empty object `{}`. [[configuring-resilient]] ==== Configuring and testing IBM Resilient diff --git a/docs/user/alerting/action-types/server-log.asciidoc b/docs/user/alerting/action-types/server-log.asciidoc index 7022320328c85..276f64e7786bd 100644 --- a/docs/user/alerting/action-types/server-log.asciidoc +++ b/docs/user/alerting/action-types/server-log.asciidoc @@ -30,3 +30,4 @@ Name:: The name of the connector. The name is used to identify a connector Server log actions have the following properties: Message:: The message to log. +Level:: The log level of the message: `trace`, `debug`, `info`, `warn`, `error` or `fatal`. Defaults to `info`. diff --git a/docs/user/alerting/action-types/servicenow.asciidoc b/docs/user/alerting/action-types/servicenow.asciidoc index 5d8782c14e581..d1ee1b9357737 100644 --- a/docs/user/alerting/action-types/servicenow.asciidoc +++ b/docs/user/alerting/action-types/servicenow.asciidoc @@ -32,7 +32,7 @@ Password:: Password for HTTP Basic authentication. -- [[servicenow-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -42,7 +42,7 @@ Password:: Password for HTTP Basic authentication. |=== -`secrets` defines sensitive information for the action type: +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== @@ -60,12 +60,33 @@ Password:: Password for HTTP Basic authentication. ServiceNow actions have the following configuration properties: -Urgency:: The extent to which the incident resolution can delay. -Severity:: The severity of the incident. -Impact:: The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question. -Short description:: A short description for the incident, used for searching the contents of the knowledge base. -Description:: The details about the incident. -Additional comments:: Additional information for the client, such as how to troubleshoot the issue. +Subaction:: The subaction to perform: `pushToService`, `getFields`, `getIncident`, or `getChoices`. +Subaction params:: The parameters of the subaction. + +==== `pushToService` subaction configuration + +Incident:: The ServiceNow incident has the following properties: +* `short_description` - A short description for the incident, used for searching the contents of the knowledge base. +* `description` - The details about the incident. +* `externalId` - The ID of the incident in ServiceNow. If present, the incident is updated. Otherwise, a new incident is created. +* `severity` - The severity of the incident. +* `urgency` - The extent to which the incident resolution can delay. +* `impact` - The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question. +* `category` - The name of the category in ServiceNow. +* `subcategory` - The name of the subcategory in ServiceNow. +Comments:: A comment in the form of `{ commentId: string, version: string, comment: string }`. + +===== `getFields` subaction configuration + +The `getFields` subaction has no parameters. Provide an empty object `{}`. + +===== `getIncident` subaction configuration + +External ID:: The ID of the incident in ServiceNow. + +===== `getChoices` subaction configuration + +Fields:: An array of fields. Example: `[priority, category, impact]`. [[configuring-servicenow]] ==== Configuring and testing ServiceNow diff --git a/docs/user/alerting/action-types/slack.asciidoc b/docs/user/alerting/action-types/slack.asciidoc index 6a38e5c827ab2..6258969753356 100644 --- a/docs/user/alerting/action-types/slack.asciidoc +++ b/docs/user/alerting/action-types/slack.asciidoc @@ -22,15 +22,19 @@ Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messa my-slack: name: preconfigured-slack-action-type actionTypeId: .slack - config: + secrets: webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz' -- -[[slack-connector-config-properties]] -`config` defines the action type specific to the configuration. -`config` contains -`webhookUrl`, a string that corresponds to *Webhook URL*. +**`secrets`** defines sensitive information for the action type and contains the following properties: +[cols="2*<"] +|=== + +| `webhookUrl` +| A string that corresponds to *Webhook URL*. + +|=== [float] [[slack-action-configuration]] diff --git a/docs/user/alerting/action-types/teams.asciidoc b/docs/user/alerting/action-types/teams.asciidoc index e1ce91fc0c123..7f4a29dc86fc5 100644 --- a/docs/user/alerting/action-types/teams.asciidoc +++ b/docs/user/alerting/action-types/teams.asciidoc @@ -22,14 +22,20 @@ Webhook URL:: The URL of the incoming webhook. See https://docs.microsoft.com/ my-teams: name: preconfigured-teams-action-type actionTypeId: .teams - config: + secrets: webhookUrl: 'https://outlook.office.com/webhook/abcd@0123456/IncomingWebhook/abcdefgh/ijklmnopqrstuvwxyz' -- [[teams-connector-config-properties]] -`config` defines the action type specific to the configuration. -`config` contains -`webhookUrl`, a string that corresponds to *Webhook URL*. +**`secrets`** defines sensitive information for the action type and contains the following properties: + +[cols="2*<"] +|=== + +| `webhookUrl` +| A string that corresponds to *Webhook URL*. + +|=== [float] diff --git a/docs/user/alerting/action-types/webhook.asciidoc b/docs/user/alerting/action-types/webhook.asciidoc index 2d626d53d1c77..efe1077707ef0 100644 --- a/docs/user/alerting/action-types/webhook.asciidoc +++ b/docs/user/alerting/action-types/webhook.asciidoc @@ -12,10 +12,10 @@ Webhook connectors have the following configuration properties: Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action. URL:: The request URL. If you are using the <> setting, make sure the hostname is added to the allowed hosts. -Method:: HTTP request method, either `post`(default) or `put`. +Method:: HTTP request method, either `POST`(default) or `PUT`. Headers:: A set of key-value pairs sent as headers with the request -User:: An optional username. If set, HTTP basic authentication is used. Currently only basic authentication is supported. -Password:: An optional password. If set, HTTP basic authentication is used. Currently only basic authentication is supported. +User:: Username for HTTP basic authentication. +Password:: Password for HTTP basic authentication. [float] [[Preconfigured-webhook-configuration]] @@ -37,7 +37,7 @@ Password:: An optional password. If set, HTTP basic authentication is used. Cur -- [[webhook-connector-config-properties]] -`config` defines the action type specific to the configuration and contains the following properties: +**`config`** defines the action type specific to the configuration and contains the following properties: [cols="2*<"] |=== @@ -51,18 +51,21 @@ Password:: An optional password. If set, HTTP basic authentication is used. Cur |`headers` |A record that corresponds to *Headers*. +| `hasAuth` +| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`. + |=== -`secrets` defines sensitive information for the action type: +**`secrets`** defines sensitive information for the action type and contains the following properties: [cols="2*<"] |=== |`user` -|A string that corresponds to *User*. +|A string that corresponds to *User*. Required if `hasAuth` is set to `true`. |`password` -|A string that corresponds to *Password*. Should be stored in the <>. +|A string that corresponds to *Password*. Should be stored in the <>. Required if `hasAuth` is set to `true`. |=== diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index 528189b8a1216..5f13c6e1774a8 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -92,6 +92,7 @@ Actions are not required on alerts. In some cases you may want to run an alert w ============================================== [float] +[[actions-configuration]] === Global actions configuration Some actions configuration options apply to all actions. If you are using an *on-prem* Elastic Stack deployment, you can set these in the kibana.yml file. @@ -99,8 +100,10 @@ If you are using a cloud deployment, you can set these via the console. Here's a list of the available global configuration options and an explanation of what each one does: +* `xpack.actions.enabled`: Feature toggle that enables Actions in {kib}. Default: `true` * `xpack.actions.allowedHosts`: Specifies an array of host names which actions such as email, Slack, PagerDuty, and webhook can connect to. An element of * indicates any host can be connected to. An empty array indicates no hosts can be connected to. Default: [ {asterisk} ] -* `xpack.actions.enabledActionTypes`: Specifies to an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are: .server-log, .slack, .email, .index, .pagerduty, .webhook. Default: [ {asterisk} ] +* `xpack.actions.enabledActionTypes`: Specifies an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, and `.webhook`. Default: [ {asterisk} ] +* `xpack.actions.preconfigured`: Specifies preconfigured action IDs and configs. Default: {} * `xpack.actions.proxyUrl`: Specifies the proxy URL to use, if using a proxy for actions. * `xpack.actions.proxyHeader`: Specifies HTTP headers for proxy, if using a proxy for actions. * `xpack.actions.proxyRejectUnauthorizedCertificates`: Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. diff --git a/x-pack/plugins/actions/README.md b/x-pack/plugins/actions/README.md index 9d48e618b76dc..78094f4c0eb0b 100644 --- a/x-pack/plugins/actions/README.md +++ b/x-pack/plugins/actions/README.md @@ -26,19 +26,12 @@ Table of Contents - [Executor](#executor) - [Example](#example) - [RESTful API](#restful-api) - - [`POST /api/actions/action`: Create action](#post-apiactionsaction-create-action) - - [`DELETE /api/actions/action/{id}`: Delete action](#delete-apiactionsactionid-delete-action) - - [`GET /api/actions`: Get all actions](#get-apiactions-get-all-actions) - - [`GET /api/actions/action/{id}`: Get action](#get-apiactionsactionid-get-action) - - [`GET /api/actions/list_action_types`: List action types](#get-apiactionslist_action_types-list-action-types) - - [`PUT /api/actions/action/{id}`: Update action](#put-apiactionsactionid-update-action) - - [`POST /api/actions/action/{id}/_execute`: Execute action](#post-apiactionsactionid_execute-execute-action) - [Firing actions](#firing-actions) - - [Accessing a scoped ActionsClient](#accessing-a-scoped-actionsclient) + - [Accessing a scoped ActionsClient](#accessing-a-scoped-actionsclient) - [actionsClient.enqueueExecution(options)](#actionsclientenqueueexecutionoptions) - - [Example](#example-1) + - [Example](#example-1) - [actionsClient.execute(options)](#actionsclientexecuteoptions) - - [Example](#example-2) + - [Example](#example-2) - [Built-in Action Types](#built-in-action-types) - [Server log](#server-log) - [`config`](#config) @@ -109,9 +102,9 @@ action types. ## Usage -1. Develop and register an action type (see action types -> example). -2. Create an action by using the RESTful API (see actions -> create action). -3. Use alerts to execute actions or execute manually (see firing actions). +1. Develop and register an action type (see [Action types -> Example](#example)). +2. Create an action by using the [RESTful API](#restful-api). +3. Use alerts to execute actions or execute manually (see [Firing actions](#firing-actions)). ## Kibana Actions Configuration @@ -119,50 +112,48 @@ Implemented under the [Actions Config](./server/actions_config.ts). ### Configuration Options -Built-In-Actions are configured using the _xpack.actions_ namespoace under _kibana.yml_, and have the following configuration options: +Built-In-Actions are configured using the _xpack.actions_ namespace under _kibana.yml_. See the [Actions configuration Documentation](https://www.elastic.co/guide/en/kibana/master/defining-alerts.html#actions-configuration) for all configuration options. -| Namespaced Key | Description | Type | -| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| _xpack.actions._**enabled** | Feature toggle which enabled Actions in Kibana. | boolean | -| _xpack.actions._**allowedHosts** | Which _hostnames_ are allowed for the Built-In-Action? This list should contain hostnames of every external service you wish to interact with using Webhooks, Email or any other built in Action. Note that you may use the string "\*" in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential use of such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. | Array | -| _xpack.actions._**enabledActionTypes** | A list of _actionTypes_ id's that are enabled. A "\*" may be used as an element to indicate all registered actionTypes should be enabled. The actionTypes registered for Kibana are `.server-log`, `.slack`, `.email`, `.index`, `.pagerduty`, `.webhook`. Default: `["*"]` | Array | -| _xpack.actions._**preconfigured** | A object of action id / preconfigured actions. Default: `{}` | Array | +#### **allowedHosts** configuration -#### Adding Built-in Action Types to allowedHosts +- You can use the string "*" in the **allowedHosts** configuration in place of a specific hostname to enable Kibana to target any URL, but keep in mind the potential to use such a feature to execute [SSRF](https://www.owasp.org/index.php/Server_Side_Request_Forgery) attacks from your server. -It is worth noting that the **allowedHosts** configuation applies to built-in action types (such as Slack, or PagerDuty) as well. - -Uniquely, the _PagerDuty Action Type_ has been configured to support the service's Events API (at _https://events.pagerduty.com/v2/enqueue_, which you can read about [here](https://v2.developer.pagerduty.com/docs/events-api-v2)) as a default, but this too, must be included in the allowedHosts before the PagerDuty action can be used. +- The **allowedHosts** configuration applies to built-in action types (such as Slack and PagerDuty). While the _PagerDuty Action Type_ has been configured to support the service's Events API (at _https://events.pagerduty.com/v2/enqueue_, which you can read about in [Pagerduty's documentation](https://v2.developer.pagerduty.com/docs/events-api-v2)), the PagerDuty domain must still be included in the allowedHosts configuration before the action can be used. ### Configuration Utilities -This module provides a Utilities for interacting with the configuration. +This module provides utilities for interacting with the configuration. -| Method | Arguments | Description | Return Type | -| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -| isUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all URI's are allowed (using an "\*") then it will always return `true`. | Boolean | -| isHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will always return `true`. | Boolean | -| isActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Returns true if the actionType is enabled, otherwise false. | Boolean | -| ensureUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all URI's are allowed (using an "\*") then it will never throw. | No return value, throws if URI isn't allowed | -| ensureHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will never throw | No return value, throws if Hostname isn't allowed . | -| ensureActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Throws an error if the actionType is not enabled | No return value, throws if actionType isn't enabled | +| Method | Arguments | Description | Return Type | +| --------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | +| isUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all URI's are allowed (using an "\*") then it will always return `true`. | Boolean | +| isHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and returns `true` if it is allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will always return `true`. | Boolean | +| isActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Returns true if the actionType is enabled, otherwise false. | Boolean | +| ensureUriAllowed | _uri_: The URI you wish to validate is allowed | Validates whether the URI is allowed. This checks the configuration and validates that the hostname of the URI is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all URI's are allowed (using an "\*") then it will never throw. | No return value, throws if URI isn't allowed | +| ensureHostnameAllowed | _hostname_: The Hostname you wish to validate is allowed | Validates whether the Hostname is allowed. This checks the configuration and validates that the hostname is in the list of allowed Hosts and throws an error if it is not allowed. If the configuration says that all Hostnames are allowed (using an "\*") then it will never throw | No return value, throws if Hostname isn't allowed . | +| ensureActionTypeEnabled | _actionType_: The actionType to check to see if it's enabled | Throws an error if the actionType is not enabled | No return value, throws if actionType isn't enabled | +| isRejectUnauthorizedCertificatesEnabled | _none_ | Returns value of `rejectUnauthorized` from configuration. | Boolean | +| getProxySettings | _none_ | If `proxyUrl` is set in the configuration, returns the proxy settings `proxyUrl`, `proxyHeaders` and `proxyRejectUnauthorizedCertificates`. Otherwise returns _undefined_. | Undefined or ProxySettings | ## Action types ### Methods -**server.plugins.actions.setup.registerType(options)** +**server.plugins.actions.setup.registerType (options)** The following table describes the properties of the `options` object. -| Property | Description | Type | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -| id | Unique identifier for the action type. For convention, ids starting with `.` are reserved for built in action types. We recommend using a convention like `.mySpecialAction` for your action types. | string | -| name | A user-friendly name for the action type. These will be displayed in dropdowns when chosing action types. | string | -| unencryptedAttributes | A list of opt-out attributes that don't need to be encrypted. These attributes won't need to be re-entered on import / export when the feature becomes available. These attributes will also be readable / displayed when it comes to a table / edit screen. | array of strings | -| validate.params | When developing an action type, it needs to accept parameters to know what to do with the action. (Example to, from, subject, body of an email). See the current built-in email action type for an example of the state-of-the-art validation.

Technically, the value of this property should have a property named `validate()` which is a function that takes a params object to validate and returns a sanitized version of that object to pass to the execution function. Validation errors should be thrown from the `validate()` function and will be available as an error message | schema / validation function | -| validate.config | Similar to params, a config is required when creating an action (for example host, port, username, and password of an email server). | schema / validation function | -| executor | This is where the code of an action type lives. This is a function gets called for executing an action from either alerting or manually by using the exposed function (see firing actions). For full details, see executor section below. | Function | +| Property | Description | Type | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| id | Unique identifier for the action type. For convention, ids starting with `.` are reserved for built in action types. We recommend using a convention like `.mySpecialAction` for your action types. | string | +| name | A user-friendly name for the action type. These will be displayed in dropdowns when chosing action types. | string | +| maxAttempts | The maximum number of times this action will attempt to execute when scheduled. | number | +| minimumLicenseRequired | The license required to use the action type. | string | +| validate.params | When developing an action type, it needs to accept parameters to know what to do with the action. (Example `to`, `from`, `subject`, `body` of an email). See the current built-in email action type for an example of the state-of-the-art validation.

Technically, the value of this property should have a property named `validate()` which is a function that takes a params object to validate and returns a sanitized version of that object to pass to the execution function. Validation errors should be thrown from the `validate()` function and will be available as an error message | schema / validation function | +| validate.config | Similar to params, a config may be required when creating an action (for example `host` and `port` for an email server). | schema / validation function | +| validate.secrets | Similar to params, a secrets object may be required when creating an action (for example `user` and `password` for an email server). | schema / validation function | +| executor | This is where the code of an action type lives. This is a function gets called for executing an action from either alerting or manually by using the exposed function (see firing actions). For full details, see executor section below. | Function | +| renderParameterTemplates | Optionally define a function to provide custom rendering for this action type. | Function | **Important** - The config object is persisted in ElasticSearch and updated via the ElasticSearch update document API. This API allows "partial updates" - and this can cause issues with the encryption used on specified properties. So, a `validate()` function should return values for all configuration properties, so that partial updates do not occur. Setting property values to `null` rather than `undefined`, or not including a property in the config object, is all you need to do to ensure partial updates won't occur. @@ -175,12 +166,13 @@ This is the primary function for an action type. Whenever the action needs to ex | Property | Description | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | actionId | The action saved object id that the action type is executing for. | -| config | The decrypted configuration given to an action. This comes from the action saved object that is partially or fully encrypted within the data store. If you would like to validate the config before being passed to the executor, define `validate.config` within the action type. | +| config | The action configuration. If you would like to validate the config before being passed to the executor, define `validate.config` within the action type. | +| secrets | The decrypted secrets object given to an action. This comes from the action saved object that is partially or fully encrypted within the data store. If you would like to validate the secrets object before being passed to the executor, define `validate.secrets` within the action type. | | params | Parameters for the execution. These will be given at execution time by either an alert or manually provided when calling the plugin provided execute function. | | services.callCluster(path, opts) | Use this to do Elasticsearch queries on the cluster Kibana connects to. This function is the same as any other `callCluster` in Kibana but runs in the context of the user who is calling the action when security is enabled. | | services.getLegacyScopedClusterClient | This function returns an instance of the LegacyScopedClusterClient scoped to the user who is calling the action when security is enabled. | | services.savedObjectsClient | This is an instance of the saved objects client. This provides the ability to do CRUD on any saved objects within the same space the alert lives in.

The scope of the saved objects client is tied to the user in context calling the execute API or the API key provided to the execute plugin function (only when security isenabled). | -| services.log(tags, [data], [timestamp]) | Use this to create server logs. (This is the same function as server.log) | +| services.log(tags, [data], [timestamp]) | Use this to create server logs. (This is the same function as server.log) ### Example @@ -189,83 +181,14 @@ The built-in email action type provides a good example of creating an action typ ## RESTful API -Using an action type requires an action to be created that will contain and encrypt configuration for a given action type. See below for CRUD operations using the API. - -### `POST /api/actions/action`: Create action - -Payload: - -| Property | Description | Type | -| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -| name | A name to reference and search in the future. This value will be used to populate dropdowns. | string | -| actionTypeId | The id value of the action type you want to call when the action executes. | string | -| config | The configuration the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if config validation is defined. | object | -| secrets | The secrets the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if secrets validation is defined. | object | - -### `DELETE /api/actions/action/{id}`: Delete action - -Params: - -| Property | Description | Type | -| -------- | --------------------------------------------- | ------ | -| id | The id of the action you're trying to delete. | string | - -### `GET /api/actions`: Get all actions - -No parameters. - -Return all actions from saved objects merged with predefined list. -Use the [saved objects API for find](https://www.elastic.co/guide/en/kibana/master/saved-objects-api-find.html) with the proprties: `type: 'action'` and `perPage: 10000`. -List of predefined actions should be set up in Kibana.yaml. - -### `GET /api/actions/action/{id}`: Get action - -Params: - -| Property | Description | Type | -| -------- | ------------------------------------------ | ------ | -| id | The id of the action you're trying to get. | string | - -### `GET /api/actions/list_action_types`: List action types - -No parameters. - -### `PUT /api/actions/action/{id}`: Update action - -Params: - -| Property | Description | Type | -| -------- | --------------------------------------------- | ------ | -| id | The id of the action you're trying to update. | string | - -Payload: - -| Property | Description | Type | -| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -| name | A name to reference and search in the future. This value will be used to populate dropdowns. | string | -| config | The configuration the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if config validation is defined. | object | -| secrets | The secrets the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if secrets validation is defined. | object | - -### `POST /api/actions/action/{id}/_execute`: Execute action - -Params: - -| Property | Description | Type | -| -------- | ---------------------------------------------- | ------ | -| id | The id of the action you're trying to execute. | string | - -Payload: - -| Property | Description | Type | -| -------- | ---------------------------------------------------------- | ------ | -| params | The parameters the action type requires for the execution. | object | +Using an action type requires an action to be created that will contain and encrypt configuration for a given action type. See the [REST API Documentation](https://www.elastic.co/guide/en/kibana/master/actions-and-connectors-api.html) API for CRUD operations for Actions. ## Firing actions Running actions is possible by using the ActionsClient which is provided by the `getActionsClientWithRequest` function part of the plugin's Start Contract. By providing the user's Request you'll receive an instance of the ActionsClient which is tailered to the current user and is scoped to the resources the user is authorized to access. -## Accessing a scoped ActionsClient +### Accessing a scoped ActionsClient ``` const actionsClient = server.plugins.actions.getActionsClientWithRequest(request); @@ -279,7 +202,7 @@ This api schedules a task which will run the action using the current user scope Running the action by scheduling a task means that we will no longer have a user request by which to ascertain the action's privileges and so you might need to provide these yourself: -- The **SpaceId** in which the user's action is expected to run +- The **spaceId** in which the user's action is expected to run - When security is enabled you'll also need to provide an **apiKey** which allows us to mimic the user and their privileges. The following table describes the properties of the `options` object. @@ -292,7 +215,7 @@ The following table describes the properties of the `options` object. | apiKey | The Elasticsearch API key to use for context. (Note: only required and used when security is enabled). | string | | source | The source of the execution, either an HTTP request or a reference to a Saved Object. | object, optional | -## Example +#### Example This example makes action `3c5b2bd4-5424-4e4b-8cf5-c0a58c762cc5` send an email. The action plugin will load the saved object and find what action type to call with `params`. @@ -324,7 +247,7 @@ The following table describes the properties of the `options` object. | params | The `params` value to give the action type executor. | object | | source | The source of the execution, either an HTTP request or a reference to a Saved Object. | object, optional | -## Example +#### Example As with the previous example, we'll use the action `3c5b2bd4-5424-4e4b-8cf5-c0a58c762cc5` to send an email. @@ -347,405 +270,7 @@ const result = await actionsClient.execute({ # Built-in Action Types -Kibana ships with a set of built-in action types: - -| Type | Id | Description | -| ------------------------------- | ----------------- | ------------------------------------------------------------------ | -| [Server log](#server-log) | `.server-log` | Logs messages to the Kibana log using Kibana's logger | -| [Email](#email) | `.email` | Sends an email using SMTP | -| [Slack](#slack) | `.slack` | Posts a message to a slack channel | -| [Index](#index) | `.index` | Indexes document(s) into Elasticsearch | -| [Webhook](#webhook) | `.webhook` | Send a payload to a web service using HTTP POST or PUT | -| [PagerDuty](#pagerduty) | `.pagerduty` | Trigger, resolve, or acknowlege an incident to a PagerDuty service | -| [ServiceNow ITSM](#servicenow) | `.servicenow` | Create or update an incident to a ServiceNow ITSM instance | -| [ServiceNow SIR](#servicenow) | `.servicenow-sir` | Create or update an incident to a ServiceNow SIR instance | -| [Jira](#jira) | `.jira` | Create or update an issue to a Jira instance | -| [IBM Resilient](#ibm-resilient) | `.resilient` | Create or update an incident to a IBM Resilient instance | - ---- - -## Server log - -ID: `.log` - -The params properties are modelled after the arguments to the [Hapi.server.log()](https://hapijs.com/api#-serverlogtags-data-timestamp) function. - -### `config` - -This action has no `config` properties. - -### `secrets` - -This action type has no `secrets` properties. - -### `params` - -| Property | Description | Type | -| -------- | ---------------------------------------- | --------------------- | -| message | The message to log. | string | -| tags | Tags associated with the message to log. | string[] _(optional)_ | - ---- - -## Email - -ID: `.email` - -This action type uses [nodemailer](https://nodemailer.com/about/) to send emails. - -### `config` - -Either the property `service` must be provided, or the `host` and `port` properties must be provided. If `service` is provided, `host`, `port` and `secure` are ignored. For more information on the `gmail` service value specifically, see the [nodemailer gmail documentation](https://nodemailer.com/usage/using-gmail/). - -The `secure` property defaults to `false`. See the [nodemailer TLS documentation](https://nodemailer.com/smtp/#tls-options) for more information. - -The `from` field can be specified as in typical `"user@host-name"` format, or as `"human name "` format. See the [nodemailer address documentation](https://nodemailer.com/message/addresses/) for more information. - -| Property | Description | Type | -| -------- | ------------------------------------------------------------------------------------------ | -------------------- | -| service | the name of a [well-known email service provider](https://nodemailer.com/smtp/well-known/) | string _(optional)_ | -| host | host name of the service provider | string _(optional)_ | -| port | port number of the service provider | number _(optional)_ | -| secure | whether to use TLS with the service provider | boolean _(optional)_ | -| from | the from address for all emails sent with this action type | string | - -### `secrets` - -| Property | Description | Type | -| -------- | ----------------------------------------- | ------ | -| user | userid to use with the service provider | string | -| password | password to use with the service provider | string | - -### `params` - -There must be at least one entry in the `to`, `cc` and `bcc` arrays. - -The message text will be sent as both plain text and html text. Additional function may be provided later. - -The `to`, `cc`, and `bcc` array entries can be in the same format as the `from` property described in the config object above. - -| Property | Description | Type | -| -------- | ----------------------------- | --------------------- | -| to | list of to addressees | string[] _(optional)_ | -| cc | list of cc addressees | string[] _(optional)_ | -| bcc | list of bcc addressees | string[] _(optional)_ | -| subject | the subject line of the email | string | -| message | the message text | string | - ---- - -## Slack - -ID: `.slack` - -This action type interfaces with the [Slack Incoming Webhooks feature](https://api.slack.com/incoming-webhooks). Currently the params property `message` will be used as the `text` property of the Slack incoming message. Additional function may be provided later. - -### `config` - -This action type has no `config` properties. - -### `secrets` - -| Property | Description | Type | -| ---------- | ------------------------------------- | ------ | -| webhookUrl | the url of the Slack incoming webhook | string | - -### `params` - -| Property | Description | Type | -| -------- | ---------------- | ------ | -| message | the message text | string | - ---- - -## Index - -ID: `.index` - -The config and params properties are modelled after the [Watcher Index Action](https://www.elastic.co/guide/en/elasticsearch/reference/master/actions-index.html). The index can be set in the config or params, and if set in config, then the index set in the params will be ignored. - -### `config` - -| Property | Description | Type | -| -------------------- | ---------------------------------------------------------- | -------------------- | -| index | The Elasticsearch index to index into. | string _(optional)_ | -| doc_id | The optional \_id of the document. | string _(optional)_ | -| execution_time_field | The field that will store/index the action execution time. | string _(optional)_ | -| refresh | Setting of the refresh policy for the write request. | boolean _(optional)_ | - -### `secrets` - -This action type has no `secrets` properties. - -### `params` - -| Property | Description | Type | -| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| documents | JSON object that describes the [document](https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started-index.html#getting-started-batch-processing). | object[] | - ---- - -## Webhook - -ID: `.webhook` - -The webhook action uses [axios](https://github.com/axios/axios) to send a POST or PUT request to a web service. - -### `config` - -| Property | Description | Type | -| -------- | ------------------------------------------------------- | ------------------------------------------------ | -| url | Request URL | string | -| method | HTTP request method, either `post`_(default)_ or `put` | string _(optional)_ | -| headers | Key-value pairs of the headers to send with the request | object, keys and values are strings _(optional)_ | - -### `secrets` - -| Property | Description | Type | -| -------- | -------------------------------------- | ------------------- | -| user | Username for HTTP Basic authentication | string _(optional)_ | -| password | Password for HTTP Basic authentication | string _(optional)_ | - -### `params` - -| Property | Description | Type | -| -------- | --------------------- | ------------------- | -| body | The HTTP request body | string _(optional)_ | - ---- - -## PagerDuty - -ID: `.pagerduty` - -The PagerDuty action uses the [V2 Events API](https://v2.developer.pagerduty.com/docs/events-api-v2) to trigger, acknowlege, and resolve PagerDuty alerts. - -### `config` - -| Property | Description | Type | -| -------- | -------------------------------------------------------------------------- | ------------------- | -| apiUrl | PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue` | string _(optional)_ | - -### `secrets` - -| Property | Description | Type | -| ---------- | ---------------------------------------------------------------------------------------------------------- | ------ | -| routingKey | This is the 32 character PagerDuty Integration Key for an integration on a service or on a global ruleset. | string | - -### `params` - -| Property | Description | Type | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -| eventAction | One of `trigger` _(default)_, `resolve`, or `acknowlege`. See [event action](https://v2.developer.pagerduty.com/docs/events-api-v2#event-action) for more details. | string _(optional)_ | -| dedupKey | All actions sharing this key will be associated with the same PagerDuty alert. Used to correlate trigger and resolution. The maximum length is **255** characters. See [alert deduplication](https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication) for details. | string _(optional)_ | -| summary | A text summary of the event, defaults to `No summary provided`. The maximum length is **1024** characters. | string _(optional)_ | -| source | The affected system, preferably a hostname or fully qualified domain name. Defaults to `Kibana Action `. | string _(optional)_ | -| severity | The perceived severity of on the affected system. This can be one of `critical`, `error`, `warning` or `info`_(default)_. | string _(optional)_ | -| timestamp | An [ISO-8601 format date-time](https://v2.developer.pagerduty.com/v2/docs/types#datetime), indicating the time the event was detected or generated. | string _(optional)_ | -| component | The component of the source machine that is responsible for the event, for example `mysql` or `eth0`. | string _(optional)_ | -| group | Logical grouping of components of a service, for example `app-stack`. | string _(optional)_ | -| class | The class/type of the event, for example `ping failure` or `cpu load`. | string _(optional)_ | - -For more details see [PagerDuty v2 event parameters](https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2). - ---- - -## ServiceNow - -ServiceNow ITSM ID: `.servicenow` - -ServiceNow SIR ID: `.servicenow-sir` - -The ServiceNow actions use the [V2 Table API](https://developer.servicenow.com/app.do#!/rest_api_doc?v=orlando&id=c_TableAPI) to create and update ServiceNow incidents. Both action types use the same `config`, `secrets`, and `params` schema. - -### `config` - -| Property | Description | Type | -| -------- | ------------------------ | ------ | -| apiUrl | ServiceNow instance URL. | string | - -### `secrets` - -| Property | Description | Type | -| -------- | -------------------------------------- | ------ | -| username | Username for HTTP Basic authentication | string | -| password | Password for HTTP Basic authentication | string | - -### `params` - -| Property | Description | Type | -| --------------- | -------------------------------------------------------------------------------------------------- | ------ | -| subAction | The sub action to perform. It can be `pushToService`, `getFields`, `getIncident`, and `getChoices` | string | -| subActionParams | The parameters of the sub action | object | - -#### `subActionParams (pushToService)` - -| Property | Description | Type | -| -------- | ------------------------------------------------------------------------------------------------------------- | --------------------- | -| incident | The ServiceNow incident. | object | -| comments | The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. | object[] _(optional)_ | - -The following table describes the properties of the `incident` object. - -| Property | Description | Type | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------- | -| short_description | The title of the incident. | string | -| description | The description of the incident. | string _(optional)_ | -| externalId | The id of the incident in ServiceNow. If presented the incident will be update. Otherwise a new incident will be created. | string _(optional)_ | -| severity | The name of the severity in ServiceNow. | string _(optional)_ | -| urgency | The name of the urgency in ServiceNow. | string _(optional)_ | -| impact | The name of the impact in ServiceNow. | string _(optional)_ | -| category | The name of the category in ServiceNow. | string _(optional)_ | -| subcategory | The name of the subcategory in ServiceNow. | string _(optional)_ | - -#### `subActionParams (getFields)` - -No parameters for `getFields` sub-action. Provide an empty object `{}`. - -#### `subActionParams (getIncident)` - -| Property | Description | Type | -| ---------- | ------------------------------------- | ------ | -| externalId | The id of the incident in ServiceNow. | string | - - -#### `subActionParams (getChoices)` - -| Property | Description | Type | -| -------- | ------------------------------------------------------------ | -------- | -| fields | An array of fields. Example: `[priority, category, impact]`. | string[] | - ---- - -## Jira - -ID: `.jira` - -The Jira action uses the [V2 API](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) to create and update Jira incidents. - -### `config` - -| Property | Description | Type | -| -------- | ------------------ | ------ | -| apiUrl | Jira instance URL. | string | - -### `secrets` - -| Property | Description | Type | -| -------- | ----------------------------------------------------- | ------ | -| email | email (or username) for HTTP Basic authentication | string | -| apiToken | API token (or password) for HTTP Basic authentication | string | - -### `params` - -| Property | Description | Type | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -| subAction | The sub action to perform. It can be `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, and `getFields` | string | -| subActionParams | The parameters of the sub action | object | - -#### `subActionParams (pushToService)` - -| Property | Description | Type | -| -------- | ------------------------------------------------------------------------------------------------------------- | --------------------- | -| incident | The Jira incident. | object | -| comments | The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. | object[] _(optional)_ | - -The following table describes the properties of the `incident` object. - -| Property | Description | Type | -| ----------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- | -| summary | The title of the issue | string | -| description | The description of the issue | string _(optional)_ | -| externalId | The id of the issue in Jira. If presented the incident will be update. Otherwise a new incident will be created. | string _(optional)_ | -| issueType | The id of the issue type in Jira. | string _(optional)_ | -| priority | The name of the priority in Jira. Example: `Medium`. | string _(optional)_ | -| labels | An array of labels. Labels cannot contain spaces. | string[] _(optional)_ | -| parent | The parent issue id or key. Only for `Sub-task` issue types. | string _(optional)_ | - -#### `subActionParams (getIncident)` - -| Property | Description | Type | -| ---------- | --------------------------- | ------ | -| externalId | The id of the issue in Jira | string | - -#### `subActionParams (issueTypes)` - -No parameters for `issueTypes` sub-action. Provide an empty object `{}`. - -#### `subActionParams (fieldsByIssueType)` - -| Property | Description | Type | -| -------- | -------------------------------- | ------ | -| id | The id of the issue type in Jira | string | - -#### `subActionParams (issues)` - -| Property | Description | Type | -| -------- | ----------------------- | ------ | -| title | The title to search for | string | - -#### `subActionParams (issue)` - -| Property | Description | Type | -| -------- | --------------------------- | ------ | -| id | The id of the issue in Jira | string | - -#### `subActionParams (getFields)` - -No parameters for `getFields` sub-action. Provide an empty object `{}`. - -## IBM Resilient - -ID: `.resilient` - -### `config` - -| Property | Description | Type | -| -------- | --------------------------- | ------ | -| apiUrl | IBM Resilient instance URL. | string | - -### `secrets` - -| Property | Description | Type | -| ------------ | -------------------------------------------- | ------ | -| apiKeyId | API key ID for HTTP Basic authentication | string | -| apiKeySecret | API key secret for HTTP Basic authentication | string | - -### `params` - -| Property | Description | Type | -| --------------- | -------------------------------------------------------------------------------------------------- | ------ | -| subAction | The sub action to perform. It can be `pushToService`, `getFields`, `incidentTypes`, and `severity` | string | -| subActionParams | The parameters of the sub action | object | - -#### `subActionParams (pushToService)` - -| Property | Description | Type | -| -------- | ------------------------------------------------------------------------------------------------------------- | --------------------- | -| incident | The IBM Resilient incident. | object | -| comments | The comments of the case. A comment is of the form `{ commentId: string, version: string, comment: string }`. | object[] _(optional)_ | - -The following table describes the properties of the `incident` object. - -| Property | Description | Type | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------- | -| name | The title of the incident | string _(optional)_ | -| description | The description of the incident | string _(optional)_ | -| externalId | The id of the incident in IBM Resilient. If presented the incident will be update. Otherwise a new incident will be created. | string _(optional)_ | -| incidentTypes | An array with the ids of IBM Resilient incident types. | number[] _(optional)_ | -| severityCode | IBM Resilient id of the severity code. | number _(optional)_ | - -#### `subActionParams (getFields)` - -No parameters for `getFields` sub-action. Provide an empty object `{}`. - -#### `subActionParams (incidentTypes)` - -No parameters for `incidentTypes` sub-action. Provide an empty object `{}`. - -#### `subActionParams (severity)` - -No parameters for `severity` sub-action. Provide an empty object `{}`. +Kibana ships with a set of built-in action types. See [Actions and connector types Documentation](https://www.elastic.co/guide/en/kibana/master/action-types.html). # Command Line Utility @@ -801,4 +326,4 @@ Instead of `schema.maybe()`, use `schema.nullable()`, which is the same as `sche ## user interface -In order to make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui). \ No newline at end of file +To make this action usable in the Kibana UI, you will need to provide all the UI editing aspects of the action. The existing action type user interfaces are defined in [`x-pack/plugins/triggers_actions_ui/public/application/components/builtin_action_types`](../triggers_actions_ui/public/application/components/builtin_action_types). For more information, see the [UI documentation](../triggers_actions_ui/README.md#create-and-register-new-action-type-ui).