elasticsearch/docs/reference/rest-api/watcher/ack-watch.asciidoc

[role="xpack"]
[[watcher-api-ack-watch]]
=== Ack watch API
++++
<titleabbrev>Ack watch</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-watcher[{watcher} APIs].
--

<<actions-ack-throttle,Acknowledging a watch>> enables you
to manually throttle execution of the watch's actions.

[[watcher-api-ack-watch-request]]
==== {api-request-title}

`PUT _watcher/watch/<watch_id>/_ack` +

`PUT _watcher/watch/<watch_id>/_ack/<action_id>`

[[watcher-api-ack-watch-prereqs]]
==== {api-prereq-title}

* You must have `manage_watcher` cluster privileges to use this API. For more
information, see <<security-privileges>>.

[[watcher-api-ack-watch-desc]]
==== {api-description-title}

An action's _acknowledgement state_ is stored in the
`status.actions.<id>.ack.state` structure.

IMPORTANT: If the specified watch is currently being executed, this API will
return an error. The reason for this is to prevent overwriting of the watch
status from a watch execution.

[[watcher-api-ack-watch-path-params]]
==== {api-path-parms-title}

`<action_id>`::
  (Optional, list) A comma-separated list of the action IDs to acknowledge. If you omit
  this parameter, all of the actions of the watch are acknowledged.

`<watch_id>`::
  (Required, string) Identifier for the watch.

//[[watcher-api-ack-watch-query-params]]
//==== {api-query-parms-title}

//[[watcher-api-ack-watch-request-body]]
//==== {api-request-body-title}

//[[watcher-api-ack-watch-response-body]]
//==== {api-response-body-title}

//[[watcher-api-ack-watch-response-codes]]
//==== {api-response-codes-title}

[[watcher-api-ack-watch-example]]
==== {api-examples-title}

To demonstrate let's create a new watch:

[source,console]
--------------------------------------------------
PUT _watcher/watch/my_watch
{
  "trigger" : {
    "schedule" : {
      "yearly" : { "in" : "february", "on" : 29, "at" : "noon" }
    }
  },
  "input": {
    "simple": {
      "payload": {
        "send": "yes"
      }
    }
  },
  "condition": {
    "always": {}
  },
  "actions": {
    "test_index": {
      "throttle_period": "15m",
      "index": {
        "index": "test"
      }
    }
  }
}
--------------------------------------------------
// 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,console]
--------------------------------------------------
GET _watcher/watch/my_watch
--------------------------------------------------

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

[source,console-result]
--------------------------------------------------
{
  "found": true,
  "_seq_no": 0,
  "_primary_term": 1,
  "_version": 1,
  "_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,console]
--------------------------------------------------
POST _watcher/watch/my_watch/_execute
{
  "record_execution" : true
}

GET _watcher/watch/my_watch
--------------------------------------------------
// TEST[continued]

and the action is now in `ackable` state:

[source,console-result]
--------------------------------------------------
{
  "found": true,
  "_id": "my_watch",
  "_seq_no": 1,
  "_primary_term": 1,
  "_version": 2,
  "status": {
    "version": 2,
    "actions": {
      "test_index": {
        "ack": {
          "timestamp": "2015-05-26T18:04:27.723Z",
          "state": "ackable"
        },
        "last_execution" : {
          "timestamp": "2015-05-25T18:04:27.723Z",
          "successful": true
        },
        "last_successful_execution" : {
          "timestamp": "2015-05-25T18:04:27.723Z",
          "successful": true
        }
      }
    },
    "state": ...,
    "execution_state": "executed",
    "last_checked": ...,
    "last_met_condition": ...
  },
  "watch": ...
}
--------------------------------------------------
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
// TESTRESPONSE[s/"last_checked": \.\.\./"last_checked": "$body.status.last_checked"/]
// TESTRESPONSE[s/"last_met_condition": \.\.\./"last_met_condition": "$body.status.last_met_condition"/]
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.last_execution.timestamp"/]

Now we can acknowledge it:

[source,console]
--------------------------------------------------
PUT _watcher/watch/my_watch/_ack/test_index
GET _watcher/watch/my_watch
--------------------------------------------------
// TEST[continued]

[source,console-result]
--------------------------------------------------
{
  "found": true,
  "_id": "my_watch",
  "_seq_no": 2,
  "_primary_term": 1,
  "_version": 3,
  "status": {
    "version": 3,
    "actions": {
      "test_index": {
        "ack": {
          "timestamp": "2015-05-26T18:04:27.723Z",
          "state": "acked"
        },
        "last_execution" : {
          "timestamp": "2015-05-25T18:04:27.723Z",
          "successful": true
        },
        "last_successful_execution" : {
          "timestamp": "2015-05-25T18:04:27.723Z",
          "successful": true
        }
      }
    },
    "state": ...,
    "execution_state": "executed",
    "last_checked": ...,
    "last_met_condition": ...
  },
  "watch": ...
}
--------------------------------------------------
// TESTRESPONSE[s/"state": \.\.\./"state": "$body.status.state"/]
// TESTRESPONSE[s/"watch": \.\.\./"watch": "$body.watch"/]
// TESTRESPONSE[s/"last_checked": \.\.\./"last_checked": "$body.status.last_checked"/]
// TESTRESPONSE[s/"last_met_condition": \.\.\./"last_met_condition": "$body.status.last_met_condition"/]
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.723Z"/"timestamp": "$body.status.actions.test_index.last_execution.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,console]
--------------------------------------------------
POST _watcher/watch/my_watch/_ack/action1,action2
--------------------------------------------------

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

[source,console]
--------------------------------------------------
POST _watcher/watch/my_watch/_ack
--------------------------------------------------
// TEST[s/^/POST _watcher\/watch\/my_watch\/_execute\n{ "record_execution" : true }\n/]


The response looks like a get watch response, but only contains the status:

[source,console-result]
--------------------------------------------------
{
  "status": {
    "state": {
      "active": true,
      "timestamp": "2015-05-26T18:04:27.723Z"
    },
    "last_checked": "2015-05-26T18:04:27.753Z",
    "last_met_condition": "2015-05-26T18:04:27.763Z",
    "actions": {
      "test_index": {
        "ack" : {
          "timestamp": "2015-05-26T18:04:27.713Z",
          "state": "acked"
        },
        "last_execution" : {
          "timestamp": "2015-05-25T18:04:27.733Z",
          "successful": true
        },
        "last_successful_execution" : {
          "timestamp": "2015-05-25T18:04:27.773Z",
          "successful": true
        }
      }
    },
    "execution_state": "executed",
    "version": 2
  }
}

--------------------------------------------------
// TESTRESPONSE[s/"last_checked": "2015-05-26T18:04:27.753Z"/"last_checked": "$body.status.last_checked"/]
// TESTRESPONSE[s/"last_met_condition": "2015-05-26T18:04:27.763Z"/"last_met_condition": "$body.status.last_met_condition"/]
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.723Z"/"timestamp": "$body.status.state.timestamp"/]
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:04:27.713Z"/"timestamp": "$body.status.actions.test_index.ack.timestamp"/]
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.733Z"/"timestamp": "$body.status.actions.test_index.last_execution.timestamp"/]
// TESTRESPONSE[s/"timestamp": "2015-05-25T18:04:27.773Z"/"timestamp": "$body.status.actions.test_index.last_successful_execution.timestamp"/]