Filter

Groovy filters allow you to control whether a message is processed by a specific plugin or mapper based on message content. Filters are defined as Groovy expressions that evaluate to either true or false.

Filters do not modify messages themselves. They only determine whether processing should continue at a given point in the message flow.

Filters vs Queue Topic

Plugins subscribe to messages using queue topics, which determine message routing based on:

• Source endpoint: where this message originated from.
• Destination endpoint: where is this message going to.
• Message type: message type before getting to the plugin.

The topic field in the sender plugin should always be the primary mechanism for routing messages to plugins.

Groovy filters should only be used when queues are not sufficient, for example when routing decisions depend on message content, not on source, destination, or message type.

Where Groovy Filters Can Be Used

Groovy filters can be configured in the following places:

Sender Plugins

Groovy filters can be added to sender plugins to control which messages the plugin is allowed to process.

• If the filter evaluates to true, the message is processed by the plugin.
• If the filter evaluates to false, the message is not sent to the plugin.

In this case:

• The message is published unchanged
• Other plugins subscribed to the same message type may still receive and process it
• The message is not discarded

This allows multiple sender plugins to selectively handle messages based on content.

Mappers

Groovy filters can also be applied at the mapper level to control whether a specific mapper is executed.

• If the filter evaluates to true, the mapper is applied and the message is transformed.
• If the filter evaluates to false, the mapper is skipped.

In this case:

• The plugin containing the mapper still processes the message
• The message continues through the plugin unchanged by that mapper
• Other mappers in the same plugin may still be applied

Mapper filters are useful when a transformation should only apply under specific conditions.

Filter Behavior Summary

Filter location	Filter result	Outcome
Sender plugin	false	Message is not sent to the plugin, published unchanged
Mapper	false	Mapper is skipped, plugin still processes message
Any filter	true	Processing continues normally

Filter Syntax

Groovy filters are written as Groovy expressions and must evaluate to a boolean (true or false).

Filters have access to the message and other context objects, allowing conditions based on message payload, metadata, headers, or environment.

Available Objects in Filters

The following objects are available when evaluating a Groovy filter:

Object	Description
message	The message being evaluated
parser	Utility for JSON, map, and list conversion
api	Access to the 1Gateway API
option	Helper for accessing optional bindings
log	Logging utility

Example Groovy Filters

The following examples demonstrate how Groovy filters can be used to evaluate message content when queue topics alone are not sufficient.

Filter by Priority

Process only incidents with high priority: message.priority == "high"

Exclude Messages Updated by 1Gateway

Process only incidents that were not updated by 1Gateway itself: message.updatedBy != "1Gateway"

Combine Multiple Conditions

Process only high-priority incidents that were updated by an external system: message.priority == "high" && message.updatedBy != "1Gateway"

Check for Field Presence

Process only incidents that contain an assigned user: message.assignedTo != null

Complex Filter

Groovy filters can include more advanced logic using if / else expressions when simple conditions are not sufficient.

The following example processes an incident only if:

1. The priority is high, or
2. The priority is medium and the incident belongs to a specific category

if (message.priority == "high") {
    true
} else if (message.priority == "medium" && message.category == "network") {
    true
} else {
    false
}

Best Practices

• Always prefer queue topic for routing by source, destination, and message type
• Always prefer plugin filters over mapper filters
• Use filters only when routing depends on message content
• Keep filters simple and easy to understand
• Avoid expensive computations in filters