See Connecting to Looker for information on connecting your Looker data source.
Pulling Data from Looker
Matik supports two ways to build Looker dynamic content (DC):
- Form method: Configure the query through Matik forms — pick a dashboard query or a model/view, choose fields, filters, sorts, and pivots. Matik calls the Looker REST API to fetch results. Supports pulling data from dashboards.
- Visual Selector method (Beta): Build the DC by interacting with an embedded Looker dashboard inside Matik. Pick a dashboard or a single tile, set filters by clicking through the dashboard, and optionally let end users filter the dashboard at generation time without setting up Matik inputs. Supports pulling data from dashboards or Looks (coming soon).
The Visual Selector method is currently in beta. Contact your Technical Account Manager for access. Until your account is enabled, only the API tab will appear on Looker DC.
Both methods use the same Looker data source connection. You choose the method on a per-DC basis using the API or Visual Selector tab at the top of the DC form.
How Looker Changes Impact Matik
Take care when making certain changes in Looker. The following changes will break connected DC in Matik:
| Looker Change | Error Message in Matik | Resolution |
|---|---|---|
| Delete dashboard used by a DC | Dashboard cannot be found | Restore the deleted dashboard; the error message will specify the dashboard ID in Looker. Otherwise, you can recreate the dashboard. |
| Delete dashboard query used by a DC | Dashboard query cannot be found | Recreate the deleted query, or select a new query. |
| (LookML dashboards only) Rename the LookML element name of a dashboard query NOTE: Display names are safe to edit | Dashboard query cannot be found | Recreate the deleted query, or select a new query. |
| Delete OR rename a field used in a DC | Field cannot be found | If the field was renamed, update its name in Looker to match what’s in Matik or remove the old field in Matik and re-add the updated field. If the field was deleted, you can recreate it. |
For Form-based Looker Dynamic Content: note that changes to the following will not cascade to Matik:
- Filters
- Sorts
- Pivots
- Limit
- Fields to return
- Query_timezone
When you first select a dashboard query during DC creation, these settings are pre-populated in the form based on the current dashboard settings, for convenience. However, once you save the DC, we will always use the settings present in Matik as the source of truth. If you change these settings on your dashboard in Looker, you will need to update the DC manually if you want it to mirror those changes.
For Visual Selector DC, this trade-off works differently: the DC is bound to the live dashboard, so filter and tile-layout changes in Looker may flow through. Field renames or deletions on the underlying tile query will still break the DC the same way as the API method.
Using the Form
Use a form to query data from Looker via Looker's REST API. Matik supports pulling Looker data from Dashboards, Model/View combinations, or Explores. Configure how you want to pull data from Matik by selecting Source = Dashboard or Source = Model.
| Dashboard > Dashboard Query | Model View | |
|---|---|---|
| How data is pulled | Pulls data from a query within a dashboard. We support both user-defined dashboards and LookML dashboards. | Build a query in Matik to pull data directly from a Model + Explore (View). (NOTE: In Matik, the selected view is effectively the Explore within the specified Model. We fetch fields from the Explore and build an inline query using the selected Model + View.) |
| Relationship to changes in Looker | Connected to dashboards in Looker, so dashboard changes may impact the DC. | Decoupled from dashboards, so dashboard changes in Looker will not affect your DC. Only changes to the actual Model + Explore (View) could potentially affect your DC. |
| Supported output formats | Data can be returned in text/tabular format OR as a screenshot of the Looker dashboard chart. | Data can only be returned in text/tabular format. No chart image screenshots. |
Note that the Looker form does not support pulling data from:
- Merged queries. If the data you are attempting to access/populate with Matik resides as part of a merged query, you will have to uncouple the query into its various components.
- Looks. Instead, make the data you want to pull available via a dashboard or model/view.
- Looker Studio
Configuring Looker Dynamic Content via the Form
Start by naming your content, giving it a description, and adding any tags as necessary. Then select Looker as the data source.
Scroll down and select whether you want to connect to a dashboard or a model and then specify which dashboard or model you want to pull data from.
If you select a dashboard, you will be prompted to select a dashboard query (this is an element on that particular dashboard). Once you select the dashboard query, Matik will automatically pre-populate the dynamic content form based on the selected query.
Use the dynamic content form to configure what data to pull from Looker.
-
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).- Tips:
- If no filters are specified, filters currently applied to your Looker dashboard will be applied.
- Dates can be filtered by using all relative date formats available in Looker. (e.g. date_time = last year)
- Tips:
- Sorting: Adds sorting criteria to choose how you want your data to be ordered.
- Pivot: Selects a field in the underlying query by which to pivot the data. Pivot will not work properly with custom fields in Looker, and the pivot field should not be modified.
- Result size: Applies a limit to the amount of data returned.
- Timezone: Chooses a timezone for the query data if needed.
-
Fields: Selects the fields from the underlying query that the user wants Matik to return.
- Tips:
- By default, all fields in the dashboard are selected.
- Rename any field by clicking on the field name and typing in a new field alias.
- Tips:
- Apply Looker Formatting: Selecting this toggle applies the current Looker field formatting to the output of data pulled by/in Matik.
Working with Looker Screenshots
If you want to directly export a screenshot of your Looker chart, you can:
- Set DC type = Image
- Enable "Output as screenshot of Looker chart"
The DC will insert a screenshot of the Looker chart that matches your query. This functionality is useful if you've already built out complex charts or formatting in Looker, and want to insert them directly into your generated content without having to rebuild them in your templates.
If desired, you can adjust the image dimensions using the optional Image Dimension settings:
-
By default, the screenshot image dimensions will be set to "Auto," meaning that we will use whatever image dimensions are returned by Looker.
-
If desired, you can configure your own desired image dimensions, setting the desired width and/or height for the image. You can also lock or unlock the image aspect ratio.
On generation, we will insert the screenshot image based on the Image Dimension settings. The aspect ratio will always be maintained. The image size may be scaled down if needed based on the template settings:
- For presentation and document templates: Matik will ensure the image fits within the space of the placeholder image, by scaling the image size down to either the placeholder width or height (whichever is larger).
- For email templates (Visual Builder): Matik scales the image to match the specified width of the email template Image module
- For email templates (Code Editor): Matik inserts the image using the specified Image dimensions, unless you specify a size override in the image tag in the HTML code.
Considerations for Form DC Setup
- If you add a Sort, you must make sure the Sort field is also included under ‘Fields to Return.’ (If you don’t want that field explicitly included in your results output, you can hide it.)
- If you add a Pivot, you must make sure the Pivot field is included under ‘Fields to Return.’ Fields used to Pivot cannot be hidden.
- Pivot will not work properly with custom fields in Looker, and the pivot field should not be modified.
- If you add a calculated field you must also include all the fields used in the calculation under ‘Fields to Return.’ (If you don’t want those fields explicitly included in your results output, you can hide them.)
Troubleshooting Looker Form DC
- If you're having trouble connecting Looker, note that you need to whitelist our IP address (54.177.196.112, 54.219.155.184, and 52.9.192.216), if you use a VPN to connect to this data source.
- If loading is very slow, try ensuring that the connected integration account only has access to dashboards required for Matik. We recommend having fewer than 50 dashboards visible to that account to prevent slow loading.
- Issues can also occur due to changes made on the Looker side. Here are some potential errors and their resolution.
| Error Message | Why it Happens | How to Resolve |
|---|---|---|
| Dashboard cannot be found | Occurs if the dashboard was deleted. | Restore the deleted dashboard; the error message will specify the dashboard ID in Looker. Otherwise, you can recreate the dashboard. |
| Dashboard query cannot be found | Occurs if the dashboard query was deleted. | Recreate the deleted query, or select a new query. |
| Field cannot be found | Occurs if the field was deleted or renamed. This can apply the fields to return and/or to fields used to filter, sort, or pivot. | If the field was renamed, update its name in Looker to match what's in Matik or remove the old field in Matik and re-add the updated field. If the field was deleted, you can recreate it. |
| Table calculation field is missing dependencies | Occurs if a calculated field is added, but its dependent fields are not. | Add the dependent fields; the Matik error message will specify the missing fields. |
Limitations & Best Practices for Looker Form DC
- The Looker integration does not support merged queries, due to API limitations. If your query is a merged query, you will not be able to select it when setting up your DC.
- If you delete a dashboard query, it will the break the connection to any DC in Matik. Even if you recreate the dashboard query again with the same name, it will not restore the DC connection.
Using the Visual Selector [Beta]
The Visual Selector for Looker is currently in beta. Contact your Technical Account Manager for access.
The Visual Selector uses Looker's Embed API to render a live, interactive dashboard inside the DC form. Instead of building a query through Matik forms, you select content by clicking on the dashboard itself. This method works well when:
- The dashboard or tiles are already set up the way you want them, and you do not want to duplicate that work in Matik.
- You want to allow end users to set Looker dashboard filters using the dashboard preview when generating.
- You want to insert a screenshot of a whole dashboard, not just a single chart.
To create a Visual Selector DC, start a new piece of dynamic content, select Looker as the data source, and switch to the Visual Selector tab at the top of the DC form.
Required Looker Configuration and Permissions for the Visual Selector
The Looker Embed API requires some additional Looker configuration, beyond the baseline required for using the REST API.
First, make sure your Looker administrator has completed all the baseline steps for setting up an integration user with the required permissions. See Connecting to Looker for the full checklist.
Then complete these additional steps to ensure the Embed API works properly with Matik.
Enable cookieless embedding
To enable this settings, in Looker, go to Looker Admin → Platform → Embed:
- Embedded content: embed_enabled must be on.
- Cookieless Embed: embed_cookieless_v2 must be on.
- Embedded Domain Allowlist: Add your Matik app domain to the allowlist (your TAM can confirm the exact domain).
Configure groups in Looker
Unlike the REST API, the Embed API relies on the groups functionality in Looker to manage access to embedded dashboard previews. Therefore, the admin must also make sure that:
- Create a group in Looker (eg. “Matik Embed Access”)
- Grant this group has at least view access to all the Shared Folders or dashboards you will want the Matik integration to access
The integration will use this group to access the desired dashboards. (You must specifically add a group. Granting access to the integration user alone is not sufficient.)
If any of these are missing, you'll see a "Looker Embed Error" when you open the Visual Selector tab. See Troubleshooting the Visual Selector for the exact message.
(Optional) Enable filtering for Looks
If you would like to pull data from Looks, and allow end users to filter directly via the embedded preview, you will need to enable filters on embedded looks.
An admin in Looker must:
- Navigate to Admin > Embed
- Set "Show filters on embedded looks" to Enabled
Configuring Visual Selector Dynamic Content
Select the Visual Selector tab. Then specify what you wish to pull from Looker:
- Select Embed Source to set the type of content you wish to pull from Looker. Currently, the Visual Selector supports pulling from Dashboards.
- Next, select the Dashboard you wish to use.
- Then click Select View to enter selection mode to specify what you wish to pull from the dashboard. You can choose:
- Select the entire Dashboard: The DC pulls a screenshot of the entire dashboard. Only valid for Image DC.
- Select a tile: The dynamic content will pull from a specific tile on the dashboard. Valid for Image, Text, or Table DC.
To change the selection later, click Select View again.
Here is a summary of how each data is pulled for each dynamic content output type:
| DC type | Whole dashboard | Single tile | Output |
|---|---|---|---|
| Image | Supported | Supported | PNG screenshot of the dashboard or tile. |
| Table | Not supported | Supported | Tabular data from the tile's underlying query. |
| Chart | Not supported | Supported | Tabular data from the tile's underlying query, which can be used to tag charts. |
| Text | Not supported | Supported | Single value from the tile's underlying query. |
Image resolution
For Image DC built with the Visual Selector, the form shows an Image Resolution section. You can set:
- Width: Width in pixels. Defaults to 800.
- Height: Height in pixels. Defaults to 600.
- Aspect ratio lock: Click the link icon to lock or unlock the aspect ratio. When locked, changing one dimension scales the other proportionally.
Unlike the Form method screenshot path, "Auto" is not available — Visual Selector always renders at the specified width and height. For slide-width images, 1600×900 typically produces sharper output than the 800×600 default. Use Test API to preview before saving.
Setting dashboard filters at the Dynamic Content level
To set filter values that apply every time the DC is generated, interact with the filter controls on the embedded dashboard inside the DC form. Matik watches the dashboard for filter changes and saves the values that differ from the dashboard's defaults.
Saved filters appear in the Dashboard Filters card below the embed view. Each filter shows as a chip with the field name and value.
Note: When the DC is bound to a single tile, dashboard filters that don't apply to that tile's underlying view are dropped at generation time. Only filters relevant to the tile's model and view are passed through.
End User Filters
You can let end users adjust the dashboard's filters at generation time, without setting up Matik inputs. To enable this, check Let end users view and set dashboard filters on the DC form.
NOTE: The setting is only enabled once you've selected a dashboard and saved the DC.
When the box is checked, end users can personalize the Looker query on generation via the following workflow.
- View Filter card on the Generate tab: One card per Looker dashboard referenced in the template appears. The card shows the dashboard name, the filters currently saved for this generation, and an Edit Filters button.
- Edit filters: Clicking the card or Edit Filters opens the embedded dashboard. End users can change filters by interacting with the dashboard the same way an admin does in the DC form. Saved values are pre-populated.
- Review: once the user has set filters, they Filter cards in the generate tab will display the currently saved filters as pills on the card.
The end user can then generate. The Visual Selector Looker dynamic content will populate using the filters that the end user set for each dashboard.
NOTE: If you've set dashboard filters at the DC level, those values are treated as default settings that end users can override if desired.
Troubleshooting the Visual Selector
| Error Message | Why it Happens | How to Resolve |
|---|---|---|
| Please enable/configure: embed_enabled, embed_cookieless_v2, domain '<your-domain>' in allowlist in Looker Admin > Platform > Embed. | One or more required Looker instance settings are off. | Have your Looker admin enable each listed setting under Admin → Platform → Embed. Add the Matik app domain to the embedded domain allowlist. |
| Token fetch failed: ... / Failed to embed dashboard: ... | Matik couldn't acquire an embed session from Looker. Usually caused by missing embed settings or a domain allowlist mismatch. | Verify the required Looker settings (see the first embed-specific row above). If they're correct, contact support with the error detail. |
| Dashboard element selection is required for table and text content types | The DC type is Table, Chart, or Text but no tile is selected. | Click Select View on the embed and click the tile you want to use. |
| Matik does not support merged queries. | The selected tile uses a Looker merged query. | Choose a different tile, or rebuild the underlying query as a single non-merged query in Looker. |
| Render task timed out after 60 seconds | Looker took too long to render the dashboard or tile. | Reduce the dashboard's data volume by tightening filters, or split the DC across smaller tiles. |
Limitations & Best Practices of the Visual Selector
- Looker query parameters are not exposed. Only dashboard filters are passed through.
- Cookieless embed is required. Older non-cookieless embed configurations are not supported.
- If you want to pull data from Looks, and allow end users to set filters by interacting directly with the embedded preview, you will your Looker admin to enable showing filters on embedded Looks.
- When the DC is bound to a single tile, dashboard filters whose underlying field belongs to a different LookML view are silently dropped at generation. Pick filters that apply to the tile's view.
- Looker Stories are not supported.
- Merged queries are not supported.
Comments
0 comments
Please sign in to leave a comment.