196 lines
6.6 KiB
Plaintext
196 lines
6.6 KiB
Plaintext
[[scripts-templates]]
|
|
=== Scripts and Templates
|
|
|
|
[float]
|
|
[[scripts]]
|
|
==== Using Scripts
|
|
|
|
[float]
|
|
[[templates]]
|
|
==== Using Templates
|
|
You can use templates to define dynamic content for a watch. At execution time, a template
|
|
can pull in data from the watch's execution context. For example, you could use a template to populate
|
|
the `subject` field for an `email` action with data stored in the watch payload.
|
|
|
|
You can use templates in a variety of places:
|
|
|
|
* The <<input-http, `http`>> input supports templates in the `path`, `params`, `headers` and `body` fields.
|
|
* The <<actions-email, `email`>> action supports templates in the `from`, `reply_to`, `priority`, `to`
|
|
`cc`, `bcc`, `subject`, `body.text` and `body.html` fields.
|
|
* The <<actions-webhook, `webhook`>> action supports templates in the `path`, `params`, `headers` and `body` fields.
|
|
|
|
You specify templates using the https://mustache.github.io[Mustache] scripting language. The
|
|
Watcher template engine uses Elasticsearch's script engine infrastructure, which supports:
|
|
|
|
* Caching - templates are compiled and cached by Elasticsearch to optimize recurring execution.
|
|
* Indexed Templates - like other scripts, you can {ref}/modules-scripting.html#_indexed_scripts[index]
|
|
your templates and refer to them by id.
|
|
* Template Files - you can store template files in `config/scripts` and refer to them by name.
|
|
{ref}/modules-scripting.html#_automatic_script_reloading[Autoloading] is also supported.
|
|
|
|
[NOTE]
|
|
===============================
|
|
While Elasticsearch supports Mustache out of the box, Watcher ships with its own version registered under `xmustache`. This is because the default Mustache implementation in Elasticsearch 1.5 lacks array/list access support. `xmustache` adds this support to enable easy array access. For example, to refer to the source of the third search hit in the
|
|
payload use `{{ctx.payload.hits.hits.2._source}}`.
|
|
|
|
When this feature is available in Elasticsearch, we expect to remove `xmustache` from Watcher and use the
|
|
version that ships with Elasticsearch.
|
|
===============================
|
|
|
|
[float]
|
|
[[accessing-template-values]]
|
|
==== Accessing the Watch Context and Template Parameters
|
|
|
|
A template can reference any of the values in the watch execution context or values explicitly passed through
|
|
template parameters.
|
|
|
|
The <<watch-execution-context, Standard Watch Execution Context Model>> is shown in the following snippet:
|
|
|
|
[source,js]
|
|
----------------------------------------------------------------------
|
|
{
|
|
"ctx" : {
|
|
"metadata" : { ... },
|
|
"payload" : { ... },
|
|
"watch_id" : "<id>",
|
|
"execution_time" : "20150220T00:00:10Z",
|
|
"trigger" {
|
|
"triggered_time" : "20150220T00:00:10Z",
|
|
"scheduled_time" : "20150220T00:00:00Z"
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------------
|
|
|
|
For example, if the context metadata contains a `color` field, you can access its
|
|
value with the expression `{{ctx.metadata.color}}`. If the context payload
|
|
contains the results of a search, you could access the source of the 3rd search hit in the
|
|
payload with the following expression `{{ctx.payload.hits.hits.3._source}}`.
|
|
|
|
You can also pass arbitrary template parameters for a field by specifying the `params` attribute.
|
|
Templates can then reference these parameters by name. For example, the following
|
|
snippet defines and references the `color` parameter.
|
|
|
|
[source,js]
|
|
----------------------------------------------------------------------
|
|
{
|
|
"actions" : {
|
|
"email_notification" : {
|
|
"email" : {
|
|
"subject" : {
|
|
"inline" : "{{color}} alert",
|
|
"params" : {
|
|
"color" : "red"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------------
|
|
|
|
[float]
|
|
[[inline-templates]]
|
|
==== Inline Templates
|
|
|
|
The default template type is `inline`, where you specify the template directly
|
|
in the value of a field. For example, the following snippet configures the subject
|
|
of the `email` action using an inline template that references the `color` value
|
|
in the metadata defined in the watch context.
|
|
|
|
[source,js]
|
|
----------------------------------------------------------------------
|
|
{
|
|
"metadata" : {
|
|
"color" : "red"
|
|
},
|
|
...
|
|
"actions" : {
|
|
"email_notification" : {
|
|
"email" : {
|
|
"subject" : "{{ctx.metadata.color}} alert"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------------
|
|
|
|
You can also explicitly indicate that the template is inlined using the formal
|
|
object definition of the template:
|
|
|
|
[source,js]
|
|
----------------------------------------------------------------------
|
|
"actions" : {
|
|
"email_notification" : {
|
|
"email" : {
|
|
"subject" : {
|
|
"inline" : "{{ctx.metadata.color}} alert"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------------
|
|
|
|
|
|
[float]
|
|
[[index-templates]]
|
|
==== Indexed Templates
|
|
|
|
If you choose to {ref}/modules-scripting.html#_indexed_scripts[index your templates],
|
|
you can reference them by id. For this, you'll need to use the formal object definition of the
|
|
template and refer to the template id using the `id` field. For example, the following
|
|
snippet references the indexed template with the id `email_notification_subject".
|
|
|
|
[source,js]
|
|
----------------------------------------------------------------------
|
|
{
|
|
...
|
|
"actions" : {
|
|
"email_notification" : {
|
|
"email" : {
|
|
"subject" : {
|
|
"id" : "email_notification_subject",
|
|
"params" : {
|
|
"color" : "red"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------------
|
|
|
|
[float]
|
|
[[file-templates]]
|
|
==== File Templates
|
|
|
|
If you store templates in files in the `config/scripts` directory, you can
|
|
reference them by name. For this, you'll need to use the formal object definition
|
|
of the template and refer to the template file by its name using the `file` field.
|
|
For example, the following snippet references the template file
|
|
`email_notification_subject.mustache`.
|
|
|
|
[source,js]
|
|
----------------------------------------------------------------------
|
|
{
|
|
...
|
|
"actions" : {
|
|
"email_notification" : {
|
|
"email" : {
|
|
"subject" : {
|
|
"file" : "email_notification_subject",
|
|
"params" : {
|
|
"color" : "red"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----------------------------------------------------------------------
|
|
|
|
NOTE: The `config/scripts` directory is scanned periodically for changes.
|
|
New and changed templates are reloaded and deleted templates are removed
|
|
from the preloaded scripts cache. For more information, see
|
|
{ref}/modules-scripting.html#_automatic_script_reloading[Automatic Script Reloading]
|
|
in the Elasticsearch Reference. |