Skip to content

Commit

Permalink
[Actions][Docs] Moving subaction and subaction params back to README (#…
Browse files Browse the repository at this point in the history 
…92878)

* Moving subaction and subaction params back to README

* Apply suggestions from code review

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* PR fixes

Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
  • Loading branch information
@ymao1 @kibanamachine @gchaps
3 people authored Mar 2, 2021
1 parent 84dc217 commit 3dd3297
Show file tree
Hide file tree
Showing 4 changed files with 175 additions and 122 deletions.
45 changes: 7 additions & 38 deletions docs/user/alerting/action-types/jira.asciidoc
View file
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
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
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
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

0 comments on commit 3dd3297

Please sign in to comment.