Skip to content

Commit c3ceb4d

Browse files
mikecotemikecote
authored
Actions & alerting getting started user guides (#39093)
* Initial user guides * Cleanup * Typos, example changes * Switch to tables, use ordered list for usage * Start docs around alert instances and templating * Documentation changes * Some adjustments * Apply PR feedback * Apply suggestions from code review Co-Authored-By: gchaps <[email protected]> * PR feedback pt2 * Provide better examples for alert types * Apply PR feedback * Update README locations
1 parent d771163 commit c3ceb4d

File tree

2 files changed

+481
-0
lines changed

2 files changed

+481
-0
lines changed

‎x-pack/legacy/plugins/actions/README.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Kibana actions
2+
3+
The Kibana actions plugin provides a common place to execute actions. You can:
4+
5+
- Register an action type
6+
- View a list of registered types
7+
- Fire an action either manually or by using an alert
8+
- Perform CRUD on actions with encrypted configurations
9+
10+
## Terminology
11+
12+
**Action Type**: A programatically defined integration with another service, with an expected set of configuration and parameters.
13+
14+
**Action**: A user-defined configuration that satisfies an action type's expected configuration.
15+
16+
## Usage
17+
18+
1. Develop and register an action type (see action types -> example).
19+
2. Create an action by using the RESTful API (see actions -> create action).
20+
3. Use alerts to fire actions or fire manually (see firing actions).
21+
22+
## Action types
23+
24+
### Methods
25+
26+
**server.plugins.actions.registerType(options)**
27+
28+
The following table describes the properties of the `options` object.
29+
30+
|Property|Description|Type|
31+
|---|---|---|
32+
|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 `<plugin_id>.mySpecialAction` for your action types.|string|
33+
|name|A user-friendly name for the action type. These will be displayed in dropdowns when chosing action types.|string|
34+
|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|
35+
|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). Use joi object validation if you would like `params` to be validated before being passed to the executor.|Joi schema|
36+
|validate.config|Similar to params, a config is required when creating an action (for example host, port, username, and password of an email server). Use the joi object validation if you would like the config to be validated before being passed to the executor.|Joi schema|
37+
|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|
38+
39+
### Executor
40+
41+
This is the primary function for an action type. Whenever the action needs to execute, this function will perform the action. It receives a variety of parameters. The following table describes the properties that the executor receives.
42+
43+
**executor(options)**
44+
45+
|Property|Description|
46+
|---|---|
47+
|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.|
48+
|params|Parameters for the execution. These will be given at fire time by either an alert or manually provided when calling the plugin provided fire function.|
49+
|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.<br><br>**NOTE**: This currently authenticates as the Kibana internal user, but will change in a future PR.|
50+
|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.<br><br>**NOTE**: This currently only works when security is disabled. A future PR will add support for enabling security using Elasticsearch API tokens.|
51+
|services.log(tags, [data], [timestamp])|Use this to create server logs. (This is the same function as server.log)|
52+
53+
### Example
54+
55+
Below is an example email action type. The attributes `host` and `port` are configured to be unencrypted by using the `unencryptedAttributes` attribute.
56+
57+
```
58+
server.plugins.actions.registerType({
59+
id: 'smtp',
60+
name: 'Email',
61+
unencryptedAttributes: ['host', 'port'],
62+
validate: {
63+
params: Joi.object()
64+
.keys({
65+
to: Joi.array().items(Joi.string()).required(),
66+
from: Joi.string().required(),
67+
subject: Joi.string().required(),
68+
body: Joi.string().required(),
69+
})
70+
.required(),
71+
config: Joi.object()
72+
.keys({
73+
host: Joi.string().required(),
74+
port: Joi.number().default(465),
75+
username: Joi.string().required(),
76+
password: Joi.string().required(),
77+
})
78+
.required(),
79+
},
80+
async executor({ config, params, services }) {
81+
const transporter = nodemailer. createTransport(config);
82+
await transporter.sendMail(params);
83+
},
84+
});
85+
```
86+
87+
## RESTful API
88+
89+
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.
90+
91+
#### `POST /api/action`: Create action
92+
93+
Payload:
94+
95+
|Property|Description|Type|
96+
|---|---|---|
97+
|attributes.description|A description to reference and search in the future. This value will be used to populate dropdowns.|string|
98+
|attributes.actionTypeId|The id value of the action type you want to call when the action executes.|string|
99+
|attributes.actionTypeConfig|The configuration the action type expects. See related action type to see what attributes is expected. This will also validate against the action type if config validation is defined.|object|
100+
|references|An array of `name`, `type` and `id`. This is the same as `references` in the saved objects API. See the saved objects API documentation.<br><br>In most cases, you can leave this empty.|Array|
101+
|migrationVersion|The version of the most recent migrations. This is the same as `migrationVersion` in the saved objects API. See the saved objects API documentation.<br><br>In most cases, you can leave this empty.|object|
102+
103+
#### `DELETE /api/action/{id}`: Delete action
104+
105+
Params:
106+
107+
|Property|Description|Type|
108+
|---|---|---|
109+
|id|The id of the action you're trying to delete.|string|
110+
111+
#### `GET /api/action/_find`: Find actions
112+
113+
Params:
114+
115+
See the saved objects API documentation for find. All the properties are the same except that you cannot pass in `type`.
116+
117+
#### `GET /api/action/{id}`: Get action
118+
119+
Params:
120+
121+
|Property|Description|Type|
122+
|---|---|---|
123+
|id|The id of the action you're trying to get.|string|
124+
125+
#### `GET /api/action/types` List action types
126+
127+
No parameters.
128+
129+
#### `PUT /api/action/{id}`: Update action
130+
131+
Params:
132+
133+
|Property|Description|Type|
134+
|---|---|---|
135+
|id|The id of the action you're trying to update.|string|
136+
137+
Payload:
138+
139+
|Property|Description|Type|
140+
|---|---|---|
141+
|attributes.description|A description to reference and search in the future. This value will be used to populate dropdowns.|string|
142+
|attributes.actionTypeConfig|The configuration the action type expects. See related action type to see what attributes is expected. This will also validate against the action type if config validation is defined.|object|
143+
|references|An array of `name`, `type` and `id`. This is the same as `references` in the saved objects API. See the saved objects API documentation.<br><br>In most cases, you can leave this empty.|Array|
144+
|version|The document version when read|string|
145+
146+
## Firing actions
147+
148+
The plugin exposes a fire function that you can use to fire actions.
149+
150+
**server.plugins.actions.fire(options)**
151+
152+
The following table describes the properties of the `options` object.
153+
154+
|Property|Description|Type|
155+
|---|---|---|
156+
|id|The id of the action you want to fire.|string|
157+
|params|The `params` value to give the action type executor.|object|
158+
|namespace|The saved object namespace the action exists within.|string|
159+
|basePath|This is a temporary parameter, but we need to capture and track the value of `request.getBasePath()` until future changes are made.<br><br>In most cases this can be `undefined` unless you need cross spaces support.|string|
160+
161+
### Example
162+
163+
This example makes action `3c5b2bd4-5424-4e4b-8cf5-c0a58c762cc5` fire an email. The action plugin will load the saved object and find what action type to call with `params`.
164+
165+
```
166+
server.plugins.actions.fire({
167+
id: '3c5b2bd4-5424-4e4b-8cf5-c0a58c762cc5',
168+
params: {
169+
from: '[email protected]',
170+
to: ['[email protected]'],
171+
subject: 'My email subject',
172+
body: 'My email body',
173+
},
174+
namespace: undefined, // The namespace the action exists within
175+
basePath: undefined, // Usually `request.getBasePath();` or `undefined`
176+
});
177+
```

0 commit comments

Comments
 (0)