Beta Feature: The Omni integration is currently in beta. Contact your Technical Account Manager for access.
Matik's Omni integration lets you pull from the dashboards you already maintain in Omni, so you don't have to rebuild metrics or queries in Matik. You can insert a screenshot of a whole dashboard or a single tile, or pull a tile's data into a table or a single text value.
You build Omni dynamic content (DC) with a live, embedded preview of the dashboard, the same way as the Tableau Embed API and Looker Visual Selector integrations. You can also let end users filter the dashboard themselves before they generate.
Connecting Omni as a Data Source
What you need from Omni
Someone with Admin access in Omni needs to provide the following:
- Embedding turned on for your Omni workspace: Embedding is off by default in Omni. Contact Omni support to have it turned on.
- An organization API key: Create one under Admin → API Keys in Omni. Use an organization API key, not a personal access token, and have an Omni Admin create it. The key carries the access of the person who created it, so Matik can only see the dashboards that person can see.
- The embed secret: The secret Omni provides for signing standard SSO embed URLs, found in your Omni embed settings.
Creating the data source in Matik
- In Matik, go to Data Sources, create a new data source, and select Omni.
- Fill in the fields:
-
Omni Instance URL: The HTTPS URL of your Omni workspace (for example,
https://your-org.omniapp.co), or your vanity domain if you have one. - Org API Key: The organization API key from Omni.
- Embed Secret: The embed secret from Omni.
-
Omni Instance URL: The HTTPS URL of your Omni workspace (for example,
- Click Test Connection. Matik checks both the API key and the embed secret.
- Click Add Data Source.
Temporary users in your Omni workspace
Each time Matik shows or renders an Omni dashboard, it creates a short-lived embed user in your Omni workspace, named Matik Embed User (temporary - managed by Matik). Matik deletes these users when it's done with them, so you can ignore them. Any attributes you set on them by hand in Omni are replaced the next time they're used.
Creating Omni Dynamic Content
- Choose Pull in data and click Continue, then select your Omni data source.
- Under Dashboard, select the Omni dashboard to pull from. Only Omni documents with a published dashboard are listed.
- Click Edit on the dashboard card to open Configure Dashboard. Pick a tile, or choose Entire Dashboard, then click Confirm. The live dashboard preview shows what you're selecting from.
- Optionally, add User Attributes and choose how End User Filters work.
- For Image DC, set the Image Resolution.
- Click Test API to preview the result, then save.
Supported DC types
| DC type | Entire dashboard | Single tile | Output |
|---|---|---|---|
| Image | Supported | Supported | PNG screenshot of the dashboard or tile. |
| Table | Not supported | Supported | The tile's data as rows and columns. |
| Text | Not supported | Supported | The first value in the tile's data. |
| Chart | Not supported | Not supported | Not available for Omni. |
Table and Text DC have a Swap rows/columns option, for when you need to reshape the data to power sub-content.
Image resolution
Images default to 1200 × 800 pixels.
- Single tile: Set the width and height. The tile is enlarged to fill the image.
- Entire dashboard: Set the width only. The height follows the dashboard, so the image includes the whole dashboard, not only what fits on screen.
User Attributes
If your Omni dashboards use user attributes to control who sees which rows, you can set those attributes from Matik. This lets one DC show each person or account only their own data. For example, set a region attribute to &:region so each generated deck shows only the region the end user picked.
- Under User Attributes, click Add Attribute.
- Select an attribute. Matik lists the custom user attributes defined in your Omni workspace.
- Enter a value: a fixed value, or a Matik input with
&:notation. For attributes that take more than one value, separate values with commas.
When an attribute uses an input, the Configure Dashboard preview lets you pick a value for that input, so you can see the dashboard as a given end user would. The value you pick here is only for the preview and isn't saved.
Note: If an attribute's input has no value at generation time, Matik leaves that attribute out and notes it in the generation log. Omni usually refuses to show restricted data without the attribute, so expect those tiles to come back empty or in error.
End User Filters
Choose how filters are set when someone generates. You can use one option or the other, not both.
| Dashboard Filters (default) | Input Filters | |
|---|---|---|
| How it works | End users set filters directly on the live Omni dashboard before they generate. | You map the dashboard's filter fields to Matik inputs or fixed values. End users fill out the inputs as usual. |
| Use it when | You want end users to have Omni's own filtering experience, with no filter setup in Matik. | You want filters driven by inputs you already use, such as input mapping, defaults, bulk generation, or Flows. |
| Available filters | Whatever filters the dashboard has. | The dashboard's filter fields, with the filter types listed below. |
Dashboard Filters
End users see one card per Omni dashboard on the generate form. DC that use the same dashboard and user attributes share a card, so end users set filters once per dashboard.
- Click the card to open the dashboard, set filters, and click Save Filters.
- The card shows the filters the end user changed from the dashboard's defaults. Any filters they don't change use the dashboard's defaults in Omni.
- If the dashboard's user attributes depend on an input, the card stays locked until that input is filled in.
Filters you change in the Configure Dashboard preview aren't saved to the DC. To change the starting filters, change the dashboard's defaults in Omni, or use Input Filters with fixed values.
Input Filters
Under Advanced Filters, add a row for each filter. Select a dashboard filter field, a filter type, and one or more values. Values can be fixed text or Matik inputs, such as &:account_name. For Within range, enter a From and To value. If you pick a date range input, Matik fills in its start and end for you.
| Field type | Filter types |
|---|---|
| Text | Equals, Not equals, Contains |
| Number | Equals, Not equals, Greater than, Less than, Within range |
| Date | Equals, Within range |
| Yes/no | Equals |
A list input applies each of its values. Rows that use an input are skipped when you click Test API, because there's no input value to apply yet.
How Omni Changes Affect Matik
Omni DC read the live dashboard, so changes to tile contents and dashboard filters in Omni flow through automatically. The following changes break a DC:
| Change in Omni | What you see in Matik | How to resolve |
|---|---|---|
| Delete the dashboard, or move it where the API key can't reach it | This dashboard can no longer be found in Omni. | Restore the dashboard, or select a different one. |
| Delete a tile, take it off the dashboard, or change its query enough that Omni gives it a new identity | This tile isn't on the dashboard. | Edit the DC and select a tile again, or use the entire dashboard. |
| Delete a user attribute used by the DC | The attribute shows as (not in Omni workspace). | Recreate the attribute in Omni, or remove it from the DC. |
Limitations
- Chart DC isn't supported. Use Image DC for a picture of an Omni chart, or Table DC to pull the data.
- Input Filters can only use the dashboard's filter fields. To filter on another field, add a filter for it to the dashboard in Omni.
- Dashboard controls aren't saved. Omni controls such as field switchers and time frame switchers render with their defaults from Omni, even if an end user changes them in the preview.
- Text DC returns the first value in the tile. You can't pick a column. Use a tile that returns the single value you want.
- Very tall dashboards are cut off. Entire-dashboard images are capped at 8000 pixels tall.
- Large bulk runs take longer. Omni allows 60 API requests per minute per API key, so Matik paces its requests. Omni support can raise this limit.
Troubleshooting
| Error message | Why it happens | How to resolve |
|---|---|---|
| Invalid Omni API key. Please check your Omni data source credentials. | Omni rejected the API key. It may have been revoked. | Create a new organization API key in Omni and update the data source. |
| Invalid Omni embed secret. Check the embed secret in your Omni standard SSO settings. | Omni rejected the embed secret. | Copy the embed secret from Omni again and update the data source. |
| Omni instance URL must use https:// | The instance URL starts with http:// or has no protocol. |
Enter the full URL, starting with https://. |
| Unable to load Omni embed. Please verify Embed is enabled on your Omni workspace. | Embedding is off for your Omni workspace. | Contact Omni support to turn on embedding. |
| Some user attributes aren't set in this preview | A user attribute uses an input that has no value in the preview. | Pick a value for the input above the preview. Generation isn't affected: it uses the end user's value. |
| This content's user attributes need an organization API key on its Omni data source. | The data source uses a personal access token. Table and Text DC with user attributes need an organization API key. | Replace the key on the data source with an organization API key. |
| Select a tile: table and text content read the rows of one tile. | The DC is Table or Text, and Entire Dashboard is selected. | Click Edit and select a tile. |
| Omni user attribute '...' was left unset (in the generation log) | An input that a user attribute depends on had no value. | Give the input a value or a default. |
| Omni did not finish loading the dashboard within 45 seconds, so no image was taken | The dashboard was too slow to load, and Matik won't take an image that might show unfiltered data. | Generate again. If it keeps happening, check that the dashboard loads in Omni, and tighten its filters. |
| Omni dashboard render is still in progress after 120s. Please try again. | Omni took too long to prepare the tile's data. | Generate again. If it keeps happening, reduce the amount of data in the tile. |
Comments
0 comments
Please sign in to leave a comment.