Setting up the infrastructure
Omni is where the permissions are defined and content is managed and created; however, the application where the content is embedded should dynamically map the user to the right underlying data by generating a script. Make sure your data security is set up correctly in Omni before you start.
Understanding the embed url
Omni embed URLs are composed of a few parts. These parts are concatenated into a single string and signed with a unique secret key used only by your organization. The signature is then added to a url with all the parts specified as query parameters in the URL.
When an Omni server receives the request in the URL, we will attempt to generate the same signature. If the passed in signature matches the signature generated in our servers, the request is honored.
Generating a secret
Generate a secret by going to the Admin > Embed section of your Omni instance.
Press the “Reset Secret” button to generate your random secret key. Resetting an existing secret key will invalidate the previous one, so be sure to update any scripts with the latest secret.
URL Builder Parameters
| Parameter Name | Required Status | Description | Example Input(s) |
|---|---|---|---|
| Content Path (Dashboards) | Required | Path pointing to the dashboard you wish to build a URL to embed. | /dashboards/_t58Abc |
| Content Path (Workbooks) | Required | Path pointing to the workbook you wish to build a URL to embed. Note that if you are embedding a workbook tied to a dashboard, you can use the dashboard ID from the URL and simply replace the dashboard part of the URL with a /w/ and append the ID. | /w/bd21da1b |
| External ID | Required | Required parameter creating a unique ID. This can be any alphanumeric value. | sugar, &spice123 or 123+EveryThingNice |
| Name | Required | Required parameter and can contain a non-unique name for the embed user's name property. | Bubbles Power, Buttercup Puff or Blossom Girls |
| User Attributes | Optional | Reference which user attributes you want applied to this particular embed user. | {"country":"Townsville", "associated_ids":[9,10,11]} |
| Filter Search Param | Optional | Specify which filters to apply for this embedded content. | f--order_items.status=closed |
| Link Access | Optional | Allows you to customize which other Omni dashboards can be linked to from the embedded dashboard. | Input __omni_link_access_open for all links on the embedded dashboard to be permissed and shown; input a list of dashboard IDs: abcd1234,efgh5678,ijkl9999 to only permit those specific dashboard IDs to be shown; leave the parameter blank for all links to other Omni dashboards links to be restricted; Note that links to anything other than an Omni Dashboard will be shown and permissed regardless of the values specified in the linkAccess parameter. |
| Custom Theme | Optional | Allows you to stylize your embedded dashboard to your preferred colors. | Custom theme example |
Generate embed urls
There are three ways to generate embed urls in Omni: leveraging an SDK, an API, or hard coding the url.
Leveraging an SDK (Recommended)
Generating a signed URL is complex and error prone. It is highly recommended you use an example script to generate embed URLs.
Omni has a supported Typescript SDK and some unsupported examples in other languages. Overtime the supported libraries will expand:
Supported:
Unsupported:
Leveraging the API
For POST operations, parameters are passed as a JSON object in the request body.
Generate a signed URL
POST /embed/sso/generate-url
Returns a signed URL for an embedded piece of content.
- The endpoint does not expect a signature param
- The endpoint requires a secret param (the one in your admin > embed panel)
- The nonce param is optional. If not included, we'll generate one for you
Example POST body:
{
contentPath: '/dashboards/12345678',
externalId: '12345678',
name: 'foo',
secret: '12345678901234567890123456789012',
userAttributes: '%7B%22shop_id%22%3A%22123%22%7D',
}
Parameters
contentPath(string) - The URL location of the dashboard within your Omni environment.externalID(number) - An external id to reference the external user. This should be unique for your external definition of user.name(string) - Human readable name for the usersecret(string) - Generated within Omni in your Admin Panel (Admin > Embed)userAttributes(string) - JSON serialized, key-value pairs matching defined user attributes in your system.
Manually Generate a Signature and URL (Hard Mode)
The following pieces of data are used to generate a signature:
| Property | URL Parameter | Description | Required |
|---|---|---|---|
| URL | n/a | The URL to your Omni instances embed login route. | yes |
| Content Path | contentPath | The path to the content you wish to embed. | yes |
| External ID | externalId | An external id to reference the external user. This should be unique for your external definition of user. | yes |
| Name | name | Human readable name for the user | yes |
| Nonce | nonce | 32 character (byte) unique string | yes |
| Custom Theme | customTheme | JSON serialized, key-value pairs that describe a custom theme. | no |
| Entity | entity | An id to reference the entity the user belongs to. Commonly is the customer name or other identifying organization for this user. | no |
| Filter Search Param | filterSearchParam | Encoded string representing dashboard filter values. This can be derived by copying the substring after the "?" from a dashboard URL with non-empty filter values. | no |
| Link Access | linkAccess | A string that allows you to customize which other Omni dashboards can be linked to from the embedded dashboard. If set to "__omni_link_access_open", all links on the embedded dashboard are permissed and shown.Alternatively, a comma-separated list of dashboard IDs can be passed (i.e. "abcd1234,efgh5678,ijkl9999") to only permiss to specific dashboard IDs. Finally, if the parameter is undefined, all links to other Omni dashboards are restricted. Note that link URLs to anything other than an Omni Dashboard will be shown and permissed regardless of the linkAccess parameter. | no |
| Prefers Dark | prefersDark | Dark mode setting. Can be "true", "false" or "system" | no |
| Theme | theme | Visual theming options. One of "dawn", "vibes", "breeze" or "blank". | no |
| User attributes | userAttributes | JSON serialized, key-value pairs matching defined user attributes in your system. | no |
To generate the signature, the follow steps must be followed exactly:
- Concatenate the properties, delimited by a newline character in the exact order enumerated below. Note they are in alphabetical order, with the exception of the leading login URL:
- login URL
- content path
- external id
- name
- nonce
Next concatenate the optional properties, again in alphabetical order. Any undefined optional properties must be omitted (no space, no extra newline, etc):
- custom theme
- entity
- filter search param
- Must be manually URI encoded unless pulled from Omni dashboard URL (in which case the string is already URI encoded).
- link access
- prefers dark
- theme
- user attributes
- Must be JSON stringified
There must be no leading or trailing spaces, and only a single newline between each part of the signature. Example:
https://example.embed-omniapp.co/embed/login
/embed/dashboards/123abc
luke@example.com
Luke Skywalker
hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4
{"dashboard-background":"#00FF00","dashboard-tile-title-font-size":"1.5rem"}
Acme Corp
f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"USA"%5D%2C"is_negative"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%7D&f--inventory_items.cost=%7B"kind"%3A"GREATER_THAN"%2C"type"%3A"number"%2C"values"%3A%5B"20"%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D
true
__omni_link_access_open
vibes
{"planet": "tatooine"}
- Sign the string using your secret key (available in your admin portal) with an HMAC sha256 digest algorithm, encoded as a base64url string. See https://datatracker.ietf.org/doc/html/rfc4648#page-7 for more information about base64url. Node.js example:
const hmac = crypto.createHmac("sha256", secret);
hmac.update(data);
return hmac.digest("base64url");
Crafting the URL
To generate the signed url, take the parts from above, URL encode them as part of a URL query string and attach the generated signature.
The URL form usually:
https://<your org name>.embed-omniapp.co/embed/login
Search params are then url encoded and appended. Order of params is irrelevant when generating the login url.
?contentPath=%2Fembed%2Fdashboards%2F123abc
&externalId=luke%40example.com
&name=Luke%20Skywalker
&nonce=hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4
&entity=Acme+Corp
&theme=vibes
&userAttributes=%7B%22planet%22%3A%22tatooine%22%7D
&filterSearchParam=f--order_items.status%3D%257B%22kind%22%253A%22EQUALS%22%252C%22type%22%253A%22string%22%252C%22topic%22%253A%22order_items%22%252C%22values%22%253A%255B%22Returned%22%255D%252C%22base_view%22%253A%22order_items%22%252C%22is_negative%22%253Afalse%257D
&linkAccess=__omni_link_access_open
&prefersDark=true
&customTheme=%7B%22dashboard-background%22%3A%22%2300FF00%22%2C%22dashboard-tile-title-font-size%22%3A%221.5rem%22%7D
&signature=rpf-YbMMTd2XzO_HRyP1E_RiYpQYqBkU-X9iUMplEz4
Note: newlines are not required, they were added to enhance readability.
All together this should look like:
https://example.embed-omniapp.co/embed/login
?contentPath=%2Fembed%2Fdashboards%2F123abc
&externalId=luke%40example.com
&name=Luke%20Skywalker
&nonce=hN38NgtnV2B3PMILhKQOpwLyJRP4qVv4
&entity=Acme+Corp
&theme=vibes
&userAttributes=%7B%22planet%22%3A%22tatooine%22%7D
&filterSearchParam=f--order_items.status%3D%257B%22kind%22%253A%22EQUALS%22%252C%22type%22%253A%22string%22%252C%22topic%22%253A%22order_items%22%252C%22values%22%253A%255B%22Returned%22%255D%252C%22base_view%22%253A%22order_items%22%252C%22is_negative%22%253Afalse%257D
&linkAccess=__omni_link_access_open
&prefersDark=true
&customTheme=%7B%22dashboard-background%22%3A%22%2300FF00%22%2C%22dashboard-tile-title-font-size%22%3A%221.5rem%22%7D
&signature=rpf-YbMMTd2XzO_HRyP1E_RiYpQYqBkU-X9iUMplEz4
Note: newlines are not required, they were added to enhance readability.
Map of Property Names to URL names
| Property | URL variant |
|---|---|
| Content Path | contentPath |
| External Id | externalId |
| Name | name |
| Nonce | nonce |
| Prefers Dark | prefersDark |
| Theme | theme |
| Signature | signature |
Embed URL Builder
To test and make sure the format etc of parameters you're passing through as you expect you can use the url builder (intended for internal embedding predominantly).
- First, you'll need your content's unique ID.
- Dashboards: the dashboard content ID can be found in the browser URL or by following the share steps above.
- Workbooks: the workbook content ID is the same as the dashboard ID if the workbook is tied to a dashboard. If the the workbook is only saved as a workbook then the workbook ID can only be found through the share steps above, How to generate an embed URL. Note that embedding a workbook creates a copy of said workbook for that embed user so their changes are not reflected back into the application's production version of that workbook.
- Navigate to the Embed URL builder, Admin > Embed > URL Builder tab.
- Input the required fields (denoted with a red asterisk):
- Content Path
- for dashboards, it is
/dashboards/ID_value - for workbooks, it is
/w/ID_value
- for dashboards, it is
- External ID
- this can be any alphanumeric value
- Name
- this can be any alphanumeric value
- Content Path
- Generate your URL and embed!