Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Actions][Docs] Moving subaction and subaction params back to README #92878

Merged
merged 6 commits into from
Mar 2, 2021
Merged

[Actions][Docs] Moving subaction and subaction params back to README #92878

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f983431
Moving subaction and subaction params back to README
ymao1 Feb 25, 2021
ed650b6
Merge branch 'master' into actions/readme-again
kibanamachine Mar 1, 2021
e755a74
Apply suggestions from code review
ymao1 Mar 1, 2021
42b3a90
Merge branch 'master' of https://github.com/elastic/kibana into actio…
ymao1 Mar 1, 2021
c81d135
Merge branch 'actions/readme-again' of https://github.com/ymao1/kiban…
ymao1 Mar 1, 2021
a714d33
PR fixes
ymao1 Mar 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 7 additions & 38 deletions docs/user/alerting/action-types/jira.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,44 +65,13 @@ API token (or password):: Jira API authentication token (or password) for HTTP

Jira actions have the following configuration properties:

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 `{}`.
Issue type:: The type of the issue.
Priority:: The priority of the incident.
Labels:: The labels for 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 ID or key of the parent issue. Only for `Subtask` issue types.
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.

[[configuring-jira]]
==== Configuring and testing Jira
Expand Down
29 changes: 5 additions & 24 deletions docs/user/alerting/action-types/resilient.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,30 +65,11 @@ API key secret:: The authentication key secret for HTTP Basic authentication.

IBM Resilient actions have the following configuration properties:

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 `{}`.
Incident types:: The type 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.

[[configuring-resilient]]
==== Configuring and testing IBM Resilient
Expand Down
33 changes: 6 additions & 27 deletions docs/user/alerting/action-types/servicenow.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,33 +60,12 @@ Password:: Password for HTTP Basic authentication.

ServiceNow actions have the following configuration properties:

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]`.
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.

[[configuring-servicenow]]
==== Configuring and testing ServiceNow
Expand Down
190 changes: 157 additions & 33 deletions x-pack/plugins/actions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,42 +33,14 @@ Table of Contents
- [actionsClient.execute(options)](#actionsclientexecuteoptions)
- [Example](#example-2)
- [Built-in Action Types](#built-in-action-types)
- [Server log](#server-log)
- [`config`](#config)
- [`secrets`](#secrets)
- [`params`](#params)
- [Email](#email)
- [`config`](#config-1)
- [`secrets`](#secrets-1)
- [`params`](#params-1)
- [Slack](#slack)
- [`config`](#config-2)
- [`secrets`](#secrets-2)
- [`params`](#params-2)
- [Index](#index)
- [`config`](#config-3)
- [`secrets`](#secrets-3)
- [`params`](#params-3)
- [Webhook](#webhook)
- [`config`](#config-4)
- [`secrets`](#secrets-4)
- [`params`](#params-4)
- [PagerDuty](#pagerduty)
- [`config`](#config-5)
- [`secrets`](#secrets-5)
- [`params`](#params-5)
- [ServiceNow](#servicenow)
- [`config`](#config-6)
- [`secrets`](#secrets-6)
- [`params`](#params-6)
- [`params`](#params)
- [`subActionParams (pushToService)`](#subactionparams-pushtoservice)
- [`subActionParams (getFields)`](#subactionparams-getfields)
- [`subActionParams (getIncident)`](#subactionparams-getincident)
- [`subActionParams (getChoices)`](#subactionparams-getchoices)
- [Jira](#jira)
- [`config`](#config-7)
- [`secrets`](#secrets-7)
- [`params`](#params-7)
- [`params`](#params-1)
- [`subActionParams (pushToService)`](#subactionparams-pushtoservice-1)
- [`subActionParams (getIncident)`](#subactionparams-getincident-1)
- [`subActionParams (issueTypes)`](#subactionparams-issuetypes)
Expand All @@ -77,9 +49,7 @@ Table of Contents
- [`subActionParams (issue)`](#subactionparams-issue)
- [`subActionParams (getFields)`](#subactionparams-getfields-1)
- [IBM Resilient](#ibm-resilient)
- [`config`](#config-8)
- [`secrets`](#secrets-8)
- [`params`](#params-8)
- [`params`](#params-2)
- [`subActionParams (pushToService)`](#subactionparams-pushtoservice-2)
- [`subActionParams (getFields)`](#subactionparams-getfields-2)
- [`subActionParams (incidentTypes)`](#subactionparams-incidenttypes)
Expand Down Expand Up @@ -272,6 +242,160 @@ const result = await actionsClient.execute({

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).

In addition to the documented configurations, several built in action type offer additional `params` configurations.

## ServiceNow

The [ServiceNow user documentation `params`](https://www.elastic.co/guide/en/kibana/master/servicenow-action-type.html) lists configuration properties for the `pushToService` subaction. In addition, several other subaction types are available.
### `params`

| Property | Description | Type |
| --------------- | -------------------------------------------------------------------------------------------------- | ------ |
| subAction | The subaction to perform. It can be `pushToService`, `getFields`, `getIncident`, and `getChoices`. | string |
| subActionParams | The parameters of the subaction. | 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 present, the incident is updated. Otherwise, a new incident is created. | string _(optional)_ |
| severity | The severity in ServiceNow. | string _(optional)_ |
| urgency | The urgency in ServiceNow. | string _(optional)_ |
| impact | The impact in ServiceNow. | string _(optional)_ |
| category | The category in ServiceNow. | string _(optional)_ |
| subcategory | The subcategory in ServiceNow. | string _(optional)_ |

#### `subActionParams (getFields)`

No parameters for the `getFields` subaction. 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

The [Jira user documentation `params`](https://www.elastic.co/guide/en/kibana/master/jira-action-type.html) lists configuration properties for the `pushToService` subaction. In addition, several other subaction types are available.
### `params`

| Property | Description | Type |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| subAction | The subaction to perform. It can be `pushToService`, `getIncident`, `issueTypes`, `fieldsByIssueType`, `issues`, `issue`, and `getFields`. | string |
| subActionParams | The parameters of the subaction. | 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 present, the incident is updated. Otherwise, a new incident is 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 ID or key of the parent issue. 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 the `issueTypes` subaction. 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 the `getFields` subaction. Provide an empty object `{}`.

---
## IBM Resilient

The [IBM Resilient user documentation `params`](https://www.elastic.co/guide/en/kibana/master/resilient-action-type.html) lists configuration properties for the `pushToService` subaction. In addition, several other subaction types are available.

### `params`

| Property | Description | Type |
| --------------- | -------------------------------------------------------------------------------------------------- | ------ |
| subAction | The subaction to perform. It can be `pushToService`, `getFields`, `incidentTypes`, and `severity. | string |
| subActionParams | The parameters of the subaction. | 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 present, the incident is updated. Otherwise, a new incident is 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 the `getFields` subaction. Provide an empty object `{}`.

#### `subActionParams (incidentTypes)`

No parameters for the `incidentTypes` subaction. Provide an empty object `{}`.

#### `subActionParams (severity)`

No parameters for the `severity` subaction. Provide an empty object `{}`.

---
# Command Line Utility

The [`kbn-action`](https://github.com/pmuellr/kbn-action) tool can be used to send HTTP requests to the Actions plugin. For instance, to create a Slack action from the `.slack` Action Type, use the following command:
Expand Down