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 the lron_config object, the task runs one time and the setting is automatically deleted when the task ends. If you pass both task_id and action_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 not task_id in the lron_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.

ParameterTypeDescription
lron_configObjectLong-running index operation notification configuration.
task_idStringThe task ID of the task that you want to be notified about. Optional. One of task_id and action_name must be specified.
action_nameStringThe 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_conditionObjectSpecifies 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.successBooleanSet this parameter to true to be notified when the operation succeeds. Optional. Default is true.
lron_condition.failureBooleanSet this parameter to true to be notified when the operation fails or times out. Optional. Default is true.
channelsObjectSupported 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:

  1. POST /_plugins/_im/lron
  2. {
  3.   "lron_config": {
  4.       "task_id":"dQlcQ0hQS2mwF-AQ7icCMw:12354",
  5.       "action_name":"indices:data/write/reindex",
  6.       "lron_condition": {
  7.         "success": false,
  8.         "failure": true
  9.       },
  10.       "channels":[
  11.           {"id":"channel1"},
  12.           {"id":"channel2"}
  13.       ]
  14.   }
  15. }

copy

The preceding request results in the following response:

  1. {
  2.   "_id": "LRON:dQlcQ0hQS2mwF-AQ7icCMw:12354",
  3.   "lron_config": {
  4.     "lron_condition": {
  5.       "success": false,
  6.       "failure": true
  7.     },
  8.     "task_id": "dQlcQ0hQS2mwF-AQ7icCMw:12354",
  9.     "action_name": "indices:data/write/reindex",
  10.     "channels": [
  11.       {
  12.         "id": "channel1"
  13.       },
  14.       {
  15.         "id": "channel2"
  16.       }
  17.     ]
  18.   }
  19. }

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:

  1.  GET /_plugins/_im/lron/<lronID>

copy

For example, the following request retrieves the notification setting for the reindex operation:

  1. {
  2.   "lron_configs": [
  3.     {
  4.       "_id": "LRON:indices:data/write/reindex",
  5.       "lron_config": {
  6.         "lron_condition": {
  7.           "success": false,
  8.           "failure": true
  9.         },
  10.         "action_name": "indices:data/write/reindex",
  11.         "channels": [
  12.           {
  13.             "id": "my_chime"
  14.           }
  15.         ]
  16.       }
  17.     }
  18.   ],
  19.   "total_number": 1
  20. }

copy

Use the following request to retrieve all notification settings:

  1. GET /_plugins/_im/lron

copy

The response contains all configured notification settings with their IDs:

  1. {
  2.   "lron_configs": [
  3.     {
  4.       "_id": "LRON:indices:admin/open",
  5.       "lron_config": {
  6.         "lron_condition": {
  7.           "success": false,
  8.           "failure": false
  9.         },
  10.         "action_name": "indices:admin/open",
  11.         "channels": []
  12.       }
  13.     },
  14.     {
  15.       "_id": "LRON:indices:data/write/reindex",
  16.       "lron_config": {
  17.         "lron_condition": {
  18.           "success": false,
  19.           "failure": true
  20.         },
  21.         "action_name": "indices:data/write/reindex",
  22.         "channels": [
  23.           {
  24.             "id": "my_chime"
  25.           }
  26.         ]
  27.       }
  28.     }
  29.   ],
  30.   "total_number": 2
  31. }

Update notification settings

The following example modifies an existing notification setting with the specified notification setting ID:

  1. PUT /_plugins/_im/lron/<lronID>
  2. {
  3.   "lron_config": {
  4.       "task_id":"dQlcQ0hQS2mwF-AQ7icCMw:12354",
  5.       "action_name":"indices:data/write/reindex",
  6.       "lron_condition": {
  7.         "success": false,
  8.         "failure": true
  9.       },
  10.       "channels":[
  11.           {"id":"channel1"},
  12.           {"id":"channel2"}
  13.       ]
  14.   }
  15. }

copy

The response contains the updated setting:

  1. {
  2.   "_id": "LRON:dQlcQ0hQS2mwF-AQ7icCMw:12354",
  3.   "lron_config": {
  4.     "lron_condition": {
  5.       "success": false,
  6.       "failure": true
  7.     },
  8.     "task_id": "dQlcQ0hQS2mwF-AQ7icCMw:12354",
  9.     "action_name": "indices:data/write/reindex",
  10.     "channels": [
  11.       {
  12.         "id": "channel1"
  13.       },
  14.       {
  15.         "id": "channel2"
  16.       }
  17.     ]
  18.   }
  19. }

Delete notification settings

The following example removes a notifications setting with the specified notification setting ID:

  1. DELETE /_plugins/_im/lron/<lronID>

copy

For example, the following request deletes the notification setting for the reindex operation:

  1. DELETE _plugins/_im/lron/LRON:indices:data%2Fwrite%2Freindex

copy

Next steps