[role="xpack"]
[[watcher-api-execute-watch]]
=== Execute watch API
++++
Execute watch
++++
The execute watch API forces the execution of a stored watch. It can be used to
force execution of the watch outside of its triggering logic, or to simulate the
watch execution for debugging purposes.
[float]
==== Request
`POST _watcher/watch//_execute` +
`POST _watcher/watch/_execute`
[float]
==== Description
For testing and debugging purposes, you also have fine-grained control on how
the watch runs. You can execute the watch without executing all of its actions
or alternatively by simulating them. You can also force execution by ignoring
the watch condition and control whether a watch record would be written to the
watch history after execution.
[float]
[[watcher-api-execute-inline-watch]]
===== Inline Watch Execution
You can use the Execute API to execute watches that are not yet registered by
specifying the watch definition inline. This serves as great tool for testing
and debugging your watches prior to adding them to {watcher}.
[float]
==== Path Parameters
`watch_id`::
(string) Identifier for the watch.
[float]
==== Query Parameters
`debug`::
(boolean) Defines whether the watch runs in debug mode. The default value is
`false`.
[float]
==== Request Body
This API supports the following fields:
[cols=",^,^,", options="header"]
|======
| Name | Required | Default | Description
| `trigger_data` | no | | This structure is parsed as the data of the trigger event
that will be used during the watch execution
| `ignore_condition` | no | false | When set to `true`, the watch execution uses the
{stack-ov}/condition-always.html[Always Condition].
This can also be specified as an HTTP parameter.
| `alternative_input` | no | null | When present, the watch uses this object as a payload
instead of executing its own input.
| `action_modes` | no | null | Determines how to handle the watch actions as part of the
watch execution. See <>
for more information.
| `record_execution` | no | false | When set to `true`, the watch record representing the watch
execution result is persisted to the `.watcher-history`
index for the current time. In addition, the status of the
watch is updated, possibly throttling subsequent executions.
This can also be specified as an HTTP parameter.
| `watch` | no | null | When present, this
{stack-ov}/how-watcher-works.html#watch-definition[watch] is used
instead of the one specified in the request. This watch is
not persisted to the index and record_execution cannot be set.
|======
[float]
[[watcher-api-execute-watch-action-mode]]
===== Action Execution Modes
Action modes define how actions are handled during the watch execution. There
are five possible modes an action can be associated with:
[options="header"]
|======
| Name | Description
| `simulate` | The action execution is simulated. Each action type
define its own simulation operation mode. For example, the
{stack-ov}/actions-email.html[email] action creates
the email that would have been sent but does not actually
send it. In this mode, the action might be throttled if the
current state of the watch indicates it should be.
| `force_simulate` | Similar to the the `simulate` mode, except the action is
not be throttled even if the current state of the watch
indicates it should be.
| `execute` | Executes the action as it would have been executed if the
watch would have been triggered by its own trigger. The
execution might be throttled if the current state of the
watch indicates it should be.
| `force_execute` | Similar to the `execute` mode, except the action is not
throttled even if the current state of the watch indicates
it should be.
| `skip` | The action is skipped and is not executed or simulated.
Effectively forces the action to be throttled.
|======
[float]
==== Authorization
You must have `manage_watcher` cluster privileges to use this API. For more
information, see {stack-ov}/security-privileges.html[Security Privileges].
[float]
==== Security Integration
When {es} {security-features} are enabled on your cluster, watches
are executed with the privileges of the user that stored the watches. If your
user is allowed to read index `a`, but not index `b`, then the exact same set of
rules will apply during execution of a watch.
When using the execute watch API, the authorization data of the user that
called the API will be used as a base, instead of of the information who stored
the watch.
[float]
==== Examples
The following example executes the `my_watch` watch:
[source,js]
--------------------------------------------------
POST _watcher/watch/my_watch/_execute
--------------------------------------------------
// CONSOLE
// TEST[setup:my_active_watch]
The following example shows a comprehensive example of executing the `my-watch` watch:
[source,js]
--------------------------------------------------
POST _watcher/watch/my_watch/_execute
{
"trigger_data" : { <1>
"triggered_time" : "now",
"scheduled_time" : "now"
},
"alternative_input" : { <2>
"foo" : "bar"
},
"ignore_condition" : true, <3>
"action_modes" : {
"my-action" : "force_simulate" <4>
},
"record_execution" : true <5>
}
--------------------------------------------------
// CONSOLE
// TEST[setup:my_active_watch]
<1> The triggered and schedule times are provided.
<2> The input as defined by the watch is ignored and instead the provided input
is used as the execution payload.
<3> The condition as defined by the watch is ignored and is assumed to
evaluate to `true`.
<4> Forces the simulation of `my-action`. Forcing the simulation means that
throttling is ignored and the watch is simulated by {watcher} instead of
being executed normally.
<5> The execution of the watch creates a watch record in the watch history,
and the throttling state of the watch is potentially updated accordingly.
This is an example of the output:
[source,js]
--------------------------------------------------
{
"_id": "my_watch_0-2015-06-02T23:17:55.124Z", <1>
"watch_record": { <2>
"watch_id": "my_watch",
"node": "my_node",
"messages": [],
"trigger_event": {
"type": "manual",
"triggered_time": "2015-06-02T23:17:55.124Z",
"manual": {
"schedule": {
"scheduled_time": "2015-06-02T23:17:55.124Z"
}
}
},
"state": "executed",
"status": {
"version": 1,
"execution_state": "executed",
"state": {
"active": true,
"timestamp": "2015-06-02T23:17:55.111Z"
},
"last_checked": "2015-06-02T23:17:55.124Z",
"last_met_condition": "2015-06-02T23:17:55.124Z",
"actions": {
"test_index": {
"ack": {
"timestamp": "2015-06-02T23:17:55.124Z",
"state": "ackable"
},
"last_execution": {
"timestamp": "2015-06-02T23:17:55.124Z",
"successful": true
},
"last_successful_execution": {
"timestamp": "2015-06-02T23:17:55.124Z",
"successful": true
}
}
}
},
"input": {
"simple": {
"payload": {
"send": "yes"
}
}
},
"condition": {
"always": {}
},
"result": { <3>
"execution_time": "2015-06-02T23:17:55.124Z",
"execution_duration": 12608,
"input": {
"type": "simple",
"payload": {
"foo": "bar"
},
"status": "success"
},
"condition": {
"type": "always",
"met": true,
"status": "success"
},
"actions": [
{
"id": "test_index",
"index": {
"response": {
"index": "test",
"type": "_doc",
"version": 1,
"created": true,
"result": "created",
"id": "AVSHKzPa9zx62AzUzFXY"
}
},
"status": "success",
"type": "index"
}
]
},
"user": "test_admin" <4>
}
}
--------------------------------------------------
// TESTRESPONSE[s/my_watch_0-2015-06-02T23:17:55.124Z/$body._id/]
// TESTRESPONSE[s/"triggered_time": "2015-06-02T23:17:55.124Z"/"triggered_time": "$body.watch_record.trigger_event.triggered_time"/]
// TESTRESPONSE[s/"scheduled_time": "2015-06-02T23:17:55.124Z"/"scheduled_time": "$body.watch_record.trigger_event.manual.schedule.scheduled_time"/]
// TESTRESPONSE[s/"execution_time": "2015-06-02T23:17:55.124Z"/"execution_time": "$body.watch_record.result.execution_time"/]
// TESTRESPONSE[s/"timestamp": "2015-06-02T23:17:55.111Z"/"timestamp": "$body.watch_record.status.state.timestamp"/]
// TESTRESPONSE[s/"timestamp": "2015-06-02T23:17:55.124Z"/"timestamp": "$body.watch_record.status.actions.test_index.ack.timestamp"/]
// TESTRESPONSE[s/"last_checked": "2015-06-02T23:17:55.124Z"/"last_checked": "$body.watch_record.status.last_checked"/]
// TESTRESPONSE[s/"last_met_condition": "2015-06-02T23:17:55.124Z"/"last_met_condition": "$body.watch_record.status.last_met_condition"/]
// TESTRESPONSE[s/"execution_duration": 12608/"execution_duration": "$body.watch_record.result.execution_duration"/]
// TESTRESPONSE[s/"id": "AVSHKzPa9zx62AzUzFXY"/"id": "$body.watch_record.result.actions.0.index.response.id"/]
// TESTRESPONSE[s/"node": "my_node"/"node": "$body.watch_record.node"/]
<1> The id of the watch record as it would be stored in the `.watcher-history` index.
<2> The watch record document as it would be stored in the `.watcher-history` index.
<3> The watch execution results.
<4> The user used to execute the watch.
You can set a different execution mode for every action by associating the mode
name with the action id:
[source,js]
--------------------------------------------------
POST _watcher/watch/my_watch/_execute
{
"action_modes" : {
"action1" : "force_simulate",
"action2" : "skip"
}
}
--------------------------------------------------
// CONSOLE
// TEST[setup:my_active_watch]
You can also associate a single execution mode with all the actions in the watch
using `_all` as the action id:
[source,js]
--------------------------------------------------
POST _watcher/watch/my_watch/_execute
{
"action_modes" : {
"_all" : "force_execute"
}
}
--------------------------------------------------
// CONSOLE
// TEST[setup:my_active_watch]
The following example shows how to execute a watch inline:
[source,js]
--------------------------------------------------
POST _watcher/watch/_execute
{
"watch" : {
"trigger" : { "schedule" : { "interval" : "10s" } },
"input" : {
"search" : {
"request" : {
"indices" : [ "logs" ],
"body" : {
"query" : {
"match" : { "message": "error" }
}
}
}
}
},
"condition" : {
"compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
},
"actions" : {
"log_error" : {
"logging" : {
"text" : "Found {{ctx.payload.hits.total}} errors in the logs"
}
}
}
}
}
--------------------------------------------------
// CONSOLE
All other settings for this API still apply when inlining a watch. In the
following snippet, while the inline watch defines a `compare` condition,
during the execution this condition will be ignored:
[source,js]
--------------------------------------------------
POST _watcher/watch/_execute
{
"ignore_condition" : true,
"watch" : {
"trigger" : { "schedule" : { "interval" : "10s" } },
"input" : {
"search" : {
"request" : {
"indices" : [ "logs" ],
"body" : {
"query" : {
"match" : { "message": "error" }
}
}
}
}
},
"condition" : {
"compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
},
"actions" : {
"log_error" : {
"logging" : {
"text" : "Found {{ctx.payload.hits.total}} errors in the logs"
}
}
}
}
}
--------------------------------------------------
// CONSOLE