Skip to main content

Save and restore dashboard filters and controls in embedded apps

Users who filter or configure an embedded dashboard lose that view the moment they navigate away or close the tab. This guide walks through capturing a user’s filter and control selections with embed events, storing them outside the dashboard, and reapplying them later, so users can build a set of views they return to without redoing that work every time. It also covers what’s possible, and what isn’t, for embedded apps. This is especially relevant if:
  • You embed dashboards in your application and want users to save and switch between multiple configured views of the same dashboard
  • You want those preferences to persist across browser sessions or devices, not just within a single page load
  • You’re building save, rename, duplicate, or delete controls for saved views around an embedded dashboard or app

How persistence works

The pattern has two halves: your application listens for state events coming out of the dashboard, and your application sends that state back into the dashboard on demand. Between those two steps, you decide where saved configurations live and how they’re matched back up with what’s currently on screen. Dashboards have two kinds of state worth saving, and Omni treats them as separate systems with separate events: filters a viewer sets, and controls (field switchers, timeframe pickers, top N selectors, and similar) built into the dashboard itself.

The embed events involved

For filters, the dashboard emits dashboard:filters with the full current filter state whenever a user applies one. Your application sends dashboard:set-filters into the dashboard’s iframe to apply a saved configuration; only the filters included in that payload change, and any filters left out keep their existing values.
dashboard:set-filters and the older dashboard:filter-change-by-url-parameter are synonyms — they take the same payload and Omni handles them the same way. Use dashboard:set-filters in new code.
Controls work the same way, with their own pair of events: dashboard:controls reports every control’s current state, and dashboard:set-controls applies saved control values back onto the dashboard.
dashboard:filter-changed and dashboard:control-changed are also available if you only need to react to what just changed (for example, to log which filter or control a user just touched) rather than the full state every time.

Where configurations get stored

localStorage is the fastest way to get this working, and it’s fine for a single-user, single-device scenario. For anything a user should be able to reach from another device, or that your team needs to manage, store configurations in your own backend instead, keyed to the user and the dashboard.

Set up two-way messaging

Both directions use the browser’s postMessage API, so you need a listener for events coming from Omni and a way to post events into the dashboard’s iframe.

Wait for the right readiness event

Before sending anything into the iframe, wait for Omni to say it’s listening. page:ready fires once the embedded page can receive events at all; dashboard:ready fires every time a dashboard finishes loading, including after in-app navigation, and is the event to key off if you want to reapply a saved view each time a dashboard loads.
Omni queues dashboard:set-filters and dashboard:set-controls events sent before the dashboard is ready and applies them once it is, so sending slightly early isn’t harmful, but waiting for dashboard:ready is the documented way to avoid racing the dashboard’s own initial-filter event and avoids guessing at a load-complete signal.

Listen for filter and control changes

Add a message listener on the parent window and filter for events from your Omni embed domain:
Check event.origin against your exact embed domain (or vanity domain, if you’ve set one up) rather than a substring match, so a page on an unrelated domain that happens to contain your domain name as a substring can’t get its messages processed.

Send filters and controls back to the dashboard

Each filter in a dashboard:filters payload includes an asJsonUrlSearchParam value; each control in a dashboard:controls payload includes an asUrlSearchParam value (which can be null — skip those rather than joining them). Join the ones you want to restore and send them as dashboard:set-filters and dashboard:set-controls events:
Use your actual embed origin as the target in postMessage, not a wildcard (*). A wildcard target sends the message to whatever origin the iframe happens to be pointed at, including one an attacker redirected it to.
A child control that follows a parent control reports a null asUrlSearchParam on purpose — the parent’s own parameter reproduces it. Sending an explicit value for that child would win over the parent on replay and stop it from following later parent changes, so leaving it out (which the filter(Boolean) above already does) is correct, not an oversight.

Handle timing and normalization issues

Two dashboards with the same filters and controls applied don’t always produce identical payloads, so comparing saved state against current state takes a bit of care.

Filter out inactive and display-only fields

dashboard:filters includes every filter defined on the dashboard, not just the ones a user has actually set, and dashboard:controls likewise lists every control, including ones with no URL value. Presence in either payload doesn’t mean something is active, so check values before treating an entry as part of the user’s configuration: for list filters, check that values has at least one entry; for date ranges, check that the range bounds are non-null; for controls, check value rather than assuming the key means anything. The payload can also include display-only properties, such as appliedLabels on a filter, that vary between otherwise-identical states. Strip these before comparing two configurations or storing one.

Compare state reliably

If you want to detect whether a user’s current filters match a saved configuration, don’t compare the raw strings. Parse each filter’s JSON, remove display-only keys, sort the remaining keys, and re-serialize before comparing:

Manage saved configurations

Once capture and restore are working, the rest is standard CRUD against whatever store you chose.

Update, rename, and duplicate

Update a configuration by replacing its stored filters and controls with the current state; rename or duplicate it by copying the record and changing its name or ID. None of these operations touch the dashboard directly, they only change what you have saved.

Isolate configurations by user and dashboard

Filter and control specifications are specific to the dashboard they came from and won’t produce the intended result if applied to a different one, so key your stored configurations by dashboard ID as well as by user. If configurations are stored client-side, clear them when a user switches dashboards or accounts; if they’re stored on your backend, scope queries to the current user and organization.

Embedded apps

Apps follow a different model, and the dashboard pattern above doesn’t carry over directly. An app manages its own query filters internally through omni.query(name).setFilter() and .removeFilter() calls in the app’s own code, and Omni doesn’t currently expose an inbound embed event that lets your page set those filters from outside. What you can do from your embedding page is observe what’s happening inside the app and react to it:
app:filter-changed reports the app’s complete filter overrides after each change, keyed by query name and field, plus a changed array describing just what’s different. app:event carries whatever an app’s own code chooses to emit with omni.emit(name, payload), which is useful if the app you’re embedding was built to broadcast its own selections (a row click, a view toggle) rather than only its query filters. To actually restore a saved state inside an app, the restoration logic has to live in the app’s own code, reading from wherever the app persists its state (an Omni user attribute, a call to your backend, or omni SDK storage inside the app) and calling setFilter() itself on load. Your embedding page can supply a user attribute, a signed parameter, or data through app:event for the app to consume, but it can’t force a filter into the app the way dashboard:set-filters forces one into a dashboard.

Known limitations

Omni’s embed events don’t support clearing all filters or controls on a dashboard programmatically. Sending an empty filterUrlParameter or an empty controlUrlParameters array won’t reset the dashboard to its unfiltered, default-control state.
Work around this by giving users a saved “default” configuration with no filters or non-default controls applied, or by remounting the dashboard iframe (for example, by changing its key or re-signing its URL) to force it back to its initial state. Remounting loses the user’s scroll position, but it’s the most reliable way to get a clean slate.

Next steps

  • Read the embed events overview for the full list of events Omni can send and receive
  • Set up a vanity domain if you haven’t already, so your application and the embedded dashboard share a top-level domain
  • Reference filterSearchParam if you’d rather set a user’s initial filters at login instead of after the dashboard has loaded