Was this page helpful?
Yes No

Web Data Connectors in Tableau Server

Tableau Server on Windows now includes Tableau Services Manager (TSM), which replaces the Configuration Utility and the command line tool. If you need help for an earlier version of Tableau Server, see the Tableau Help page.

Web data connectors (WDCs) are web pages that provide a data connection that is accessible over HTTP for data sources that don't already have a connector in Tableau. WDCs allow users to connect to almost any data that is accessible over the web and to create extracts for their workbooks. Data sources for a WDC can include internal web services, JSON data, REST APIs, and other sources that are available over HTTP or HTTPS. Users can create their own WDC or use connectors that were created by others.

For information about how to use a WDC in Tableau Desktop, see Web Data Connector in the Tableau Desktop documentation.

For information about how to create a WDC, see the Web Data Connector documentation on Github.

Before you run connectors on Tableau Server

As a security measure, Tableau Server won't run WDCs unless you approve the connector, as explained in this topic.

Note: You must be a server administrator to approve WDCs for use on Tableau Server.

WDCs require your approval because they contain executable code and typically make requests to third-party websites. Before a user can use a WDC with Tableau Server, you must either add the domain and port used by the connector to a safe list (whitelist) and also include the domains that a connector can send requests to and receive requests from on a secondary safe list (secondary whitelist). Before you do this, we recommend that you vet and test the connector so that you know what the connector does and what sites it connects to. For more information, see Testing and Vetting Web Data Connectors.

When you add a connector to the safe lists (whitelists), you configure Tableau Server to allow connections to a particular URL where the connector is hosted and from a URL which the connector can query. This is the only way to allow Tableau Server to run WDCs. The connectors can then be hosted on a server inside your organization's firewall or on an external domain. Importing WDCs is not supported for Tableau Server.

Manage connectors in a safe list

To add a WDC to the safe list, use the tsm data-access web-data-connectors add command. This command and the related commands described below let you perform the following tasks:

  • Add WDCs to the safe list and secondary safe list.

  • Allow or disallow all WDCs, or WDC refreshes.

  • Remove one or more connectors from the safe list.

  • List all WDCs on the safe list and secondary safe list.

Updating WDC safe lists requires a server restart

After running any commands that make changes to WDCs, you need to apply your pending changes using the tsm pending-changes apply command.

The pending-changes apply command displays a prompt to let you know this will restart Tableau Server if the server is running. The prompt displays even if the server is stopped, but in that case there is no restart. You can suppress the prompt using the --ignore-prompt option, but this does not change the restart behavior. For more information, see tsm pending-changes apply.

Add connectors to the safe list and secondary safe list

To add a connector to the safe list and secondary safe list, use the tsm data-access web-data-connectors add command, providing the name, safe list URL, and secondary safe list URLs. You can also manage WDCs using the web-data-connector-settings Entity. After running this command, you need to apply your pending changes using the tsm pending-changes apply command.

tsm data-access web-data-connectors add --name 'WTA WDC' --url https://dtreskunov.github.io:80/wta-wdc/ --secondary https://dtreskunov.github.io/*

Notes on formatting:

  • Be sure to use straight quotes (" and '), not curly or "smart" quotes, around the name of the WDC.
  • For many WDCs, the port specified for the --url option is 443 or 80, but you can check the value for your connector by looking at the data source details on Tableau Server.
  • If a WDCs send requests to and receive data from multiple domains, use a comma-delimited list of URL for the --secondary option.
  • To add an entire domain to the secondary safe list, end the domain URL with a wildcard character (*).

Allow or disallow WDCs or WDC extract refreshes

To allow or disallow WDCs, or WDC extract refreshes, use the following command before running tsm pending-changes apply:

tsm data-access web-data-connectors allow

Remove one or more WDCs from the safe list

To remove one or more WDCs from the safe list, use the following command before running tsm pending-changes apply:

tsm data-access web-data-connectors delete

List all WDCs on the safe list

To list all WDCs on the safe list, use the following command:

tsm data-access web-data-connectors list

Refresh the extract for a connector

When a user creates a workbook that uses a WDC, Tableau Server creates an extract from the data returned by the connector. If the user then publishes the workbook, the publish process sends the workbook and the data extract to the server.

Tableau can refresh an extract that was created by a WDC, the same as it can refresh any extract. If the connector requires credentials to sign in to the web-based data source, you need to ensure that the credentials are embedded with the data source, and that the WDC is on the safe list for the server. Tableau Server cannot refresh the extract if the connector requires credentials and they are not embedded with the data source. This is because the refresh can occur on a schedule or in some other background context, and the server cannot prompt for credentials.

Currently, there is no way to re-authenticate a data source from Tableau Server directly. If the data source has credentials that expire, or was published without embedding the credentials, the workbook and data extract need to be published again with the new embedded credentials.

If the background process that performs the refresh operation fails, it creates an alert and a log entry that indicates this issue. Users will be able to see that the timestamp on the extract does not change.

To disable refresh for all WDCs, use the tsm data-access web-data-connectors allow -r false command.

Troubleshooting

If the server experiences problems with adding connectors to the safe list, you can examine the log files. Be sure to check the log files on both the initial server node and on the other nodes that are running the gateway process. For more information about log files, Server Log File Locations.

If the issue is that Tableau Server will not refresh an extract that was created by a WDC, make sure that the webdataconnector.refresh.enabled configuration setting has been set to true. If it is set to false, run the following command to allow extract refreshes for all WDCs on the server:

tsm data-access web-data-connectors allow -r true

Note: The safe list is the only way of allowing Tableau Server to run web data connectors. Importing web data connectors was deprecated starting with version 10.5.