Execute Watch API

edit

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:

POST _xpack/watcher/watch/my_watch/_execute

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:

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 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 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 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:

POST _xpack/watcher/watch/my_watch/_execute
{
  "trigger_data" : { 
     "triggered_time" : "now",
     "scheduled_time" : "now"
  },
  "alternative_input" : { 
    "foo" : "bar"
  },
  "ignore_condition" : true, 
  "action_modes" : {
    "my-action" : "force_simulate" 
  },
  "record_execution" : true 
}

The triggered and schedule times are provided.

The input as defined by the watch is ignored and instead the provided input will be used as the execution payload.

The condition as defined by the watch will be ignored and will be assumed to evaluate to true.

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.

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:

{
  "_id": "my_watch_0-2015-06-02T23:17:55.124Z", 
  "watch_record": { 
    "watch_id": "my_watch",
    "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": {
      "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": { 
      "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"
        }
      ]
    }
  }
}

The id of the watch record as it would be stored in the .watcher-history index.

The watch record document as it would be stored in the .watcher-history index.

The watch execution results.

Action Execution Modes

edit

Action modes define how actions are handled during the watch execution. There are five possible modes an action can be associated with:

Name Description

simulate

The action execution will be simulated. Each action type define its own simulation operation mode. For example, The 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:

POST _xpack/watcher/watch/my_watch/_execute
{
  "action_modes" : {
    "action1" : "force_simulate",
    "action2" : "skip"
  }
}

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

POST _xpack/watcher/watch/my_watch/_execute
{
  "action_modes" : {
    "_all" : "force_execute"
  }
}

Inline Watch Execution

edit

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:

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

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:

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