Add backend documentation about configuring ISM notifications

_im-plugin/notifications-settings.md

@@ -1,41 +1,40 @@
 ---
 layout: default
-title: Configuring notifications settings
-parent: Managing indexes
+title: Notification settings
 nav_order: 100
 ---
 
-## Configuring notifications settings
+# Notification settings
 
 Introduced 2.8
 {: .label .label-purple }
 
-Notifications settings allow users to control how they receive notifications about index events. Set up automatic [notifications]({{site.url}}{{site.baseurl}}/observing-your-data/notifications/index/) when long-running index operations are complete by [using OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/im-dashboards/notifications/), the command line, or [index state management (ISM) policies]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/).
+Use notification settings to configure notifications about long-running index operations. Set up automatic [notifications]({{site.url}}{{site.baseurl}}/observing-your-data/notifications/index/) when long-running index operations are complete by [using Notifications in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/im-dashboards/notifications/) or through the API.
 
-Configuring notifications settings is useful for long-running index operations. When creating long-running operation notifications using the API, you can configure the `lron_config` setting in two ways:
+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 will return immediately and the response will contain a task ID. You can use that task ID to configure notifications for this operation.
 
-- As a one-time task: If you pass a `task_id` in the `lron_config` object, the task is one-time and the setting automatically deletes when the task ends.
-- As a global and persistent task: If you pass an `action_name` in the `lron_config` object, the task is global, persistent, and applies to all operations of this action type.
+## Configuring notification settings
 
-The following table lists the parameters for long-running index operations. 
+When creating long-running operation notifications using the API, you can configure the `lron_config` using the `task_id` and `action_name` parameters as follows:
 
-| Parameter | Type | Description |
-| :--- | :--- | :--- |
-| `lron_config` | String | Long-running index operation configuration setting. |
-| `task_id` | String | The identifier assigned to a specific task or operation. Optional. |
-| `action_name` | String | Specifies a specific action or operation to be performed. Supported actions are resize, reindex, open index, and force merge. Optional. |
-| `lron_condition` | String | Specifies one or more conditions that must be met for the event to be handled. Conditions are `success` or `failure`. If either condition is set to `true`, you receive a notification through the specified channel when the operation succeeds or fails. If either condition is set to `false`, you do not receive a notification when the operation succeeds or fails. Required. |
-| `channels.id` | String | 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. Required. |
-| `lron_config._id` | String | <description> |
+- **One-time task**: If you pass a `task_id` in the `lron_config` object, the task is 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 task**: If you pass an `action_name` and don't pass a `task_id` in the `lron_config` object, the task is global, persistent, and applies to all operations of this action type.
 
+The following table lists the parameters for long-running index operation notifications. 
 
-## Create, read, update, and delete (CRUD) operations
-
-The following examples show how to configure notifications settings for long-running index operations. 
+| 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]({{site.url}}{{site.baseurl}}/observing-your-data/notifications/index/). |
 
-### Create 
+## Create notification settings 
 
-The following example request creates the notification:
+The following example request sets up notifications on a failure of a reindex task:
 
 ```json
 POST /_plugins/_im/lron
@@ -80,24 +79,34 @@ The preceding request results in the following response:
 }
 ```
 
-## Read
+### 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}
 
-The following examples retrieve the current notifications settings for a user or group. This information can be used to determine what types of notifications the user or group is currently receiving, and to make changes to the notifications settings as needed. 
+For a task `lron_config`, the ID is in the form `LRON:<task ID>`.
 
+## Retrieve notification settings 
 
-The following example shows how to get one document:
+The following examples retrieve the current configured notification settings. 
+
+Use the following request to retrieve a notification setting with the specified [notification setting ID](#notification-setting-id):
 
 ```json
  GET /_plugins/_im/lron/<lronID>
 ```
+{% include copy-curl.html %}
 
-The following example shows how to get all documents:
+Use the following request to retrieve all notification settings:
 
-```bash
+```json
 GET /_plugins/_im/lron
 ```
+{% include copy-curl.html %}
 
-which result in the following response: 
+The response contains all configured notification settings with their IDs: 
 
 ```json
 {
@@ -119,12 +128,12 @@ which result in the following response:
 }
 ```
 
-## Update
+## Update notification settings 
 
-The following example modifies an existing notifications setting:
+The following example modifies an existing notification setting with the specified [notification setting ID](#notification-setting-id):
 
 ```json
-PUT /_plugins/_im/lron/{lronID}
+PUT /_plugins/_im/lron/<lronID>
 {
   "lron_config": {
       "task_id":"dQlcQ0hQS2mwF-AQ7icCMw:12354",
@@ -140,8 +149,9 @@ PUT /_plugins/_im/lron/{lronID}
   }
 }
 ```
+{% include copy-curl.html %}
 
-which results in the following response:
+The response contains the updated setting:
 
 ```json
 {
@@ -165,13 +175,14 @@ which results in the following response:
 }
 ```
 
-## Delete 
+## Delete notification settings 
 
-The following example shows how to remove a notifications setting:
+The following example shows how to remove a notifications setting with the specified [notification setting ID](#notification-setting-id):
 
 ```json
 DELETE /_plugins/_im/lron/<lronID>
 ```
+{% include copy-curl.html %}
 
 ## Next steps