Add backend documentation about configuring ISM notifications

[vagimeli]

Description

Add new documentation about configuring notifications for ISM API

Issues Resolved

#4170

Checklist

• By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
  For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[vagimeli]

See frontend documentation for reference #4207

[zhichao-aws]

Great work, but still need some changes

[zhichao-aws]

Do we have a better expression for abbreviations than "xxxx"? e.g. add a line of comment?

[vagimeli]

What would be an appropriate expression example?

[zhichao-aws]

Great work, but still need some changes

[kolchfa-aws]

I think the reference to Dev Tools in Dashboards is confusing. The way to do it using the UI is to go to index management > Notifications. If the user is doing it through the API, they can use curl or dev tools. Normally, we don't direct them to dev tools from an individual API page. How about

Suggested change

	To configure configure the notifications settings for long-running index operations using OpenSearch Dashboards, go to **Dev Tools** under the main menu. When creating notifications using the API, the LRON setting can be configured two ways: as a concrete task or as a global and persistent task. The LRON setting with `task_id` is ad hoc and automatically deletes when the task ends. The LRON setting using `action_name` is global and persists and applies to all operations of this action type.
	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:
	- 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.

[kolchfa-aws]

@zhichao-aws Some questions:

• Where do you get the task_id from?
• In the example below, both task_id and action_name are passed. What happens in this case?
• For the request and response, we have to provide descriptions for all fields and the possible values for enum fields. Could you help with that? Also, what are the possible values for action_name? For lron_condition, are the possible values only success and failure? Which fields are required and which are optional?

[zhichao-aws]

• The task id can be obtained by setting the request parameter wait_for_completion as false for open/reindex/resize/force merge. Make some long running operations execute asynchronously and can be tracked by _tasks API OpenSearch#6228. The index operation will return the task id immediately and execute at the background.
• Infact if task_id has higher priority. If task_id is passed, action_name will be ignored in our code. But it may be useful if user want to search settings about certain actions.
• For lron_condition, it only has success and failure. Both of them are optional, the value is true by default. lron_condition itself is optional (true, true by default). For action_name, current possible values are "indices:data/write/reindex", "indices:admin/resize", "indices:admin/forcemerge", "indices:admin/open".

[zhichao-aws]

The config must contain taskID or actionName. And enabled lron_config(i.e. at least there is one true in lron_condition) must contain at least one channel

[kolchfa-aws]

Thanks a lot, @zhichao-aws! Could you also provide an actual example of a request and response for each section where we have them? Thanks!

[zhichao-aws]

Do you mean create/update/read/delete section, or the cases we talked above?

[kolchfa-aws]

create/update/read/delete. Basically, wherever we have requests/response placeholders now we should have actual requests/responses.

[zhichao-aws]

create/update are actual requests/responses. Here are actual responses of get/delete:
request:
GET _plugins/_im/lron
response:

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

request:
GET _plugins/_im/lron/LRON:indices:data%2Fwrite%2Freindex
response:

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

request:
DELETE _plugins/_im/lron/LRON:indices:data%2Fwrite%2Freindex
response(same with delete doc in opensearch normal index):

{
  "_index": ".opensearch-control-center",
  "_id": "LRON:indices:data/write/reindex",
  "_version": 2,
  "result": "deleted",
  "forced_refresh": true,
  "_shards": {
    "total": 2,
    "successful": 2,
    "failed": 0
  },
  "_seq_no": 2,
  "_primary_term": 1
}

[kolchfa-aws]

Suggested change

	GET /_plugins/_im/lron/{lronID}
	GET /_plugins/_im/lron/<lronID>

[kolchfa-aws]

@zhichao-aws Is the the _id from the response when you create an lron setting?

[kolchfa-aws]

Add a description of the lronID path parameter.

[kolchfa-aws]

Global: include copy-curl for all requests and make them json instead of bash.

[zhichao-aws]

Yes, it is the _id from the response. For global lron_config, it will be "LRON:"+action_name. For one-time lron_config, it will be "LRON:"+task_id.
Here is one thing I want to call out, there maybe char "/" in action_name, and it may be in _id. If users are using dev tools, they will need to use http encode to transfer "/" to "%2F" in action name. e.g. PUT _plugins/_im/lron/LRON:indices:admin%2Fopen in dev tools

[zhichao-aws]

To be precise, If you pass an action_name and not pass the "task_id", then it's global and persistent

[kolchfa-aws]

@zhichao-aws Could you review the updated documentation and either comment or approve if everything looks good? Thanks!

[zhichao-aws]

I think the wording "One-time setting" or "Global, persistent setting" may be better. The "task" here may cause confusion with the "task_id" task.

[kolchfa-aws]

@zhichao-aws Implemented, thanks. The PR is ready for your final review.

[zhichao-aws]

Great work, looks good to me.

[vagimeli]

@kolchfa-aws minimal edits

[vagimeli]

What would be an appropriate expression example?

[kolchfa-aws]

LGTM

[hdhalter]

Just a few suggestions. Looks good!

[hdhalter]

Suggested change

	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:
	When creating long-running operation notifications using the API, you can configure the `lron_config` object using the `task_id` and `action_name` parameters as follows:

[kolchfa-aws]

Reworded.