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

[[watcher-api-execute-watch]]
=== Execute Watch API

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.

The following example executes the `my_watch` watch:

[source,js]
--------------------------------------------------
POST _xpack/watcher/watch/my_watch/_execute
--------------------------------------------------
// CONSOLE
// TEST[setup:my_active_watch]

For testing and debugging purposes, you also have fine-grained control on how the
watch is executed--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.

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
                                              <<condition-always, Always>> Condition. This can also be
                                              specified as a 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 <<watcher-api-execute-watch-action-mode, Action Execution Modes>>
                                              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 a HTTP parameter.

| `watch`             | no       | null     | When present, this <<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.
|======

The following example shows a comprehensive example of executing the `my-watch` watch:

[source,js]
--------------------------------------------------
POST _xpack/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
    will be used as the execution payload.
<3> The condition as defined by the watch will be ignored and will be 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 will create a watch record in the watch history,
    and the throttling state of the watch will potentially be 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,
      "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": "test2",
              "version": 1,
              "created": true,
              "result": "created",
              "id": "AVSHKzPa9zx62AzUzFXY"
            }
          },
          "status": "success",
          "type": "index"
        }
      ]
    }
  }
}
--------------------------------------------------
// 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.

[[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 will be simulated. Each action type
                      define its own simulation operation mode. For example, The
                      <<actions-email, email>> action will create the email that
                      would have been sent but will not actually send it. In this
                      mode, the action may be throttled if the current state
                      of the watch indicates it should be.

| `force_simulate`  | Similar to the the `simulate` mode, except the action will
                      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 may be throttled if the current state of the
                      watch indicates it should be.

| `force_execute`   | Similar to the `execute` mode, except the action will not
                      be throttled even if the current state of the watch
                      indicates it should be.

| `skip`            | The action will be skipped and won't be executed nor
                      simulated. Effectively forcing the action to be throttled.
|======

You can set a different execution mode for every action by associating the mode
name with the action id:

[source,js]
--------------------------------------------------
POST _xpack/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 _xpack/watcher/watch/my_watch/_execute
{
  "action_modes" : {
    "_all" : "force_execute"
  }
}
--------------------------------------------------
// CONSOLE
// TEST[setup:my_active_watch]

[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}.

The following example shows how to execute a watch inline:

[source,js]
--------------------------------------------------
POST _xpack/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 _xpack/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