Was this page helpful?
Yes No
Tableau Help > Tableau Server for Windows Help > 

Web Data Connectors in Tableau Server

Web data connectors 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. Web data connectors 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 web data connector can include internal web services, JSON data, REST APIs, and other sources that are available over HTTP or HTTPS. Users can create their own web data connectors or use connectors that were created by others.

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

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

Before you run connectors on Tableau Server

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

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

Web data connectors require your approval because they contain executable code and typically make requests to third-party websites. Before a user can use a web data connector via Tableau Server, you must either add the connectors to a safe list (to a whitelist) or import the connectors into Tableau Server. 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.

Safe list method and import method comparison

When you add a connector to the safe list (whitelist), you configure Tableau Server to allow connections to a particular URL where the connector is hosted. This is the recommended way of allowing Tableau Server to run web data connectors. The connectors can then be hosted on a server inside your organization's firewall or on an external domain.

Alternatively, you can import a web data connector. When you import a connector, you run a tabadmin command that imports (copies) the connector from a location on your network to all of the machines in your Tableau Server installation.

Note: In versions of Tableau Server before 10.0, importing is the only way to run web data connectors on Tableau Server.

Reasons to use a safe list

You might want to add web data connectors to a safe list if:

  • Your organization wants to host the connector on a separate server in your network or on an external domain. (That is, on a computer that is not running Tableau Server.)

  • Your organization makes updates to connectors frequently. By adding the connector to the safe list, you avoid the need to re-import the connector each time you change it. 

  • The connector references many files and you do not want to import each file to Tableau Server individually.

Reasons to import web data connectors

As noted, the recommended way to configure Tableau Server to be able to run web data connectors is to use a safe list. However, you might want to import web data connectors if:

  • Your organization does not have an existing web server that you can use to host the connector.

  • Your organization has imported many connectors to Tableau Server in previous versions and wants to manage the connectors in a central location.

By default, both ways of configuring Tableau Server to run connectors are allowed. However, you can restrict the ways that connectors can be added or imported with the tabadmin set webdataconnector.whitelist.mode option. For more information, see tabadmin set options.

The safe list method

To add a web data connector to the safe list, use the tabadmin whitelist_webdataconnector command. This command lets you perform the following tasks:

  • Add a connector to the safe list.

  • List connectors on the safe list.

  • Remove a connector from the safe list.

  • Configure a secondary safe list, that is, a list of domains that a particular connector can send requests to and receive requests from.

For more information, see tabadmin whitelist_webdataconnector.

The import method

Use the import_webdataconnector, list_webdataconnectors, and delete_webdataconnector commands to manage imported connectors.

Import a web data connector

  1. Ensure that you have the HTML file for the web data connector and any supporting files, such as .css files or .js files.

    The HTML file name for the web data connector can only contain these characters:

    a-zA-Z0-9()~.-_

  2. On the server, run the import_webdataconnector command, as in this example:

    tabadmin import_webdataconnector connector1.html

    You can import a web data connector as a local file on the server or from a network share (for example, \\myshare\connector1.html), as in these examples:

    tabadmin import_webdataconnector c:\webdataconnectors\connector1.html
    
    tabadmin import_webdataconnector \\myshare\webdataconnectors\connector2.html

    When the command finishes, it displays a URL, as in this example:

    ===== Importing web data connector to server...
               -- The web data connector with the following URL was imported to the server:
            http://myserver/webdataconnectors/connector1.html

  3. Give the URL of the imported web data connector to any users who want to use that connector.

    Note: The URL displayed above uses the server's host name by default. If you have configured a DNS alias for the server, replace the server host name with the DNS alias.

Re-import a web data connector

If you want to re-import a web data connector that's already been imported (for example, you want to import an updated version of the connector), run the import_webdataconnector command with the overwrite option, as in this example:

tabadmin import_webdataconnector \\myshare\webdataconnectors\connector1.html --overwrite

The older version of the connector might still be available in the server's cache, and users who work with the connector might still see the older version. By default, the maximum lifetime for an item in the cache is eight hours. To force a cache reset, restart the server.

List imported connectors

As the server administrator, you can see a list of web data connectors by running the following command:

tabadmin list_webdataconnectors

In order to reference a web data connector in a workbook, users need to know the URL for the connector. To get a list of connector URLs, use this command:

tabadmin list_webdataconnectors --urls

Delete imported connectors

If you no longer need a web data connector, you should delete it from the server. Use the following command to remove an individual web data connector, where connector_name is the name of the connector file to delete:

tabadmin delete_webdataconnector connector_name

(To see a list of web data connectors on the server, use the tabadmin list_webdataconnectors command).

To remove all web data connectors from the server, use the following command:

tabadmin delete_webdataconnector --all

Note: When you delete a web data connector, a version of the connector might still be available in the server's cache, and users might still be able to work with the connector. By default, the maximum lifetime for an item in the cache is eight hours. To force a cache reset, restart the server.

Reference external files from imported connectors

If a web data connector .html file references external files, you must make sure that those files are available on the server. For example, a web data connector might reference an external .css file in a <link> element or a .js file in a <script> element.

If the external files are referenced using a URL (http://), Tableau Server can access the external files as long as the files are on a server that is accessible to Tableau Server.

If the external files are referenced as local files, you can import them into Tableau Server using the import_webdataconnector command. For example, if a web data connector that you are importing references the myconnectors.css file, you import the connector and the .css file using this sequence of commands:

tabadmin import_webdataconnector connector1.html
tabadmin import_webdataconnector myconnectors.css

An important point is that all files imported using the import_webdataconnector command are stored in the same directory on the server—Tableau Server does not let you import external files into a subdirectory. Therefore, you must make sure that any local files referenced in <link> or <script> elements in the connector's .html file do not include paths, only file names.

Imported connectors in a distributed environment

If your server is configured as a cluster, web data connectors are imported to each computer where a gateway process is running. This makes the web data connector available for distributed access across your cluster. Deleting a connector in a distributed environment removes the connector from all the computers where the gateway process is running.

In a distributed environment, the process of importing or deleting a web data connector might complete only partially. If you're importing a connector, the connector might be copied to some of the computers where the gateway process is running, but not to all of them. In that case, the tabadmin import_webdataconnector command reports the error using text like this:

The web data connector with the following URL has been imported to some gateways on the server, but not all.

Similarly, if you're deleting a web data connector, the connector might be removed from some computers but not all of them. The tabadmin delete_webdataconnector command reports the error using text like this:

The web data connector was deleted from some gateways on the server, but not all.

Note: If the delete process is partially successful, users can still access the connector.

If the import or delete process reports partial success, you can try either of the following solutions:

  • Run the import or delete process again. If you're importing, run the tabadmin import_webdataconnector command again, and use the --overwrite option to overwrite any instances of the connector that were successfully installed. If you're deleting, run the tabadmin delete_webdataconnector command again. Tableau Server will remove any remaining instances of the connector.

  • Stop the server, run tabadmin configure, and then restart the server. The configuration process makes sure that any web data connectors are correctly distributed (imported or deleted) in all nodes where the gateway process is running. Since this option requires you to stop the server, you would choose it if it's practical to stop the server, or if you have some other reason to stop and restart the server.

Performing site import and site export with web data connectors

Web data connectors are imported as server-wide resources; they are not associated with a specific site on your server. Therefore, if you export a site using the tabadmin exportsite command, the resulting .zip file does not include web data connectors that might be referenced by workbooks on the site.

Managing imported connectors for failover in a cluster

If your server is configured as a cluster with a backup primary server, you must make sure that web data connectors that you have imported to the primary are available if you need to failover to your backup primary. If the web data connectors are not available on the new primary after a failover, running the configuration process on the primary server can end up removing the connectors from other computers where a gateway process is running.

To make sure that web data connectors are available after a failover, follow these steps:

  1. Make sure that you keep an up-to-date backup of the web data connectors that have been imported to your server.

  2. After the primary fails, and before you start the backup primary, copy the web data connectors from the backup location to the following folder on the backup primary:

    C:\ProgramData\Tableau\Tableau Server\data\tabsvc\httpd\htdocs\webdataconnectors

    If you have created a backup of the primary server using the tabadmin backup command, the .tsbak file created by the backup file contains the web data connectors. You can extract the contents of a .tsbak file and get the web data connectors.

    If you installed Tableau Server on a different drive, substitute that drive letter for C:.

  3. Overwrite the tabsvc.yml file on the backup primary.

  4. Run the tabadmin failoverprimary command. For more information, see Quick Start: Creating a Backup Primary

If necessary, you can also reimport the web data connectors, as described earlier in this topic.

Refresh the extract for a connector

When a user creates a workbook that uses a web data connector, Tableau 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 web data connector, 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 web data connector 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.)

If you want, you can disable refresh for all web data connectors, even those that were previously imported. To disable refresh, use the tabadmin set command to change the webdataconnector.refresh.enabled setting to false, as in the following example:

tabadmin set webdataconnector.refresh.enabled false

Troubleshooting

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

If the issue is that Tableau Server will not refresh an extract that was created by a web data connector, make sure that the webdataconnector.refresh.enabled configuration setting has been set to true.

If you have re-imported a changed web data connector on the server (overwriting an existing one), but users who work with the web data connector are not seeing the changes, the users might be getting a cached version of the older version. By default, the cache is reset after eight hours; after a cache reset, older versions of the web data connector will no longer be used. If you want to force the cache to reset, you can restart the server.

If you have deleted an imported connector from the server but users are still able to work with the connector, the connector is probably still in the server's cache. A web data connector can stay available in the cache for up to eight hours. To clear the cache, restart the server. If you delete a web data connector from a server in a distributed environment, make sure that the connector has been successfully deleted from all computers where a gateway process is running.