Event and Notification Filtering

Bitcaster provides a powerful filtering engine that allows you to control exactly when a notification should be sent based on the data received during an event trigger.

Filtering is defined using JMESPath syntax, which can be applied directly as a string or wrapped in structured YAML blocks for complex logic.

---

Simple Filtering (JMESPath)

The most common way to filter is by providing a JMESPath expression in the Payload Filter field of a Notification.

Basic Examples

Goal	Filter Expression
Match a string	country == 'italy'
Match a number	office == 22
Check nested data	server.status == 'down'
Check if field exists	attribute_not_null(urgent)

Note on Numbers: In JMESPath, literal numbers must be enclosed in backticks (e.g., `22`) to be treated as integers rather than strings.

---

Complex Logic (Structured YAML)

When you need to combine multiple conditions, you can use a structured YAML syntax. Bitcaster supports AND, OR, and NOT operators.

AND Operator

All conditions must be true.

AND:
  - country == 'italy'
  - area == 'europe'

OR Operator

At least one condition must be true.

OR:
  - country == 'italy'
  - office == 22

Nested Logic

You can nest these operators to create highly specific rules.

Goal: Notify if (Country is Italy AND Region is Lazio) OR if the Office ID is 22.

OR:
  - AND:
      - area == 'europe'
      - country == 'italy'
  - office == 22

---

How it works with the API

When you trigger an event via the API, the filtering engine evaluates your rules against the context object provided in the request.

Example Request

{
    "context": {
        "area": "europe",
        "country": "italy",
        "office": 10,
        "message": "High temperature alert"
    }
}

If a notification has the filter country == 'italy' && area == 'europe', it will be processed because both conditions match the context.

---

Testing your Filters

It is recommended to test your JMESPath expressions using the JMESPath Tutorial ⧉ or online testers before deploying them to production.

Common pitfalls to watch out for: * Case Sensitivity: 'italy' is different from 'Italy'. * Quotes: Use single quotes ' for strings. * Backticks: Use backticks ` for numbers, booleans (true/false), and nulls.