[[api-rest-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 test the watch for
debugging purposes.

The following example executes the `my-watch` watch:

[source,js]
--------------------------------------------------
POST _watcher/watch/my-watch/_execute
--------------------------------------------------
// AUTOSENSE

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 by simply
simulating them. You can also force execution by ignoring the watch's condition and
control whether a watch record would be written to the watch history after execution.

This API supports the following fields:

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

| 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 
                                            <<api-rest-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 `.watch_history` index for the current time.
                                            In addition, the status of the watch is
                                            updated, possbily throttling subsequent executions.

| 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 _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>
}
--------------------------------------------------
// AUTOSENSE

<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",
      "trigger_event": {
         "type": "manual",
         "triggered_time": "2015-06-02T23:17:55.124Z",
         "manual": {
            "schedule": {
               "scheduled_time": "2015-06-02T23:17:55.124Z"
            }
         }
      },
      "state": "executed",
      "input": {
         "search": {
            "request": {
               "search_type": "query_then_fetch",
               "indices": [
                  "logstash*"
               ],
               "types": [],
               "body": {
                  "query": {
                     "filtered": {
                        "query": {
                           "match": {
                              "response": 404
                           }
                        },
                        "filter": {
                           "range": {
                              "@timestamp": {
                                 "from": "{{ctx.trigger.scheduled_time}}||-5m",
                                 "to": "{{ctx.trigger.triggered_time}}"
                              }
                           }
                        }
                     }
                  }
               }
            }
         }
      },
      "condition": {
         "script": "ctx.payload.hits.total > 1"
      },
      "result": { <3>
         "execution_time": "2015-06-02T23:17:55.124Z",
         "execution_duration": 12608,
         "input": {
            "type": "simple",
            "payload": {
               "foo": "bar"
            }
         },
         "condition": {
            "type": "always",
            "met": true
         },
         "actions": [
            {
               "id": "email_admin",
               "type" : "email"
               "status" : "success"
               "email": {
                  "account": "gmail",
                  "email": {
                     "id": "my-watch_0-2015-05-30T01:14:05.319Z",
                     "from": "watcher@example.com",
                     "sent_date": "2015-05-30T01:14:05.319Z",
                     "to": [
                        "admin@domain.host.com"
                     ],
                     "subject": "404 recently encountered"
                  }
               }
            }
         ]
      }
   }
}
--------------------------------------------------

<1> The id of the watch record as it would be stored in the `.watch_history` index.
<2> The watch record document as it would be stored in the `.watch_history` index.
<3> The watch execution results.

[[api-rest-execute-watch-action-mode]]
===== Action Execution Modes

Action modes define how actions will be 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 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 ill 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 or simulated.
                      Effectively forcing the action to be throttled.
|======

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

[source,js]
--------------------------------------------------
POST _watcher/watch/my-watch/_execute
{
  "action_modes" : {
    "action1" : "force_simulate",
    "action2" : "skip"
  }
}
--------------------------------------------------
// AUTOSENSE

You can also associate a single execution mode with all the watch's actions using `_all`
as the action id:

[source,js]
--------------------------------------------------
POST _watcher/watch/my-watch/_execute
{
  "action_modes" : {
    "_all" : "force_execute"
  }
}
--------------------------------------------------
// AUTOSENSE

[[api-rest-execute-inline-watch]]
===== Inline Watch Execution

You can use the Execute API to execute watches that are not yet registered in Watcher 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 demonstrates how you can test a watch defintion:

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

All other settings for this API still apply take effect when inlining a watch.
In the following snippet, while the watch is defined with a `compare` condition,
during 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" 
        }
      }
    }
  }
}
--------------------------------------------------
