OpenSearch-Docs-Cn/_im-plugin/notifications-settings.md

layout, title, nav_order

layout	title	nav_order
default	Notification settings	100

Notification settings

Introduced 2.8 {: .label .label-purple }

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"}
      ]
  }
}

{% include copy-curl.html %}

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. {: .important}

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>

{% include copy-curl.html %}

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
}

{% include copy-curl.html %}

Use the following request to retrieve all notification settings:

GET /_plugins/_im/lron

{% include copy-curl.html %}

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"}
      ]
  }
}

{% include copy-curl.html %}

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>

{% include copy-curl.html %}

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

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

{% include copy-curl.html %}

Next steps

• Learn more about the ISM API.
• Learn more about the Notifications application.