Tableau Server on Windows Help

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 have been created by others.

For information about how to use a WDC in Tableau Desktop, see Web Data Connector(Link opens in a new window) in the Tableau Desktop documentation.

For information on 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 add the domain and port used by the connector to a safe list and also include the domains that a connector can send requests to and receive requests from on a secondary safe list. 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, 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 organisation'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.

If the pending changes require a server restart, the pending-changes apply command will display a prompt to let you know a restart will occur. This 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 behaviour. If the changes do not require a restart, the changes are applied without a prompt. 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. A prompt warns you that the command will restart Tableau Server. If Tableau Server is currently running it is restarted, and if it is stopped it is left in a stopped state with no restart.

tsm data-access web-data-connectors add --name "USGS Earthquakes" --url https://tableau.github.io:443/webdataconnector/Examples/html/earthquakeUSGS.html --secondary https://tableau.github.io/.*,https://earthquake.usgs.gov/.*,https://maxcdn.bootstrapcdn.com/.*,https://ajax.googleapis.com/.*,https://connectors.tableau.com/.*

Notes on formatting:

• Be sure to use straight quotes (" and '), not curly or "smart" quotes, around the name of the WDC. Use double quotes (") if the name contains a space.
• 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. You must specify the port number as part of the URL if the WDC is using SSL (HTTPS). For example, to use the default port for HTTPS, the URL might look like the following: https://example.com:443/WDC/.
• A URL or comma-delimited list of URLs must be specified for the --secondary option, which indicates the domains that provide the libraries and sources that the WDC needs to access. This option cannot be omitted or left empty unless the WDC does not use any secondary domains. If you don't know whether the WDC uses secondary domains, or what the secondary domains are, you might need to contact the developer of the WDC. You can also choose to use http://.* and https://.* wildcard URLs to allow all domains. However, we strongly recommend that you use more specific URLs to increase security.
• To add an entire domain to the secondary safe list, end the domain URL with a wildcard expression. Use .* as the wildcard to indicate the entire domain, as in the following example: https://example.com/.*.

Allow or disallow WDCs or WDC extract refreshes

To allow or disallow WDCs, or WDC extract refreshes, use the tsm data-access web-data-connectors allow command with the -t or -r options. By default, WDCs and WDC extract refreshes are allowed. If you change this setting, you need to run the tsm pending-changes apply command. For more information about the command and the command options, see 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 tsm data-access web-data-connectors delete command. If you change this setting, you need to run the tsm pending-changes apply command. For more information, see tsm data-access web-data-connectors delete.

List all WDCs on the safe list

To list all WDCs on the safe list, use the tsm data-access web-data-connectors list command. For more information, see: 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, Tableau Server Logs and 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.