Notification settings

Introduced 0.1.0

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.