You're viewing version 2.13 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Notification settings
Introduced 2.8
You can use notification settings to configure notifications about long-running index operations. Set up automatic notifications when long-running index operations are complete by using Notifications in OpenSearch Dashboards or through the API.
Configuring notification settings is useful for long-running index operations, such as open
, reindex
, resize
, and force merge
. When you send a request for those operations and set the wait_for_completion
parameter to false
, the operation returns immediately and the response contains a task ID. You can use that task ID to configure notifications for this operation.
Configuring notification settings
You can configure long-running operation notifications through the API by using the task_id
and action_name
parameters:
- One-time setting: If you pass
task_id
in thelron_config
object, the task runs one time and the setting is automatically deleted when the task ends. If you pass bothtask_id
andaction_name
,action_name
is ignored but may be useful to you for searching and debugging notification settings. - Global, persistent setting: If you pass
action_name
and nottask_id
in thelron_config
object, the task is global and persistent and applies to all operations of this action type.
The following table lists the parameters for long-running index operation notifications.
Parameter | Type | Description |
---|---|---|
lron_config | Object | Long-running index operation notification configuration. |
task_id | String | The task ID of the task that you want to be notified about. Optional. One of task_id and action_name must be specified. |
action_name | String | The operation type that you want to be notified about. Provide action_name but not task_id to be notified of all operations of this type. Supported values are indices:data/write/reindex , indices:admin/resize , indices:admin/forcemerge , and indices:admin/open . Optional. One of task_id and action_name must be specified. |
lron_condition | Object | Specifies which events you want to be notified about. Optional. If not provided, you’ll be notified of both the operation success and failure. |
lron_condition.success | Boolean | Set this parameter to true to be notified when the operation succeeds. Optional. Default is true . |
lron_condition.failure | Boolean | Set this parameter to true to be notified when the operation fails or times out. Optional. Default is true . |
channels | Object | Supported communication channels include Amazon Chime, Amazon Simple Notification Service (Amazon SNS), Amazon Simple Email Service (Amazon SES), email through SMTP, Slack, and custom webhooks. If either lron_condition.success or lron_condition.failure is true , channels must contain at least one channel. Learn how to configure notification channels in Notifications. |
Create notification settings
The following example request sets up notifications on a failure of a reindex task:
POST /_plugins/_im/lron
{
"lron_config": {
"task_id":"dQlcQ0hQS2mwF-AQ7icCMw:12354",
"action_name":"indices:data/write/reindex",
"lron_condition": {
"success": false,
"failure": true
},
"channels":[
{"id":"channel1"},
{"id":"channel2"}
]
}
}
The preceding request results in the following response:
{
"_id": "LRON:dQlcQ0hQS2mwF-AQ7icCMw:12354",
"lron_config": {
"lron_condition": {
"success": false,
"failure": true
},
"task_id": "dQlcQ0hQS2mwF-AQ7icCMw:12354",
"action_name": "indices:data/write/reindex",
"channels": [
{
"id": "channel1"
},
{
"id": "channel2"
}
]
}
}
Notification setting ID
The response returns an ID for the notification setting in the _id
field. You can use this ID to read, update, or delete this notification setting. For a global lron_config
, the ID is in the form LRON:<action_name>
(for example, LRON:indices:data/write/reindex
).
The action_name
may contain a slash character (/
), which must be HTTP encoded as %2F
if you use it the Dev Tools console. For example, LRON:indices:data/write/reindex
becomes LRON:indices:data%2Fwrite%2Freindex
.
For a task lron_config
, the ID is in the form LRON:<task ID>
.
Retrieve notification settings
The following examples retrieve the current configured notification settings.
Use the following request to retrieve a notification setting with the specified notification setting ID:
GET /_plugins/_im/lron/<lronID>
For example, the following request retrieves the notification setting for the reindex
operation:
{
"lron_configs": [
{
"_id": "LRON:indices:data/write/reindex",
"lron_config": {
"lron_condition": {
"success": false,
"failure": true
},
"action_name": "indices:data/write/reindex",
"channels": [
{
"id": "my_chime"
}
]
}
}
],
"total_number": 1
}
Use the following request to retrieve all notification settings:
GET /_plugins/_im/lron
The response contains all configured notification settings with their IDs:
{
"lron_configs": [
{
"_id": "LRON:indices:admin/open",
"lron_config": {
"lron_condition": {
"success": false,
"failure": false
},
"action_name": "indices:admin/open",
"channels": []
}
},
{
"_id": "LRON:indices:data/write/reindex",
"lron_config": {
"lron_condition": {
"success": false,
"failure": true
},
"action_name": "indices:data/write/reindex",
"channels": [
{
"id": "my_chime"
}
]
}
}
],
"total_number": 2
}
Update notification settings
The following example modifies an existing notification setting with the specified notification setting ID:
PUT /_plugins/_im/lron/<lronID>
{
"lron_config": {
"task_id":"dQlcQ0hQS2mwF-AQ7icCMw:12354",
"action_name":"indices:data/write/reindex",
"lron_condition": {
"success": false,
"failure": true
},
"channels":[
{"id":"channel1"},
{"id":"channel2"}
]
}
}
The response contains the updated setting:
{
"_id": "LRON:dQlcQ0hQS2mwF-AQ7icCMw:12354",
"lron_config": {
"lron_condition": {
"success": false,
"failure": true
},
"task_id": "dQlcQ0hQS2mwF-AQ7icCMw:12354",
"action_name": "indices:data/write/reindex",
"channels": [
{
"id": "channel1"
},
{
"id": "channel2"
}
]
}
}
Delete notification settings
The following example removes a notifications setting with the specified notification setting ID:
DELETE /_plugins/_im/lron/<lronID>
For example, the following request deletes the notification setting for the reindex
operation:
DELETE _plugins/_im/lron/LRON:indices:data%2Fwrite%2Freindex
Next steps
- Learn more about the ISM API.
- Learn more about the Notifications application.