[discrete]
[[api-java-execute-watch]]
=== Execute watch API

This API enables on-demand execution of a watch stored in the `.watches` index.
It can be used to test a watch without executing all its actions or by ignoring
its condition. The response contains a `BytesReference` that represents the
record that would be written to the `.watcher-history` index.

The following example executes a watch with the name `my-watch`

[source,java]
--------------------------------------------------
ExecuteWatchResponse executeWatchResponse = watcherClient.prepareExecuteWatch("my-watch")

    // execute the actions, ignoring the watch condition
    .setIgnoreCondition(true)

    // A map containing alternative input to use instead of the output of
    // the watch's input
    .setAlternativeInput(new HashMap<String, Object>())

    // Trigger data to use (Note that "scheduled_time" is not provided to the
    // ctx.trigger by this execution method so you may want to include it here)
    .setTriggerData(new HashMap<String, Object>())

    // Simulating the "email_admin" action while ignoring its throttle state. Use
    // "_all" to set the action execution mode to all actions
    .setActionMode("_all", ActionExecutionMode.FORCE_SIMULATE)

    // If the execution of this watch should be written to the `.watcher-history`
    // index and reflected in the persisted Watch
    .setRecordExecution(false)

    // Indicates whether the watch should execute in debug mode. In debug mode the
    // returned watch record will hold the execution vars
    .setDebug(true)

    .get();
--------------------------------------------------

Once the response is returned, you can explore it by getting execution record
source:

TIP:  The `XContentSource` class provides convenient methods to explore the
      source

[source,java]
--------------------------------------------------
XContentSource source = executeWatchResponse.getRecordSource();
String actionId = source.getValue("result.actions.0.id");
--------------------------------------------------
