OpenSearch/docs/public/watcher/condition/script.asciidoc

[[condition-script]]
=== Script Condition

A watch <<condition, 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 {ref}/modules-scripting.html[Scripting]
in the Elasticsearch Reference.

==== Using a Script Condition

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

[source,js]
--------------------------------------------------
"condition" : {
  "script" : "return true"
}
--------------------------------------------------

This example defines a script as a simple string. This format is actually a
shortcut for defining an <<condition-script-inline, 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:
<<condition-script-inline, Inline>>, <<condition-script-file, File>>, and
<<condition-script-stored, 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`:

[source,js]
--------------------------------------------------
"condition" : {
  "script" : {
    "inline" : "return result",
    "lang" : "painless",
    "params" : {
      "result" : true
    }
  }
}
--------------------------------------------------

[[condition-script-inline]]
==== Inline Scripts

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

[source,js]
--------------------------------------------------
"condition" : {
  "script" : {
    "inline" : "return true"
  }
}
--------------------------------------------------

[[condition-script-file]]
==== File Scripts

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:

[source,js]
--------------------------------------------------
"condition" : {
  "script" : {
    "file" : "my_script"
  }
}
--------------------------------------------------

As with <<condition-script-inline, Inline>> scripts, you can also specify the
script language and parameters:

[source,js]
--------------------------------------------------
"condition" : {
  "script" : {
    "file" : "my_script",
    "lang" : "javascript",
    "params" : {
      "result" : true
    }
  }
}
--------------------------------------------------

[[condition-script-stored]]
==== Stored Scripts

Stored scripts refer to scripts that were {ref}/modules-scripting-using.html#modules-scripting-stored-scripts[stored]
in Elasticsearch. The following snippet shows how to refer to a script by its `id`:

[source,js]
--------------------------------------------------
"condition" : {
  "script" : {
    "id" : "my_script"
  }
}
--------------------------------------------------

As with <<condition-script-file, File>> and <<condition-script-inline, Inline>>
scripts, you can also specify the script language and parameters:

[source,js]
--------------------------------------------------
"condition" : {
  "script" : {
    "id" : "my_script",
    "lang" : "javascript",
    "params" : { "color" : "red" }
  }
}
--------------------------------------------------

[[accessing-watch-payload]]
==== Accessing the Watch Payload

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 <<input-search, `search` input>>
and uses a `script` condition to check if the number of hits is above a specified
threshold:

[source,js]
--------------------------------------------------
{
  "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:

[source,js]
--------------------------------------------------
org.elasticsearch.common.joda.time.DateTime.parse(@timestamp)
--------------------------------------------------

You can reference the following variables in the watch context:

[options="header"]
|======
| 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.
|======