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

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.