Merge pull request #395 from dbbaughe/patch-1

Updates ISM change policy API docs

Author: ashwinkumar12345

docs/ism/api.md

@@ -396,7 +396,11 @@ POST _opendistro/_ism/remove/index_1
 
 ## Update managed index policy
 
-Updates the managed index policy to a new policy (or to a new version of the policy). You can use an index pattern to update multiple indices at once. When updating multiple indices, you might want to include a state filter to only affect certain managed indices.
+Updates the managed index policy to a new policy (or to a new version of the policy). You can use an index pattern to update multiple indices at once. When updating multiple indices, you might want to include a state filter to only affect certain managed indices. This will filter out all the existing managed indices and only apply the change to the ones in the specified state. You can also directly set the state the managed index should transition to after the change policy happens.
+
+The changing of a policy is an asynchronous background process. The change is queued up to happen instead of taking affect immediately. This is to protect the currently running managed indices from being put into a broken state. If the policy you are changing to only has some small configuration changes such as changing `min_index_age` in the rollover condition from `"1000d"` to `"100d"` then the change will happen immediately on the next execution. If the change modifies the state, actions, or order of actions of the current state the index is in then it will happen at the end of the current state before transitioning to a new state.
+
+The example below is changing the policy on the index `index_1` to `policy_1` which could be a completely new policy or an updated version of the existing policy. It will only apply the change if the index is currently in the `searches` state. And once the change goes through it will transition to the `delete` state and start from there.
 
 #### Request