IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Execute watch API Activate watch API »

› › ›

Ack watch API

edit

Ack watch API

edit

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.

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.

Request

edit

PUT _xpack/watcher/watch/<watch_id>/_ack

PUT _xpack/watcher/watch/<watch_id>/_ack/<action_id>

Path Parameters

edit

action_id: (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.

Authorization

edit

You must have manage_watcher cluster privileges to use this API. For more information, see Security privileges.

Examples

edit

To demonstrate let’s create a new watch:

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

The current status of a watch and the state of its actions is returned with the watch definition when you call the Get Watch API:

GET _xpack/watcher/watch/my_watch

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

{
  "found": true,
  "_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": ...
}

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:

POST _xpack/watcher/watch/my_watch/_execute
{
  "record_execution" : true
}

GET _xpack/watcher/watch/my_watch

and the action is now in ackable state:

{
  "found": true,
  "_id": "my_watch",
  "_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": ...
}

Now we can acknowledge it:

PUT _xpack/watcher/watch/my_watch/_ack/test_index
GET _xpack/watcher/watch/my_watch

{
  "found": true,
  "_id": "my_watch",
  "_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": ...
}

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:

POST _xpack/watcher/watch/my_watch/_ack/action1,action2

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

POST _xpack/watcher/watch/my_watch/_ack

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

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

« Execute watch API Activate watch API »