WARNING: Version 5.1 of the Elastic Stack has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

› › ›

Script Condition

edit

Script Condition

edit

A watch condition that evaluates a script. The default scripting language is painless. You can use any of the scripting languages supported by Elasticsearch as long as the language supports evaluating expressions to Boolean values. Note that the mustache and expression languages are too limited to be used by this condition. For more information, see Scripting in the Elasticsearch Reference.

For Groovy, you must explicitly enable dynamic scripts in elasticsearch.yml to use inline or stored scripts. To enable groovy scripting for watches only, you can set script.engine.groovy.inline.xpack_watch: true.

Alternatively, starting with 5.0, Elasticsearch is shipped with the new Painless scripting language. Painless was created and designed specifically for use in Elasticsearch. Beyond providing an extensive feature set, its biggest trait is that it’s properly sandboxed and safe to use anywhere in the system (including in Watcher) without the need to enable dynamic scripting.

Using a Script Condition

edit

The following snippet configures an inline script condition that always returns true:

"condition" : {
  "script" : "return true"
}

This example defines a script as a simple string. This format is actually a shortcut for defining an inline script. The formal definition of a script is an object that specifies the script type and optional language and parameter values. If the lang attribute is omitted, the language defaults to painless. Elasticsearch supports three script types: Inline, File, and Stored.

For example, the following snippet shows a formal definition of an inline script that explicitly specifies the language and defines a single script parameter, result:

"condition" : {
  "script" : {
    "inline" : "return result",
    "lang" : "painless",
    "params" : {
      "result" : true
    }
  }
}

Inline Scripts

edit

Inline scripts are scripts that are defined in the condition itself. The following snippet shows the formal configuration of a simple painless script that always returns true.

"condition" : {
  "script" : {
    "inline" : "return true"
  }
}

File Scripts

edit

File scripts are scripts that are defined in files stored in the config/scripts directory. The following snippet shows how to refer to the my_script.painless file:

"condition" : {
  "script" : {
    "file" : "my_script"
  }
}

As with Inline scripts, you can also specify the script language and parameters:

"condition" : {
  "script" : {
    "file" : "my_script",
    "lang" : "javascript",
    "params" : {
      "result" : true
    }
  }
}

Stored Scripts

edit

Stored scripts refer to scripts that were stored in Elasticsearch. The following snippet shows how to refer to a script by its id:

"condition" : {
  "script" : {
    "id" : "my_script"
  }
}

As with File and Inline scripts, you can also specify the script language and parameters:

"condition" : {
  "script" : {
    "id" : "my_script",
    "lang" : "javascript",
    "params" : { "color" : "red" }
  }
}

Accessing the Watch Payload

edit

A script can access the current watch execution context, including the payload data, as well as any parameters passed in through the condition definition.

For example, the following snippet defines a watch that uses a search input and uses a script condition to check if the number of hits is above a specified threshold:

{
  "input" : {
    "search" : {
      "indices" : "log-events",
      "body" : {
        "size" : 0,
        "query" : { "match" : { "status" : "error" } }
      }
    }
  },
  "condition" : {
    "script" : {
      "inline" : "return ctx.payload.hits.total > threshold",
      "params" : {
        "threshold" : 5
      }
    }
  }
}

When you’re using a scripted condition to evaluate an Elasticsearch response, keep in mind that the fields in the response are no longer in their native data types. For example, the @timestamp in the response is a string, rather than a DateTime. To compare the response @timestamp against the ctx.execution_time, you need to parse the @timestamp string into a DateTime. For example:

org.elasticsearch.common.joda.time.DateTime.parse(@timestamp)

You can reference the following variables in the watch context:

Name	Description
`ctx.watch_id`	The id of the watch that is currently executing.
`ctx.execution_time`	The time execution of this watch started.
`ctx.trigger.triggered_time`	The time this watch was triggered.
`ctx.trigger.scheduled_time`	The time this watch was supposed to be triggered.
`ctx.metadata.*`	Any metadata associated with the watch.
`ctx.payload.*`	The payload data loaded by the watch’s input.

« Array Compare Condition Actions »