Scripts migration guide
This is the migration guide for Groovy and JavaScript scripts used in the Script component.
Versions
| Dovetail | Groovy version | Javascript version (Engine) |
|---|---|---|
| < 4.14.x | 2.5 | ECMAScript 5.1 (Nashorn) |
| > 4.15.0 | 3.0 Release notes | ECMAScript 2023 (GraalVM) |
| > 4.17.0 | 4.0 Release notes | ECMAScript 2023 (GraalVM) |
Groovy
Migration
Most Groovy scripts will migrate without any changes. If a Groovy script is not working anymore; verify in the Groovy release notes if your script is affected by one of the listed changes and update your script accordingly.
JavaScript
Until version 4.14.x, Dovetail was running on Java 8. This version of Java came with a JavaScript engine bundled called Nashorn. For a while Oracle, the owner of Java, supported JavaScript with the Nashorn Engine. Since Java 11 this engine was deprecated because of maintenance challenges, as cited by Oracle.
Dovetail 4.15.0 runs on Java 11 that uses a new Javascript engine as provided by Oracle. This engine is called GraalVM. JavaScript used in Dovetail Script components needs to be tested to verify if they still work with the new engine.
Oracle says: “Both Nashorn and GraalVM JavaScript support a similar set of syntax and semantics for Java interoperability. One notable difference is that GraalVM JavaScript takes a secure by default approach, meaning some features need to be explicitly enabled that were available by default on Nashorn. The most important differences relevant for migration are listed here (Nashorn-GraalVM Migration guide)”
Changes in predefined variables
Some JavaScript variables in Nashorn are predefined like "request" and "result". In GraalVM some predefined variables have changed:
| Dovetail 4.14.x | Dovetail 4.15.0 |
|---|---|
| context | context |
| exchange | exchange |
| request | message |
| response | body |
| properties | properties |
| headers | |
| body | |
| exchangeId | |
| result | * |
* The last variable is returned by default so you don't have to define result anymore.
Migration
To upgrade it's best to follow the steps below:
- Update all the changes in predefined variables.
- Remove the "result" variable, the last variable is returned by default so result is not need anymore.
- Update your Javascript from ECMAScript 5.1 to ECMAScript 2023.
Functions affected by this change are described in the Nashorn-GraalVM Migration guide.
Test your JavaScript in Script components to verify it's working (the Migration Guide might not be complete).
Tip 1: Use a linter
Test the syntax of your script online: JS Hint.
It doesn't recognize the predefined variables.
Tip 2: Use ChatGPT
Use our custom created GPT to convert a script automatically: ChatGPT Dovetail Javascript Converter.
This (like all ChatGPT's) is not perfect, but it can save a bit of time.