OpenSearch/watcher/docs/how-watcher-works/templates.asciidoc

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