[[transform-script]]
==== Script Transform

A <<transform, Transform>> that executes a script on the current payload in the watch execution context
and replaces it with a newly generated one. The following snippet shows how a simple script transform can be defined on the watch level:

[source,json]
.Simple Script Transform
--------------------------------------------------
{
  ...

  "transform" : {
    "script" : "return [ time : ctx.trigger.scheduled_time ]" <1>
  }
  ...
}
--------------------------------------------------

<1> A simple `groovy` script that creates a new payload with a single `time` field holding the scheduled time.

NOTE:   The executed script may either return a valid model that is the equivalent of a Java(TM) Map or a JSON object (you
        will need to consult the documentation of the specific scripting language to find out what this construct is). Any
        other value that is returned will be assigned and accessible to/via the `_value` variable.

As seen above, the `script` may hold a string value in which case it will be treated as the script itself and the default
elasticsearch script languages will be assumed (as described {ref}/modules-scripting.html#modules-scripting[here]). It
is possible to have more control over the scripting languages and also utilize pre-registered/pre-configured scripts
in elasticsearch. For this, the `script` field will be defined as an object, and the following table lists the possible
settings that can be configured:

[[transform-script-settings]]
.Script Transform Settings
[options="header"]
|======
| Name              |Required   | Default       | Description
| `inline`          | yes*      | -             | When using an inline script, this field holds the script itself.
| `file`            | yes*      | -             | When refering to a script file, this field holds the name of the file.
| `id`              | yes*      | -             | When refering to an indexed script, this field holds the id of the script.
| `lang`            | no        | `groovy`      | The script language
| `params`          | no        | -             | Additional parameters/variables that are accessible by the script
|======

* When using the object notation of the script, one (and only one) of `inline`, `file` or `id` fields must be defined

NOTE:   In addition to the provided `params`, the scripts also have access to the <<watch-execution-context, Standard Watch Execution Context Parameters>>

===== Script Type

IMPORTANT:  When suing `inline` scripts, if you're running Elasticsearch 1.3.8 or above, or 1.4.3 or above,
            you will need to explicitly {ref}/modules-scripting.html#enable-dynamic-scripting[enable dynamic scripts]
            in `elasticsearch.yml`.

As indicated by the table above, it is possible to utilize the full scripting support in elasticsearch and to base the script
on pre-registered indexed scripts or pre-defined scripts in file. Please note, for security reasons, starting from elasticsearch
`v1.4.3`, inline groovy scripts are disabled by default. Furthermore, it is considered a best practice to pre-define the script
in stored files. To read more about elasticsearch search scripting support and possible related vulnerabilities, please
see {ref}/modules-scripting.html[here].

TIP:    The `script` transform is often useful when used in combination with the <<transform-script, `search`>>
        transform, where the script can extract only the significant data from a search result, and by that, keep the payload
        minimal. This can be achieved with the <<transform-chain, `chain`>> transform.