Skip to main content
When setting up Curator’s connection to Tableau, or dealing with unexpected networking or feature related issues, it’s beneficial to understand how to get details on the issues you’re facing to help narrow down root-causes. Whether you’re managing a Curator site need to understand how to enable Debug Mode to view the data returned from Tableau, or you’re a developer or system administrator working with Tableau Server and need to understand how to use Postman to make API calls to ensure your Curator and Tableau Server can communicate with one another, you’ll find all you need below.

​
Backend User Permissions

After a Tableau connection is saved, the Tableau section may not appear in the backend navigation for some users. This is a permissions issue — the connection is valid, but the backend user has not been granted access to the Tableau plugin. Curator automatically grants backend permissions to the user who saves the connection. Other backend users must be granted access manually:
  1. Log in as a super-administrator.
  2. Navigate to Settings > Administrators.
  3. Open the affected user’s record and click the Permissions tab.
  4. Under the Tableau section, enable the required permissions (Manage Tableau Settings, Manage Tableau Dashboards, etc.).
  5. Save the user record.

​
Dashboards Marked Not Found After a Connection Outage

Curator’s daily Dashboard ID sync asks Tableau to resolve each Dashboard, and flags any Dashboard it cannot resolve with a Not Found on Tableau callout in Backend > Tableau > Dashboards. When a connection’s credentials break (an expired Personal Access Token, a changed password) or the Tableau Server is unreachable at the moment the sync runs, every Dashboard on that connection can be flagged this way even though the content is still published and perfectly healthy. Curator clears these flags for you once the connection is working again, so no manual re-sync is needed in this case. Recovery happens through either of the following:
  • Saving the connection. Navigate to Backend > Integration > Connections, open the affected connection, correct the credentials and save. Curator validates the connection before it saves, so a successful save proves the credentials work, and Curator immediately queues a Dashboard ID refresh for every Not Found Dashboard on that connection.
  • The automatic connection check. Curator re-checks the primary Tableau connection every five minutes, and re-checks any other connection the next time it successfully authenticates against it. When a connection that was flagged as down starts responding again, for example because the server came back online on its own, the same Dashboard ID refresh is queued without anyone touching the backend.
The refresh runs through Curator’s queue as Tableau Dashboard: TableauID Update processes, so allow a few minutes for the queue to work through them before the Not Found callouts disappear. Dashboards published under a connection’s Custom Domain, including the per-site Custom Domains configured for Tableau Cloud secondary sites, are covered alongside those on the connection’s primary URL. A connection coming back after a longer outage also catches up on the metadata the outage interrupted. Curator queues a Tableau Dashboard: Metadata Update process for every Dashboard on that connection, not only the ones marked Not Found, so filter and parameter details that failed to refresh while Tableau was unreachable are brought up to date without waiting for the next daily sync. Two limits keep this from adding load to a Tableau Server that is still recovering:
  • It only happens when the connection was down for at least ten minutes. After a shorter interruption, such as a single slow sign-in that fails one five-minute connection check, very little failed in the meantime and the next daily sync covers it.
  • It happens at most once every three hours per connection, so a connection that goes up and down repeatedly during a bad stretch catches up once rather than after every recovery. An outage that itself lasted three hours or more always catches up when it ends.
The Dashboard ID refresh for Not Found Dashboards described above is not limited this way and runs on every recovery. Each Dashboard it fixes queues its own metadata update. Thumbnails are deliberately left for the next scheduled thumbnail refresh: rendering an image for every Dashboard on the connection at once is the most expensive sync work Curator does, and stale thumbnails are cosmetic in the meantime. If you would rather trigger the sync yourself, the Tableau API exposes /Tableau/syncTableauDashboardIds with a not_found_only parameter that limits the sync to Dashboards currently marked as Not Found.

​
Content Hidden While a Connection Is Down

When Curator cannot sign in to an enabled Tableau connection (the Tableau Server is unreachable, or the password or Personal Access Token stopped working), it cannot confirm what each user is allowed to see. Rather than show everything, Curator hides that connection’s content until it can check again:
  • Menu items, tiles, and search results for the connection’s Dashboards, workbooks, and Tableau Metrics disappear for end users.
  • Opening one of those Dashboards or Tableau Metrics by URL shows the Tableau 503 page, which tells the user the content is temporarily unavailable.
  • A page that embeds one of those Dashboards or Tableau Metrics also goes to the Tableau 503 page. If Disable Page Element Security Checks is turned on in Portal Settings, the page loads instead and the element shows a message saying the Dashboard is temporarily unavailable.
Some settings still show content during an outage, just as they do when the connection is healthy: pass-through authentication, content whose URL is listed in the Authentication Settings Whitelist, and, for Dashboards, Skip checking all Dashboard permissions (everywhere) or Skip checking menu item’s Dashboard permissions (menus only). The content comes back on its own. Curator re-checks at most every five minutes, and as soon as the connection responds again (through the automatic connection check described above, or by saving the connection with working credentials) the hidden content is restored right away. A disabled connection behaves differently: its content stays hidden until the connection is enabled again. See Temporarily Disabling Connections.

​
Renewing a Personal Access Token Before It Expires

The simplest way to avoid the outage described above is to replace a connection’s Personal Access Token before it expires rather than after. Curator reads each connection’s PAT expiration date from Tableau’s sign-in response and shows it in the read-only Personal Access Token Expiration field on the connection. Starting 31 days before that date, Curator raises a warning naming the connection and counting down the days until the token expires. The warning stays up on the day the token expires and after it has expired, until the connection is saved with a new token. The warning is a high-priority notification, so it appears in:
  • The Notification System widget on the backend Dashboard.
  • Settings > Curator > Status.
  • The Curator Digest email, listed under Serious Issues. To receive it without having to check the backend, turn on Send Curator Digests and subscribe the administrators who manage your Tableau connections, as described in System Notifications. Choose the daily schedule, or turn on immediate notifications, if a weekly or monthly digest would leave too little time to act.
The warning only covers the connection’s own Personal Access Token. Tokens entered under Secondary Sites are not checked, so track their expiration dates separately. When the warning appears, create a new Personal Access Token in Tableau and follow the Rotation Checklist below to put it in place.

​
Sync Jobs Skipped for Disabled or Non-REST Connections

Curator’s daily metadata and thumbnail syncs only queue work for Dashboards whose Tableau connection can actually serve it: the connection must be enabled and have the REST API configured, meaning a Personal Access Token or a username and password. Dashboards on a connection that has been disabled, deleted, or saved without REST credentials are skipped rather than queued, because every one of those jobs would fail. Before this behavior was introduced, a disabled connection left a failed Tableau Dashboard: Metadata Update and Tableau Dashboard: Thumbnail Update entry per Dashboard in Backend > Settings > Queued Processes every day, along with a matching error in the logs. This is a check against the connection’s configuration only, not against whether Tableau is reachable at that moment. A connection that is enabled and configured but briefly unreachable still has its jobs queued; those jobs fail cheaply, the next day’s sync picks the Dashboards up again, and after an outage of ten minutes or more the recovery described above catches up on metadata as soon as the connection responds. The skip is silent by design, so an administrator who disables a connection during a migration or decommission does not see a wall of failed processes. To confirm what was skipped, turn on Cron Debug Mode and, after the next daily sync, look in the Event Log for entries of the form CRON DEBUG MODE: Metadata refresh: skipped 12 dashboards on an unavailable Tableau connection and CRON DEBUG MODE: Thumbnail refresh: skipped 12 dashboards on an unavailable Tableau connection. Re-enabling the connection, or adding REST credentials to it, brings its Dashboards back into the next daily sync automatically.

​
Tableau API Debugging

Sometimes there are issues that are hard to diagnose without seeing exactly which API calls Curator is making to Tableau and what responses Curator is getting back from Tableau. To log all of those API calls, Curator provides a Debug Mode for Tableau Server.

​
Side Effects

A word of warning though, when this debug mode is enabled, the amount of logging that takes place is drastically increased and may fill up your server if left on for long periods. Be sure to turn it back off once you’ve logged enough to diagnose the issue. For more information about Curator’s logging systems, see the Logging Overview.

​
How to Enable Debug Mode

To turn on Curator’s Debug Mode for Tableau Server:
  1. Navigate to Backend > Settings > Tableau > Tableau Server Settings > Advanced tab.
  2. Toggle on the switch labeled Debug Mode for Tableau Server.
  3. Save the settings by using the button in the upper right.

​
Using Debug Mode to Troubleshoot

Once Curator’s Debug Mode for Tableau Server is enabled, you’ll want to recreate the scenario that led to the troublesome behavior and then view the debug logs by navigating to Backend > Settings > Logs > Event log. If you don’t see the applicable API calls in the logs, you may need to clear Curator’s cache by using the Clear Cache button in the upper right portion of the Backend, and then repeat the steps to recreate the troublesome scenario.

​
Using Postman to Test Connection

Sometimes, it’s difficult to establish a connection to Tableau and the reason why isn’t clear. One method to help rule out bugs in Curator is to use the Postman application to directly make the API call. This document will guide you through using Postman to authenticate to Tableau’s REST API like Curator does behind the scenes.

​
Install Postman

The first step is to download and install Postman. You can get it from: https://www.postman.com/downloads/

​
Make API Call

Follow these steps to configure a new API call against Tableau’s REST API.
  1. Open Postman and start a new tab.
  2. Enter your Tableau Server/Cloud URL into the URL bar. Append /api/3.4/auth/signin. Update the API version if needed based on this page.
  3. Change the request type from GET to POST.
  4. Click on the Body tab.
  5. Select raw.
  6. In the text box, copy and paste the following XML: Username/Password:
    Personal Access Token (PAT):
  7. Fill in the username/password or PAT name/secret, and site content URL details within the above XML.
  8. Click the Send button.
You should get back XML with a credentials session token and the site and user IDs. Postman Screenshot If needed, use the credentials session token from this response to make subsequent API calls to Tableau. Open the headers tab for the request and add an entry where the key is X-Tableau-Auth and the value is your credentials session token. If this token expires, you’ll need to make a new request to the signin end point to get a new token.

​
Admin Account Login with Multiple Connections

When Curator is configured with multiple Tableau connections (for example, a production server and a test server), only one connection can be designated as the primary connection. The primary connection controls which Tableau Server’s user accounts are synced into Curator and, therefore, which accounts can log in to the portal.

​
Symptom

An admin account that exists on one Tableau Server can log in to the portal, while an admin account that exists on a different Tableau Server cannot. The login attempt may fail silently or return an authentication error, even though the credentials are correct on their respective Tableau Server.

​
Cause

Curator’s Tableau Sync only pulls user accounts from the primary connection. If your admin account exists on a non-primary connection, that account is never synced into Curator and cannot be used to log in to the portal. This limitation also applies when the connection uses the Tableau Server authentication type — users must exist on the primary site of the primary server, not merely be synced from elsewhere, in order to authenticate against the portal.

​
Resolution

There are two paths forward depending on your requirements.

​
Option 1: Consolidate Users on the Primary Connection

If you want to keep all Tableau connections under a single Curator instance, you need to ensure all users who must log in to the portal exist on the primary site of the primary Tableau Server. There are two ways to approach this:
  • Add users directly to the primary site — Create the accounts on the primary Tableau Server’s primary site so they are picked up by Tableau Sync. Note that usernames must match exactly across Tableau Servers so that Curator can correctly associate a portal login with the right account on each server. Also be aware that users who exist on both Tableau Servers will require a license on each, which can significantly increase licensing costs if there is little overlap between the two user populations.
  • Create a dedicated authentication site — Set up a separate site on the primary Tableau Server that contains no content and exists solely to hold user accounts for Curator’s sync. Configure that site as the primary site in Curator’s connection settings. Users must still exist on this site with usernames that match their accounts on the other Tableau Server, and the same per-server licensing considerations apply. However, this approach keeps content permissions and access concerns separate from portal authentication while still allowing a single Curator instance to serve all users.
To verify or change which connection is set as the primary:
  1. Navigate to Backend > Integration > Connections.
  2. Locate the connection that contains the admin account you want to use for portal login.
  3. Click to edit that connection and check whether the Primary toggle is enabled.
  4. If it is not the primary connection, enable the Primary toggle. Only one connection can be primary at a time, so enabling it on this connection will automatically disable it on the previous primary connection.
  5. Save the connection settings.
  6. Run a Tableau Sync to pull the updated user accounts from the new primary connection.
  7. Verify that the admin account can now log in to the portal.
Note: You do not have to reassign the Primary flag before disabling a connection that currently holds it. When you turn a primary connection’s Enabled toggle off and save, Curator automatically releases its Primary flag and promotes another active connection to primary, then shows a flash message naming the connection that is now primary. If no other active connection remains to take over, Curator instead shows a warning that no primary is set, in which case you should enable a connection and mark it primary using the steps above.

​
Option 2: Deploy Separate Curator Instances

If you have two distinct user populations that each require ongoing access to their own Tableau Server — for example, an internal team that must always reach the production server and an external partner team that must always reach a separate partner server — deploy separate Curator instances, one per Tableau Server. Each instance is configured with only one Tableau connection, so its primary connection is unambiguous and each user population has its own portal backed by the correct server. Note that licensing varies depending on your use case:
  • Two production Curator instances — Each production-level Curator portal requires its own Curator license, so if each Tableau Server/Curator pair has a different purpose for their respective users, then this will require separate Curator licenses for each.
  • Separating test and production environments — If one instance is a production portal and the other is a matching test environment for a separate, but equivalent test Tableau Server, this is covered under the existing Curator license. Contact InterWorks if you have questions about your specific licensing situation.

​
Rotating the Service Account Password or PAT

Rotating the credentials on an existing connection — a scheduled password reset on the Tableau service account, or replacing a Personal Access Token before it expires — is a much smaller job than the site migration described below. The Tableau Server URL and Site Content URL do not change, the Connected App configuration is separate and does not change, and no Dashboard needs to be re-created. Only the credential fields and Curator’s cache need attention.

​
Before the Reset

Take an inventory of everywhere the account is used, because each location stores its own copy of the credentials and each one has to be updated:
  • Every Curator portal. A service account shared across several portals means several separate updates. There is no central place to change it once.
  • Every Tableau connection in each portal. Navigate to Backend > Integration > Connections and check the Service Username (or Personal Access Token Name) on each Tableau connection.
  • Every entry under Secondary Sites. Each secondary site in the repeater carries its own Personal Access Token Name and Secret. These PATs must not be shared with any other site or portal, so if the rotation affects the account that owns them, each entry needs its own new token.

​
Rotation Checklist

Work through this in each affected portal, after the new password or PAT exists in Tableau:
  1. Navigate to Backend > Integration > Connections and open the affected connection.
  2. Update only the credential fields: the Service Password, or the Personal Access Token Name and Personal Access Token Secret. Leave the Tableau Server URL, Site Content URL, and all Connected App fields exactly as they are.
  3. Update the Personal Access Token Name and Personal Access Token Secret on each Secondary Sites entry that needs a new token.
  4. Save the connection using the button in the upper right.
  5. Saving clears Curator’s cached permission results for Tableau content, so a separate cache clear is not required. See below.
  6. Load a Dashboard as an end user (not as a backend administrator) and confirm the content, thumbnails, and permissions all resolve.

​
Saving Is the Validation Step

Curator re-authenticates against Tableau every time a connection is saved, whether or not the credentials were changed, and it also confirms that the account still holds a site or server administrator role on the site. If either check fails, the save is rejected and the error appears on the Service Username or Personal Access Token Name field with the message Tableau returned. A connection that saves without error has proven the new credentials work, so there is no separate “test connection” step to run. For PAT connections, a successful save also refreshes the read-only Personal Access Token Expiration field from Tableau’s sign-in response. Seeing a new expiration date is a quick confirmation that Curator is using the token you just entered rather than the previous one. If a save is rejected and the reason is not obvious, use the Postman steps above to confirm the new credentials authenticate against Tableau independently of Curator, or enable Debug Mode for Tableau Server to capture the exact request and response.

​
Cached Permission Results After a Rotation

Curator caches the outcome of each permission check — per user, per Dashboard — for 60 minutes, so that viewing content does not require a REST API call every time. While the credentials were wrong, Curator could not sign in, so it hid the connection’s content (see Content Hidden While a Connection Is Down) and cached those denials for only five minutes. Saving the connection clears every cached permission result for Tableau content, including those denials and the cached menus, pages, tiles, and search results built from them, so users see the correct content on their next page load. This applies to reverting as well: changing the password in one portal to test it and then putting the original value back is also a save, so it clears the same cached results. If a user still reports a stale result after the save, the Clear Cache button in the upper right of the backend is a safe extra step.

​
Dashboards Marked Not Found During the Window

If the daily Dashboard ID sync happened to run while the credentials were broken, Dashboards on that connection may be flagged with a Not Found on Tableau callout in Backend > Tableau > Dashboards. No manual re-sync is needed: saving the connection with working credentials queues a Dashboard ID refresh automatically, and each Dashboard it fixes gets a metadata refresh. See Dashboards Marked Not Found After a Connection Outage for the full detail, including how long to allow for the queue to catch up.

​
Migrating Between Tableau Cloud Sites

When a Tableau Cloud tenant is migrated from one site to another (for example, moving from a legacy site to a newly provisioned one), Curator will continue to reference the old site until its connection settings are updated. After migration, users will commonly report permission errors such as dashboards failing to load, thumbnails disappearing, or content that was previously visible no longer appearing in listings. These errors are almost always caused by stale cached permission data and outdated connection credentials pointing at the previous site. Work through the following checklist on the Curator backend to point the connection at the new Tableau Cloud site:
  1. Navigate to Backend > Settings > Tableau > Tableau Server Settings.
  2. Update the Tableau Server URL to match the new Tableau Cloud host (for example, https://10ax.online.tableau.com).
  3. Update the Site Content URL to the content URL of the new site. This is the value that appears in the Tableau Cloud browser URL immediately after /site/ when you are signed in.
  4. Regenerate the Personal Access Token (PAT) on the new Tableau Cloud site and update both the Personal Access Token Name and Personal Access Token fields in Curator. PATs are site-specific and will not carry over from the old site.
  5. Verify the Connected App configuration in the new site. The Client ID, Secret ID, and Secret Value must all be regenerated on the new site and updated in Curator. See Creating Integrations: Tableau Connection - Connected Apps for full details.
  6. Update any entries under Secondary Sites so that each one points at its equivalent site on the new Tableau Cloud host, including the Site Content URL, PAT credentials, and Connected App details for each secondary site.
  7. Save the connection settings using the button in the upper right of the backend.
  8. Clear the backend cache using the Clear Cache button in the upper right of the backend. This step is required — skipping it will cause the permission errors described below to persist.
  9. Test the connection by loading a Dashboard as an end user and confirming that content, thumbnails, and permissions all resolve correctly.

​
Why Permission Errors Persist After Migration

Curator caches the result of permission checks against Tableau for 60 minutes to avoid making a REST API call every time a user views a Dashboard or browses content. When a site migration occurs, these cached permission results still reference the old site and will continue to be served to users until either the cache entries expire or the cache is manually cleared. This is why permission errors can appear to “stick” after migration even when the connection settings in Curator have already been updated — the new settings are in place, but cached answers from the old site are still being returned. Clearing the backend cache immediately after saving the updated connection settings invalidates these entries and forces Curator to re-check permissions against the new site on the next request. If errors continue to occur after completing the checklist and clearing the cache, enable Debug Mode for Tableau Server to capture the exact API calls Curator is making and the responses it is receiving from the new site. You can also use the Postman steps above to confirm directly that the new PAT and Site Content URL authenticate successfully against the new Tableau Cloud site independently of Curator.