Run Your Connector

Note: the below is intended for connector developers. Customer-facing documentation is available here.

In this section

• Load order and class name collisions
  • Tableau 2022.2 and newer
  • Tableau versions older than 2022.2
  • Load order
• Run Your Packaged Connector (TACO file)
  • Run a packaged connector in Tableau Desktop
  • Run a packaged connector in Tableau Prep Builder
  • Run a packaged connector in Tableau Server
    • Option 1 (Preferred, available in Tableau 2021.2 and newer)
    • Option 2
    • Option 2 (For in-development connectors)
  • Verify the signature
    • Disabling signature verification
• Run Your Under Development Connector
  • Set up Tableau Desktop
  • Set up Tableau Server

Load order and class name collisions

Tableau 2022.2 and newer

If a connector has the same class as a connector that has already been registered, Tableau will load the connector with the highest connector version number (the plugin-version attribute in the connector manifest).

If both connectors have the same version, connector loaded first will have precedence. See the load order below.

Tableau versions older than 2022.2

If a connector has the same class as a connector that has already been registered, the new connector will be rejected. This means that connectors loaded first have precedence when two connectors share the same class name.

Load order

Tableau loads connectors by directory in the following order:

1. Built-in Tableau connectors
2. Connectors located in ``C:\Program Files\Tableau\Connectors (Windows) or /opt/tableau/connectors` (Linux)
3. Connectors located in My Tableau Repository/Connectors
4. (Optional) Connectors in the dev path specified by -DConnectPluginsPath

Run Your Packaged Connector (TACO file)

Starting in 2019.4, you can load packaged connectors (otherwise known as TACO files). To use a connector in earlier Tableau versions, or to run an unpackaged connector, see Run Your “Under Development” Connector below.

Run a packaged connector in Tableau Desktop

1. Copy the .taco file into your My Tableau Repository/Connectors directory.
   • Windows: C:\Users\\[Windows User]\Documents\My Tableau Repository\Connectors
   • macOS: /Users/[user]/Documents/My Tableau Repository/Connectors
2. Launch Tableau Desktop.

Run a packaged connector in Tableau Prep Builder

1. Copy the .taco file to your My Tableau Prep Repository\Connectors directory:
   • Windows: C:\Users\\[Windows User]\Documents\My Tableau Prep Repository\Connectors
   • macOS: /Users/[user]/Documents/My Tableau Prep Repository/Connectors
2. Launch Tableau Prep Builder.

Run a packaged connector in Tableau Server

Option 1 (Preferred, available in Tableau 2021.2 and newer)

For each machine:

1. Drop your .taco file into the following directory:
   • Windows: C:\Program Files\Tableau\Connectors
   • Linux: /opt/tableau/connectors
2. Restart Tableau Server

Option 2

For each machine:

1. Drop your .taco file into the following directory:
   • [Tableau_Server_Installation_Directory]/data/tabsvc/vizqlserver/Connectors
2. To enable your connector for Prep, you also need to add your taco to the following locations:
   • Tableau Prep Conductor: [Tableau_Server_Installation_Directory]/data/tabsvc/flowprocessor/Connectors
   • Tableau Flow Web Authoring: [Tableau_Server_Installation_Directory]/data/tabsvc/flowqueryservice/Connectors or [Tableau_Server_Installation_Directory]/data/tabsvc/flowminerva/Connectors/, depending on which directory exists
3. Restart your server.

Option 2 (For in-development connectors)

1. Create a directory for Tableau connectors. This needs to be the same path on each machine, and on the same drive as the server is installed on. For example: C:\tableau_connectors
2. Copy your packaged connector file (with a .taco filename extension) into the folder your created on each node.

3. Set the native_api.connect_plugins_path option. For example:

    tsm configuration set -k native_api.connect_plugins_path -v C:/tableau_connectors
   

   If you get a configuration error during this step, try adding the --force-keys option to the end of the command.

4. Apply the pending configuration changes. This restarts the server.

    tsm pending-changes apply
   

   Note that whenever you add, remove, or update a connector, you need to restart the server to see the changes.

For information about using TSM to set the option, see tsm configuration set Options in the Tableau Server Help.

Verify the signature

To be loaded in Tableau, a packaged connector must be signed by a trusted certificate.

Note: Signature verification was added to Tableau Desktop in 2019.4 and Tableau Server in 2020.1.

If the connector can’t be verified, you will see the following error: Package signature verification failed during connection creation

This can happen because the connector is unsigned, because the certificate’s trust chain does not link back to a trusted certificate authority, or because a previously valid certificate has expired.

For more information about signing a packaged connector, see Package and Sign Your Connector for Distribution and Signature Verification Log Entries

Disabling signature verification

To use an unsigned packaged connector, you can disable signature verification.

• On Tableau Desktop, you use this command: -DDisableVerifyConnectorPluginSignature=true

• On server, you can disable signature verification by setting native_api.disable_verify_connector_plugin_signature to true via TSM.

Run Your Under Development Connector

Set up Tableau Desktop

For Windows:

1. Create a directory for Tableau connectors. For example: C:\tableau_connectors
2. Put the folder containing your connector’s manifest.xml file in this directory. Each connector should have its own folder. For example: C:\tableau_connectors\my_connector
3. Run Tableau using the -DConnectPluginsPath command-line argument, pointing to your connector directory. For example: tableau.exe -DConnectPluginsPath=C:\tableau_connectors

For macOS:

Note: In the steps below, replace [username] with your name (for example /Users/agarcia/tableau_connectors) and [version] with the version of Tableau that you’re running (for example, 2019.3.app).

1. Create a directory for Tableau connectors. For example: /Users/[username]/tableau_connectors
2. Put the folder containing your connector’s manifest.xml file in this directory. Each connector should have its own folder. For example: /Users/[username]/tableau_connector/my connector
3. Run Tableau using the -DConnectPluginsPath command-line argument and pointing to your connector directory. For example:

    /Applications/Tableau\ Desktop\[version].app/Contents/MacOS/Tableau -DConnectPluginsPath=/Users/[username]/tableau_connectors
   
   

Set up Tableau Server

1. For each server node:
   • Create a directory for Tableau connectors. This needs to be the same path on each machine, and on the same drive as the server is installed on. For example: C:\tableau_connectors
   • Put the folder containing your connector’s manifest.xml file in this directory. Each connector should have its own folder. For example: C:\tableau_connectors\my_connector
2. Set the native_api.connect_plugins_path option. For example:

    tsm configuration set -k native_api.connect_plugins_path -v C:/tableau_connectors
   

   If you get a configuration error during this step, try adding the --force-keys option to the end of the command.

3. Apply the pending configuration changes to restart the server: tsm pending-changes apply

   Note: Whenever you add, remove, or update a connector, you must restart the server to see the changes.

For information about using TSM to set the option, see tsm configuration set Options in the Tableau Server Help.