OpenSearch/docs/en/rest-api/watcher/ack-watch.asciidoc

[[watcher-api-ack-watch]]
=== Ack Watch API

<<actions-ack-throttle, Acknowledging>> a watch enables you to manually throttle
execution of the watch's actions. An action's _acknowledgement state_ is stored
in the `status.actions.<id>.ack.state` structure.

To demonstrate let's create a new watch:

[source,js]
--------------------------------------------------
PUT _xpack/watcher/watch/my_watch
{
  "trigger": {
    "schedule": {
      "hourly": {
        "minute": [ 0, 5 ]
      }
    }
  },
  "input": {
    "simple": {
      "payload": {
        "send": "yes"
      }
    }
  },
  "condition": {
    "always": {}
  },
  "actions": {
    "test_index": {
      "throttle_period": "15m",
      "index": {
        "index": "test",
        "doc_type": "test2"
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TESTSETUP

The current status of a watch and the state of its actions is returned with the
watch definition when you call the <<watcher-api-get-watch, Get Watch API>>:

[source,js]
--------------------------------------------------
GET _xpack/watcher/watch/my_watch
--------------------------------------------------
// CONSOLE

The action state of a newly-created watch is `awaits_successful_execution`:

[source,js]
--------------------------------------------------
{
  "found": true,
  "_id": "my_watch",
  "status": {
    "version": 1,
    "actions": {
      "test_index": {
        "ack": {
          "timestamp": "2015-05-26T18:04:27.723Z",
          "state": "awaits_successful_execution"
        }
      }
    },
    "state": ...
  },
  "watch": ...
}
--------------------------------------------------
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]

When the watch executes and the condition matches, the value of the `ack.state`
changes to `ackable`. Let's force execution of the watch and fetch it again to
check the status:

[source,js]
--------------------------------------------------
POST _xpack/watcher/watch/my_watch/_execute
GET _xpack/watcher/watch/my_watch
--------------------------------------------------
// TEST[continued]

and the action is now in `ackable` state:

[source,js]
--------------------------------------------------
{
  "found": true,
  "_id": "my_watch",
  "status": {
    "version": 1,
    "actions": {
      "test_index": {
        "ack": {
          "timestamp": "2015-05-26T18:04:27.723Z",
          "state": "ackable"
        }
      }
    },
    "state": ...
  },
  "watch": ...
}
--------------------------------------------------
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]

Now we can acknowledge it:

[source,js]
--------------------------------------------------
PUT _xpack/watcher/watch/my_watch/_ack/test_index
GET _xpack/watcher/watch/my_watch
--------------------------------------------------
// CONSOLE

[source,js]
--------------------------------------------------
{
  "found": true,
  "_id": "my_watch",
  "status": {
    "version": 1,
    "actions": {
      "test_index": {
        "ack": {
          "timestamp": "2015-05-26T18:04:27.723Z",
          "state": "acknowledged"
        }
      }
    },
    "state": ...
  },
  "watch": ...
}
--------------------------------------------------
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]

Acknowledging an action throttles further executions of that action until its
`ack.state` is reset to `awaits_successful_execution`. This happens when the
condition of the watch is not met (the condition evaluates to `false`).

You can acknowledge multiple actions by assigning the `actions` parameter a
comma-separated list of action ids:

[source,js]
--------------------------------------------------
POST _xpack/watcher/watch/my_watch/_ack/action1,action2
--------------------------------------------------
// CONSOLE

To acknowledge all of the actions of a watch, simply omit the `actions`
parameter:

[source,js]
--------------------------------------------------
POST _xpack/watcher/watch/my_watch/_ack
--------------------------------------------------
// CONSOLE

[float]
==== Timeouts

If you acknowledge a watch while it is executing, the request blocks and waits
for the watch execution to finish. For some watches, this can take a significant
amount of time. By default, the acknowledge action has a timeout of 10 seconds.
You can change the timeout setting by specifying the `master_timeout` parameter.

The following snippet shows how to change the default timeout of the acknowledge
action to 30 seconds:

[source,js]
--------------------------------------------------
POST _xpack/watcher/watch/my_watch/_ack?master_timeout=30s
--------------------------------------------------
// CONSOLE

[float]
==== Response format
[source,js]

The response format looks like:

[source,js]
--------------------------------------------------
{
   "status": {
      "last_checked": "2015-05-26T18:21:08.630Z",
      "last_met_condition": "2015-05-26T18:21:08.630Z",
      "actions": {
         "my-action": {
            "ack_status": {
               "timestamp": "2015-05-26T18:21:09.982Z",
               "state": "acked"
            },
            "last_execution": {
               "timestamp": "2015-05-26T18:21:04.106Z",
               "successful": true
            },
            "last_successful_execution": {
               "timestamp": "2015-05-26T18:21:04.106Z",
               "successful": true
            },
            "last_throttle": {
               "timestamp": "2015-05-26T18:21:08.630Z",
               "reason": "throttling interval is set to [5 seconds] but time elapsed since last execution is [4 seconds and 530 milliseconds]"
            }
         }
      }
   }
}
--------------------------------------------------
// TESTRESPONSE