dashboard:set-controls embed event

This event can only be processed by dashboards. Sending this event to an iframe that contains a non-dashboard Omni URL, such as an app, will have no effect on the embedded page.

Updates one or more controls on an embedded dashboard without a reload. Only controls included in the parameters are affected; any existing controls that aren’t included retain their existing values.

{
  "name": "dashboard:set-controls",
  "payload": {
    "controlUrlParameters": ["string"]
  }
}

Properties

string[]

An array of control specifications that define the control values to apply. Each entry is formatted as follows, url-encoded as it would appear in a signed embed URL:

c--<control_id>=<value>

Omni reads only the c-- entries from each string. It drops anything else, including a filter parameter, a non-string entry, or an invalid entry. If a message doesn’t have any control parameters, Omni ignores it.

Retrieve values for this parameter by using Omni in a non-embedded context. Navigate to a dashboard with controls and change the control values, which changes the URL. Use what’s in the URL as the value for this parameter.

When to send this event

Send this event after Omni emits page:ready or dashboard:ready. To apply controls each time a dashboard loads, send this event in response to dashboard:ready. If the dashboard isn’t ready when the event arrives, Omni keeps the event and applies it when the dashboard is ready:

If you send more than one event, Omni applies the events in the order that you sent them. If two events set the same control, the later event wins.
If you send a navigate event, Omni discards the controls that wait for the page the user leaves.
If you send this event after a navigate event, Omni applies the controls to the dashboard where the navigation arrives.

Example

This example sets a field switcher control and a top N control directly:

const iframe = document.querySelector("iframe#omni-dashboard")

iframe.contentWindow.postMessage(
  {
    name: "dashboard:set-controls",
    payload: {
      controlUrlParameters: [
        // field switcher / timeframe control: swap the field
        "c--8f2c1e7a=users.created_at%5Bquarter%5D",
        // top N control
        "c--3b9d4f10=10",
      ],
    },
  },
  "https://yourcompany.embed-omniapp.co"
)

Save and replay control state

This example saves the control state Omni reports for the dashboard, then replays it later:

let savedControls = null

window.addEventListener("message", (event) => {
  if (event.data?.name === "dashboard:controls") {
    savedControls = event.data.payload
  }
})

function restoreControls() {
  iframe.contentWindow.postMessage(
    {
      name: "dashboard:set-controls",
      payload: {
        controlUrlParameters: Object.values(savedControls)
          .map((control) => control.asUrlSearchParam)
          .filter((parameter) => parameter !== null),
      },
    },
    "https://yourcompany.embed-omniapp.co"
  )
}

Getting started

Setup

App customization

Events & interactivity

Admin

dashboard:set-controls embed event

Properties

When to send this event

Example

Save and replay control state

​Properties

​When to send this event

​Example

​Save and replay control state

Properties

When to send this event

Example

Save and replay control state