> For the complete documentation index, see [llms.txt](https://docs.dataloy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dataloy.com/release-8.34/voyage-management-system/step-by-step-guides/alerts/alert-scripts.md).

# Alert Scripts

### Configuring Alert Scripts

Alert scripts allow you to implement custom business logic and complex conditional checks that go beyond standard webhook expression filters. This guide covers how to define and script an automated alert.

***

#### 1. Script Information

Start by defining the identity and purpose of the alert:

* Name: Provide a clear, recognizable name for the alert (e.g., "PNL Change by 20,000").
* Code: A unique short-hand identifier for the script (e.g., "PNL").
* Description: Briefly explain the logic or the specific scenario this script monitors (e.g., "A voyage PNL (result) has changed by more than 20,000").

***

#### 2. Defining the Trigger

Specify which system events should initiate the execution of your script:

* Object Type: Select the data entity to monitor (e.g., Voyage).
* Event Type: Choose the action that triggers the script (e.g., Update).

Multiple triggers can be added to a single script by clicking the + icon in the Alert Script Trigger section. If the alert is scheduled, the triggers still apply: the script runs on the schedule and whenever a trigger fires.

***

#### 3. Writing the Script Body

The Script Body is where the custom logic resides. Scripts must be written in the [Groovy language](https://groovy-lang.org/documentation.html).

* Object Comparison: The script can access both the current state of the object (`dlpObject`) and the previous state (`oldDlpObject`) to compare changes.

  {% hint style="warning" %} A script that contains the text `oldDlpObject` anywhere, including in a comment, cannot be scheduled. Use separate scripts for alerts that compare changes and alerts that run on a schedule. {% endhint %}
* Scheduled runs: There is no triggering object, so `dlpObject` and `oldDlpObject` are not available. Query the data the alert should check instead, see [Script Body Guide](https://api.dataloy.com/user-guides/enterprise-functionality/alert-scripts/script-body-guide-groovy-java).
* Return Values: Always return a boolean (`true` or `false`). Ensure the script returns `false` if the conditions for an alert are not met to prevent unnecessary notifications.

{% hint style="warning" %}
A script that contains the text `oldDlpObject` anywhere, including in a comment, cannot be scheduled. Use separate scripts for alerts that compare changes and alerts that run on a schedule.
{% endhint %}

See [Script Body Guide](https://api.dataloy.com/user-guides/enterprise-functionality/alert-scripts/script-body-guide-groovy-java) for more in-depth information.

See full script examples in the [Alert Scripts API documentation](https://api.dataloy.com/user-guides/enterprise-functionality/alert-scripts).

***

#### 4. Message Configuration

Once the script logic determines an alert should be sent, configure the output:

* Message Subject: Define the subject line for the resulting notification (e.g., \[VMS] Voyage PNL Alert).
* Message Type: Select the format of the output (e.g., String, XML, JSON).
* Build message in script: Check this box if the actual content of the alert notification is generated dynamically within the logic written in the Script Body.
  * If unchecked, you can provide an "Alert Script Message" string.
  * Scheduled alerts have no default message, so always provide one of these.

***

#### Tips for Success

{% hint style="success" %}
Include type checks (e.g., `if (dlpObject instanceof Voyage)`) at the beginning of event-based scripts to prevent execution errors when data is missing. 
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dataloy.com/release-8.34/voyage-management-system/step-by-step-guides/alerts/alert-scripts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.