app:filter-changed embed event

Emitted by Omni when an embedded app changes a filter on one of its queries after the app loads. An app changes filters through its own controls, which call omni.query(name).setFilter() and .removeFilter() in the app’s code. Use this to keep your own interface in sync with what someone has filtered to inside the app.

Payload

{
  "name": "app:filter-changed",
  "payload": {
    "filters": {},
    "changed": []
  }
}

Properties

object

The complete set of filter overrides after the change, as an object of query name to field name to value. A query with no overrides is absent.

array

What differs from the previous state. One entry per changed field.

Hide changed properties

string

The name of the app query whose filter changed.

string

The fully-qualified field name the filter applies to.

string

The type of change:

added - A filter was set on a field that had none
removed - An existing filter was removed
updated - An existing filter’s value changed

unknown

The previous filter value. Absent when action is added.

unknown

The new filter value. Absent when action is removed.

Example

Someone picks Returned in an app’s status control, and the app calls setFilter on its orders query:

{
  "name": "app:filter-changed",
  "payload": {
    "filters": {
      "orders": {
        "order_items.status": "Returned"
      }
    },
    "changed": [
      {
        "queryName": "orders",
        "field": "order_items.status",
        "action": "updated",
        "prev": "Complete",
        "next": "Returned"
      }
    ]
  }
}

Values are the raw filter values the app passes to setFilter — a scalar, an array, or a filter object — so treat them as opaque unless you know what the app sends. Refer to Consuming events for the full listener setup, including origin checks.

Getting started

Setup

App customization

Events & interactivity

Admin

app:filter-changed embed event

Payload

Properties

Example