Link Search Menu Expand Document Documentation Menu

You're viewing version 2.16 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 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.

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