Tableau REST API integration
Matik's Tableau integration offers a simple point-and-click wizard to pull in data and snapshot PNG images from your published dashboards. Start out by creating a new piece of Dynamic Content. Then select Tableau as the data source. Once you have connected Tableau as a data source, you will go through a wizard.
Scroll down and select which Tableau Workbook you want to connect to, and then specify which View (i.e. a dashboard worksheet) you want to pull data from. Please wait for the views to load if you don’t see them immediately.
Only worksheets are compatible with Matik; dashboards and Stories are not supported. Views that contain table calculations or pivots cannot be used directly with Matik. Tableau parameters are also not supported in Matik.
Note that views that aren’t published can’t be accessed by our API and won’t appear in the list options. In order to select them, publish them first in your Tableau instance.
Also note that you may need to whitelist our IP addresses (54.177.196.112, 54.219.155.184, and 52.9.192.216) if you use a VPN to connect to this data source.
Select which fields you want Matik to return, and then further customize the content with the following fields.
-
Filter Returned Fields: Any field in your selected view will be available here. By default, all returned fields will have the filters applied to them that are found in the dashboard. Adding additional filters will further filter the worksheet view selected or overwrite existing filters.
- Tip: You can rename any field by clicking on the field name and typing in a new field alias.
-
Filter: Adds filters to the data — these are the inputs that end users will have to populate in order for Matik to pull this data (i.e.
%:account_name).- Please note that only the = operator is supported at this time. See this documentation on how to filter view queries for more information on how to filter Tableau with Matik.
- Tip: Tableau dates must be formatted to YYYY-MM-DD to use the date picker input.
- Sorting: Adds sorting criteria to choose how you want your data to be ordered.
- Result size: Applies a limit to the amount of data returned.
Our Tableau integration also allows you to pull your existing data visualizations from your Tableau dashboard directly into your presentation. Once you have created your Tableau piece of dynamic content, select "Image" as the output. Then, tag an image object in your template. Make sure to sync your presentation after making changes.
Note: The images will be placed in your presentations as a PNG and cannot be edited once the presentation is generated.
Troubleshooting and Known Limitations
-
I can't find my view, dashboard, or story in the dropdown
- Unfortunately, only worksheets are compatible with Matik; dashboards and Stories are not supported.
- Ensure your worksheet is published
-
There are no fields appearing in the Filters or Fields to Return dropdown or fields are missing.
- This is a Tableau bug that can occur with certain Tableau instances. If you know the field names you can manually enter them. Reach out to your Matik TAM and they may be able to enable a workaround if you do not wish to enter the fields manually.
- Tableau's API does not support continuous date ranges. As a result using date range inputs with Tableau Dynamic Content is not supported.
- Tableau's API does not support special characters (i.e commas, ampersands) when trying to filter dynamic content.
- Ensure your integration user is used for Matik alone. Tableau enforces a limit of 40,000 API requests per hour per integration user.
- Tableau time outs can occur with large worksheets. If possible, reduce the size of your worksheet to only what you need to access for Matik. Reducing the number of columns associated with a work book can have a large impact.
-
I have created and published fields, dashboards, etc. and they are not displaying in Matik.
- Ensure the worksheet is published with the recent changes. If they still haven't appeared, this is another Tableau bug. New fields/ content will usually appear within 24 hours.
-
No workbooks or worksheets will load after selecting my Tableau Datasource.
- This is usually the result of a timeout due to too many views having to load from Tableau. This can be resolved by reducing the number of Tableau Views and worksheets that are accessible to the Tableau user used for Matik.
-
I am having trouble retrieving workbooks in the dropdown.
- If you have over 20k workbooks contact your TAM for a workaround.
-
I am not getting any values returned from Tableau when I Test API or generate a presentation.
- Ensure your filtering is set up correctly. Please note the Tableau API only supports the = operator. See above for more filtering information.
[Beta] Tableau Embed API Integration
The Tableau Embed API integration is currently in beta. Contact your Technical Account Manager if you would like to opt in to the beta.
To connect a Tableau Embed API data source, see the Connecting to BI Tools (Tableau, Looker, Microsoft Power BI) article.
Setting up Tableau Embed API Dynamic Content
The basic process for setting up Tableau Embed API Dynamic Content is:
- Select your DC type (all DC types are supported)
- Select a workbook
- Select the worksheet to pull from
- Select what you’d like to pull from this worksheet:
- A view
- An entire dashboard (Image DC only)
- Apply any needed filters:
- Use dashboard filters to save “hard-coded” filters based on the dashboard
- Alternatively use advanced filters to filter on Matik inputs
See the sections below for more detail on each of the steps.
DC Output Types
Tableau Embed API DC can be used to pull images of a dashboard/view or to output tabular data.
Output an Image of a Dashboard/View
- Select Image DC
- Select the dashboard OR view you want to screenshot
- Define any desired filters (see the sections below for more detail)
The DC will output a screenshot of your selected view or dashboard.
Image Export Methods
Matik offers two export methods:
-
By default, Matik will export the selected visual using Tableau's native 'Download' functionality.
- This corresponds to the output you would receive if you clicked 'Download' in Tableau's own UI. It will include the entire selected dashboard/view.
- A limitation of this method is that, in some cases, Tableau may output the image with an aspect ratio/dimensions that don't match what you see in the dashboard preview.
-
Optionally, you can instead choose to "Export as screenshot."
- This method is equivalent to viewing the current dashboard and taking a screenshot of the currently selected view. This method is best if you want to exactly match the aspect ratio/dimensions that you see when viewing the dashboard preview.
- A limitation of this method is that the screenshot can only include what's visible on the screen for the selected dashboard/view. It will not include content that would require scrolling to see, or legends that are placed separately from the view.
In most cases, we recommend trying the default setting first, and then enabling "Export as screenshot" if your selected visual does not output nicely using the default setting.
Output Tabular Data
- Select any non-Image DC type
- Select an individual view or worksheet (you cannot select an entire dashboard in this case)
- Define any desired filters (see the sections below for more detail)
The DC will output the tabular data that powers your selected view or worksheet.
Working with Filters
There’s 2 ways to filter Tableau Embed API DC: dashboard filters and advanced filters. See below for more details on each type.
If a dashboard filter and an advanced filter would conflict with each other, the advanced filter will always take precedence. For example, say you set a dashboard filter to "Region = North," but then you also set an advanced filter to "Region = &input." The Region = &:input filter is what would ultimately be applied on generation.
Dashboard Filters
Dashboard filters are set by interacting with the embed preview. You can see the data update live within the preview as you set the filters.
Dashboard filters that you have saved are displayed in the “Dashboard Filters” section of the DC form. The filters listed here are what will be applied on generation. You can clear them by clicking the “x.”
Use dashboard filters if you want to use the filters available within the Tableau dashboard itself.
Advanced Filters
Advanced filters are defined by selecting a field in the dashboard and then entering a value to compare that field against. The value you enter can be plain text, or you can reference a Matik input with &: notation.
Advanced filters support:
- Categorical Filters: filtering on discrete values (a list of specific values) or categories (e.g., regions, product names, categories). For example: Filtering a “Region” field to show only "Americas" and "Europe", or filtering a "Product Category" field to show only "Technology" and "Furniture".
- Range Filters: filtering data within a specified range of values, typically for continuous fields like numbers, dates, or measures. For example: filtering sales data to show only transactions between $1,000 and $10,000, or filtering dates between January 1, 2020 and December 31, 2022.
- RelativeDateFilter: allows for filtering dates relative to an anchor point or current date. For example: Filtering to show "Last 30 days", "This quarter", "Previous year", or "Next 2 weeks". These filters automatically adjust as time progresses.
When using advanced filters, take care to select a field that is connected to filters for the selected view/dashboard in Tableau. Otherwise, "filtering" on the field will not actually have any effect on the data that's returned.
For example, take this example Tableau view:
In this example:
- ✅ The Date field is connected to a filter for this view. You can verify this by confirming that it appears in the Filters section in Tableau.
- ❌ The MONTH(Date) field is not connected to a filter for this view. You can tell because it is not listed under Filters.
Filtering on Date would restrict the results that are output, whereas filtering on MONTH(Date) would not.
Tableau Embed API FAQ
Is there a glossary of Tableau terms?
In Tableau’s terminology:
- A workbook is a container for related visualizations and data connections.
- A view (or worksheet) is an individual visualization within a workbook.
- A dashboard is a container that can display multiple views/worksheets together.
A field describes an individual data column in a Tableau view.
When you pull non-image data from a view, what data should I expect to see returned?
When you select a view, Matik will return the Summary data associated with that view in Tableau. This should match what you see when you go to that view in Tableau, select View Data, and then Summary. Here is Tableau documentation on viewing underlying data for a view/worksheet: https://help.tableau.com/current/pro/desktop/en-us/inspectdata_viewdata.htm#:~:text=The-,Summary,-tab%20displays%20the
How can I return non-image view data in a different format?
You might need your Tableau data formatted in a particular way (for example: to fit in a table, to populate a given chart, etc.)
If you cannot or would prefer not to edit the Tableau worksheet, you can transform the data in a spreadsheet. See Using Google Sheets with Matik with Matik for more detail.
If you have edit permissions in Tableau: depending on your use case and the nature of your data, you may be able to adjust the worksheet itself.
- USING AGGREGATE FUNCTIONS: Use aggregate functions (like SUM, COUNTD, etc.) to aggregate and shape the data in Tableau.
- Ensure the worksheet outputs one row per bucket (e.g., Month or Platform) by using aggregate functions like
SUM/COUNTD/etc., level-of-detail expressions, or table calculations. - If the worksheet outputs multiple rows at the same grain, Matik will not sum
them, so if you go this route, you must ensure the worksheet produces exactly
one row per bucket.
- Ensure the worksheet outputs one row per bucket (e.g., Month or Platform) by using aggregate functions like
- USING CALCULATED MEASURES: When a worksheet includes both "Measure Names" and "Measure Values," we widen Tableau’s “Measure Names”/“Measure Values” pattern into separate columns. (This is the only reshaping that we perform. Matik does not aggregate or pivot categorical dimensions).
- You could use calculated measures that align with Matik's widening.
- Create one calculated measure per segment and place them on Measure Values. For example:
- Users (web):
SUM(IIF([LOGIN_PLATFORM]='web', [Active Users], 0)) - Users (mobile):
SUM(IIF([LOGIN_PLATFORM]='mobile', [Active Users], 0)) - Users (multiple):
SUM(IIF([LOGIN_PLATFORM]='multiple', [Active Users], 0))
- Users (web):
My workbook uses Tableau extensions. Does Matik support this?
Tableau extensions might not be compatible with the Embed API integration. If you experience issues, try disabling the extensions to see if that resolves the problem.
Comments
0 comments
Please sign in to leave a comment.