Skip to main content

Event Handlers

Event handlers define the automated actions that Mango performs when an event is raised. When an event detector triggers, a data source reports an error, or any other system event occurs, associated event handlers execute the configured response. Mango supports four types of event handlers, each suited to different automation needs.

How Event Handlers Work​

The event handling workflow follows a consistent pattern:

  1. An event occurs (e.g., a high limit detector activates, a data source goes offline, a user logs in).
  2. Mango checks for any event handlers associated with that event type.
  3. Each matching handler executes its configured action (send email, set a point value, run a process, or execute a script).
  4. When the event returns to normal (RTN), handlers may execute additional actions (e.g., send an "inactive" notification or reset a point value).

Event handlers are configured on the Event Handlers page, accessible from the main navigation menu. Each handler specifies:

  • A name and optional XID for identification.
  • One or more event types that trigger the handler.
  • The handler-specific configuration (recipients, target point, command, or script).

A single event can trigger multiple handlers, and a single handler can be associated with multiple event types.

Email Event Handler​

The email event handler sends email notifications when an event is raised, optionally during escalation, and when the event returns to normal. This is the most commonly used handler type. For complete email setup details, see Email Notifications.

Active Notification Recipients​

Add recipients who will receive the email when the event becomes active. Recipients can be:

  • Mailing lists: Pre-configured groups of addresses managed on the Mailing Lists page.
  • Users: Individual Mango users (uses their configured email address).
  • Email addresses: Directly entered external email addresses.

Subject Line​

Choose whether the email subject displays the handler name or the event message. The default subject format is:

{alarmLevel} - {nameOrMessage} ({notificationType}) - id:{eventId}

The subject can be further customized by modifying i18n keys (ftl.subject.fullSubjectLine) or by using a custom FreeMarker template.

Optional Email Content​

Several optional content additions can provide context in the notification:

  • Include system information: Appends a list of all Work Items currently scheduled, grouped by priority. Useful for diagnosing system problems.
  • Include point value data: For point events, includes a configurable number of recent rendered point values.
  • Include log file: Attaches a zip archive of the current Mango log file at the time of the event.

Escalation​

Escalation sends additional notifications if an event remains unresolved after a specified time period. Multiple escalation entries can be configured, each with its own delay, recipients, and behavior:

  • Send until inactive: Keep sending escalation emails until the event returns to normal.
  • Send until acknowledged: Keep sending until the event is acknowledged or returns to normal.
  • Maximum emails: Limit the total number of escalation emails, or check Send indefinitely for unlimited escalation.
  • Escalation delay: The initial delay before the first escalation email and the interval between subsequent emails.

Each escalation entry can have an optional name. When specified, the escalation name replaces the default notification type in the email subject line.

Inactive Notification​

Enable Send inactive notification to send a follow-up email when the event returns to normal. By default, the inactive notification goes to all recipients who received the active or escalation emails. You can optionally specify a separate list of inactive recipients.

Custom Templates​

Override the default email body by providing a custom FreeMarker template. The template has access to the full event model via the evt variable and can use Mango's i18n system for translated text. Default templates are located under MA_HOME/ftl/.

Set Point Event Handler​

The set point event handler writes a value to a specified data point when an event is triggered. This enables automated control responses to alarm conditions.

Configuration​

  • Target point: The data point that will receive the new value.
  • Value source: Choose one of three options:
    • Use source value: If the event was triggered by a value change, use the triggering value (data types must match).
    • Static value: Enter a specific value to write.
    • Script: Use a JavaScript or Groovy script to compute the value dynamically.

Script Context​

When using a script to compute the set value, you can add additional data points to the script context. The target point is always available under the key target. If a context point is disabled, it will not be added to the context (check with typeof(variableName) === "undefined").

Common Use Cases​

  • Emergency shutdown: When a high-temperature alarm fires, set an equipment control point to "Off".
  • Failover switching: When a primary sensor goes offline, switch to a backup data source.
  • Alarm acknowledgment: Automatically set a visual indicator point when an alarm is raised.

Process Event Handler​

The process event handler executes a local operating system command or shell script when an event occurs. This allows integration with external systems, logging infrastructure, or custom automation scripts.

warning

The process event handler is disabled by default due to security implications. Enabling it allows Remote Code Execution (RCE). If you enable this functionality, ensure Mango is not running as the root user.

Enabling the Process Handler​

Add the following to your mango.properties file:

# Enable the process event handler
event-handlers.process.enabled=true

# Enable interpolation for the process event handler command
event-handlers.process.interpolation-enabled=false

Configuration​

  • Active command: The shell command to execute when the event is raised.
  • Inactive command (optional): A separate command to execute when the event returns to normal.

Commands should be specified exactly as they would be typed at a terminal prompt. For complex logic, write a shell script file and call it from the handler.

Process Behavior​

  • If a process fails to start, a system event is raised with the failure description.
  • Processes are terminated if they run longer than 15 seconds.
  • Standard output is logged at the "information" level; error output is logged at the "error" level.

Command Interpolation​

When interpolation is enabled (requires explicit opt-in via mango.properties), event context can be injected into the command using ${variableName} syntax. For example:

logger 'Mango alarm: ${event.alarmLevel}'
danger

Enabling interpolation is especially dangerous as it may allow injection of user-crafted strings into the executed command via event messages. Only enable this if you fully understand the security implications.

Script Event Handler​

The script event handler executes callback functions in a supported scripting language when events are raised, acknowledged, or return to normal. This provides the most flexibility for custom event processing logic.

Supported Script Engines​

  • Graal.js (ECMAScript) -- Recommended
  • Groovy Scripting Engine
  • OpenJDK Nashorn (ECMAScript) -- Legacy
  • Oracle Nashorn (ECMAScript) -- Legacy

Callback Functions​

Three callback functions can be defined in the script:

FunctionRequiredTriggered When
eventRaised(event)YesThe event becomes active
eventInactive(event)YesThe event returns to normal or is deactivated
eventAcknowledged(event)NoThe event is acknowledged by a user

ECMAScript Example​

function eventRaised(event) {
    console.log('Event raised: ' + event.message);
}

function eventAcknowledged(event) {
    console.log('Event acknowledged: ' + event.id);
}

function eventInactive(event) {
    console.log('Event inactive: ' + event.id);
}

Groovy Example​

def eventRaised(event) {
    println("Event raised: ${event.message}")
}

def eventAcknowledged(event) {
    println("Event acknowledged: ${event.id}")
}

def eventInactive(event) {
    println("Event inactive: ${event.id}")
}

Script Permissions​

Script permissions control what Mango resources the script can access. Utilities that use permissions include RuntimeManager, DataSourceQuery, DataPointQuery, and JsonEmportScriptUtility. Assign appropriate roles to allow the script to read or write data points, query data sources, or perform other privileged operations.

Best Practices​

  • Use descriptive handler names: A name like "AHU-1 High Temp Email to Facilities" is far more useful than "Email Handler 1" when reviewing the event handlers list.
  • Test handlers with low-severity events: Before deploying critical alarm handlers, test the configuration with Information-level events to verify recipients, commands, and scripts work correctly.
  • Combine handler types: Use an email handler for notification and a set point handler for automated response on the same event for comprehensive alarm management.
  • Monitor escalation carefully: Unlimited escalation can generate a large volume of emails. Always set a reasonable maximum or ensure someone is responsible for acknowledging alarms.
  • Review process handler security: Regularly audit which process handlers are configured and ensure the commands they execute are safe and necessary.