Scripts and Templates

The following snippet shows the basic elements in a watch’s execution context:

{
  "ctx" : {
    "metadata" : { ... }, 
    "payload" : { ... }, 
    "watch_id" : "<id>", 
    "execution_time" : "20150220T00:00:10Z", 
    "trigger" : { 
      "triggered_time" : "20150220T00:00:10Z",
      "scheduled_time" : "20150220T00:00:00Z"
    },
    "vars" : { ... } 
}

You can use scripts to define conditions and transforms. The default scripting language is groovy.

Scripts can reference any of the values in the watch execution context or values explicitly passed through script parameters.

For example, if the context metadata contains a color field, "metadata" : {"color": "red"}, you can access its value with the variable ctx.metadata.color. If you pass in a color parameter as part of the condition or transform definition, "params" : {"color": "red"}, you access its value with the variable color.

You use templates to define dynamic content for a watch. At execution time, templates 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. Templates can also access values explicitly passed through template parameters.

Watcher supports templates in a variety of places:

You specify templates using the Mustache scripting language.

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.2._source}}.

If you pass in a parameter as part of the input or action definition, you can reference the parameter by name. For example, the following snippet defines and references the color parameter.

{
  "actions" : {
    "email_notification" : {
      "email" : {
        "subject" : {
          "inline" : "{{color}} alert",
          "params" : {
            "color" : "red"
          }
        }
      }
    }
  }
}

To define an inline template or script, you simply specify it 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 context metadata.

"actions" : {
  "email_notification" : {
     "email" : {
       "subject" : "{{ctx.metadata.color}} alert"
     }
   }
  }
}

For a script, you simply specify the inline script as the value of the script field. For example:

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

You can also explicitly specify the inline type by using a formal object definition as the field value. For example:

"actions" : {
  "email_notification" : {
    "email" : {
      "subject" : {
         "inline" : "{{ctx.metadata.color}} alert"
      }
    }
  }
}

The formal object definition for a script would be:

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

If you index your templates and scripts, you can reference them by id.

To reference an indexed script or template, you use the formal object definition and specify its id in the id field. For example, the following snippet references the email_notification_subject template.

{
  ...
  "actions" : {
    "email_notification" : {
      "email" : {
        "subject" : {
          "id" : "email_notification_subject",
          "params" : {
            "color" : "red"
          }
        }
      }
    }
  }
}

If you store templates or scripts in the $ES_HOME/config/scripts directory, you can reference them by name. Template files must be saved with the extension .mustache. Script files must be saved with the appropriate file extension, such as .groovy.

To reference a file-based index or script, you use the formal object definition and specify its name in the file field. For example, the following snippet references the script file threshold_hits.groovy.

"condition" : {
    "script" : {
      "file" : "threshold_hits",
      "params" : {
        "threshold" : 0
      }
    }
  }