VOOZH about

URL: https://www.cdata.com/kb/tech/bitbucket-tableau-setup.rst

⇱ Getting Started with the CData Tableau Connector for Bitbucket

Getting Started with the CData Tableau Connector for Bitbucket

👁 Dibyendu Datta
Dibyendu Datta
Lead Technology Evangelist
Complete guide to installing, licensing, and connecting with the CData Tableau Connector for Bitbucket.

This guide explains everything you need to get started with the CData Tableau Connector for Bitbucket. You'll learn how to install and license the connector, configure your first connection, and explore next steps for working with Bitbucket data in your applications.

This setup guide applies to Tableau Desktop, Tableau Prep, and Tableau Server environments.

Installation & Licensing

The CData Tableau Connector for Bitbucket enables Tableau Desktop, Tableau Prep, and Tableau Server to connect directly to live Bitbucket data. This section details installation prerequisites, platform support, connector deployment, and licensing requirements.

System Requirements

The connector is supported in environments where Tableau Desktop, Tableau Prep, or Tableau Server are available. The CData Tableau Connector for Bitbucket supports both Windows and macOS platforms.

Operating System Support

Windows

  • Windows 10 (64-bit)
  • Windows 11 (64-bit)
  • Windows Server 2016, 2019, or 2022 (for Tableau Server deployments)

macOS

  • macOS 10.14 or later

Tableau Components

  • Tableau Desktop 2020.3 or later (for automatic installation); Tableau Desktop 2020.1 or later (with manual registration)
  • Tableau Prep Builder 2020.4.1 or later
  • Tableau Server 2020.1 or later

For older versions of Tableau, use the CData ODBC Driver or JDBC Driver for Bitbucket instead.

Software Dependencies

  • Java Runtime Environment (JRE) - an up-to-date version of Java is required

Installing the Tableau Connector

Windows

  1. Download the CData Tableau Connector for Bitbucket.
  2. Run the installer and follow the installation wizard.
  3. The installer deploys the connector to the default installation directory: C:\Program Files\CData\CData Tableau Connector for Bitbucket 20XX.
  4. If you have Tableau Desktop 2020.3 or later, the setup automatically installs the connector into your personal Tableau repository.
  5. Once the installation is complete, click Finish.

Note: If you are using Tableau Prep or an earlier version of Tableau Desktop (before 2020.3), the setup will not detect your Tableau installation, and you will need to register the connector manually (see Manual Registration below).

macOS

  1. Download the CData Tableau Connector for Bitbucket.
  2. Run the installer package and follow the installation wizard.
  3. The installer deploys the connector to: /Applications/CData Tableau Connector for Bitbucket 20XX.
  4. If you have Tableau Desktop 2020.3 or later, the setup automatically installs the connector into your personal Tableau repository.
  5. Once the installation is complete, click Finish.

Manual Registration (Tableau Desktop or Tableau Prep)

If automatic registration did not occur, follow these steps:

  1. Find the connector install directory:
    • Windows: C:\Program Files\CData\CData Tableau Connector for Bitbucket 20XX
    • macOS: /Applications/CData Tableau Connector for Bitbucket 20XX
  2. Find your Tableau repository:
    • Windows: Documents\My Tableau Repository (or "My Tableau Prep Repository" for Prep)
    • macOS: /Users/[username]/Documents/My Tableau Repository
  3. Open the connector install directory and navigate to the lib folder.
  4. Copy cdata.bitbucket.legacy.taco into the Connectors directory within your Tableau repository.

Note: As of Tableau Prep 21.2 and above versions, standard .taco files are supported instead of legacy .taco files.

Activating Your License

The CData Tableau Connector for Bitbucket uses file-based licensing rather than license key activation. The license file is included in the installation package.

If not, you should have received your license key via email from the CData Orders Team. The license key looks like this: XXXX-XXXX-XXXX-XXXX-XXXX

Licensing Steps

  1. Navigate to the lib folder in your connector installation directory:
    • Windows: C:\Program Files\CData\CData Tableau Connector for Bitbucket 20XX\lib
    • macOS: /Applications/CData Tableau Connector for Bitbucket 20XX/lib
  2. Locate the license file: cdata.tableau.bitbucket.lic
  3. Place the .lic file in the same folder as the connector's JAR file (cdata.tableau.bitbucket.jar).

The automatic install process attempts to register both the driver JAR and the license file. The JAR file is copied to one of these locations:

  • Windows: C:\Users[username]\My Tableau Repository\Drivers
  • macOS: /Users/[username]/Documents/My Tableau Repository/Drivers

Note: If you are running a trial, the trial license file is included with the installer. No additional activation steps are required.

Deploying to Tableau Server

Windows

  1. Install the CData Tableau Connector for Bitbucket on the Tableau Server machine.
  2. Locate the connector file: cdata.bitbucket.taco
  3. Copy the .taco file to the Tableau Server connectors directory: [TableauServerRoot]\data absvc\vizqlserver\Connectors
    • In most cases, TableauServerRoot is located under "C:\ProgramData"
  4. Ensure the JAR file (cdata.tableau.bitbucket.jar) and license file (cdata.tableau.bitbucket.lic) are in the Tableau Server drivers directory.
  5. Restart Tableau Server.

Linux

  1. Unpack the setup.zip archive. Creating a directory such as "/opt/cdata/.bitbucket" is recommended.
  2. Navigate to the lib subdirectory under the install directory.
  3. Generate a license file by running the licensing tool and following the prompts: 
    java -jar cdata.tableau.bitbucket.jar -l
  4. Copy cdata.tableau.bitbucket.jar and cdata.tableau.bitbucket.lic into the drivers directory: /opt/tableau/tableau_driver/jdbc
  5. Copy cdata.bitbucket.taco into the connectors directory: /var/opt/tableau/tableau_server/data/tabsvc/vizqlserver/Connectors
  6. Restart Tableau Server.

Note: If you cannot execute the java command, you will need to install a Java Runtime Environment (JRE).

Common Licensing Questions

Can I use my license on multiple machines?

Yes, depending on your subscription tier. Check your order confirmation or contact your account representative for details. If you are unsure of who your account representative is, contact [email protected].

I lost my license key. How do I retrieve it?

Email [email protected] with your order number, and we'll resend your license key.

Can I transfer my license to a different machine?

Yes. When transferring the license to a different machine, you will need to submit a License Transfer Request on our site linked below:

https://www.cdata.com/lic/transfer/

After the License Transfer Request is submitted and successfully processed, an activation will be added to your Product Key, and you will be able to activate the full license on the other machine. Once this process is finished, the license on the previous machine will be invalid.

For additional licensing questions, contact [email protected]. Viewing and upgrading your license can now be done through our self-service portal at portal.cdata.com.

Connection Configuration

After installing the connector, you can connect and create a Data Source for Bitbucket data.

Complete the following steps to connect to the data:

  1. Open Tableau Desktop.
  2. Under Connect | To a Server, click More...
  3. Select the data source called Bitbucket by CData.
  4. Enter the information required for the connection.
  5. Click Sign In.
👁 Search for the Bitbucket by CData connector

The connector makes the most common connection properties available directly in Tableau. However, if you need to use more advanced settings or troubleshoot connection issues, the connector includes a separate connection builder that allows you to create and test connections outside of Tableau.

There are two ways to access the connection builder:

  • On Windows, use a shortcut called Connection Builder in the Start menu, under the "CData Tableau Connector for Bitbucket" folder.
  • Navigate to the driver install directory (by default, C:/Program Files/CData/CData Tableau Connector for Bitbucket) and run the .jar file in the lib directory.

In the connection builder, you can set values for connection properties and click Test Connection to validate that they work. You can also use the Copy to Clipboard button to save the connection string. This connection string can be given to the Connection String option included in the connector connection window in Tableau.

Configuring Connection Properties

For most queries, you must set the Workspace. The only exception to this is the Workspaces table, which does not require this property to be set, as querying it provides a list of workspace slugs that can be used to set Workspace. To query this table, you must set Schema to 'Information' and execute the query SELECT * FROM Workspaces>.

Setting Schema to 'Information' displays general information. To connect to Bitbucket, set these parameters:

  • Schema: To show general information about a workspace, such as its users, repositories, and projects, set this to Information. Otherwise, set this to the schema of the repository or project you are querying. To get a full set of available schemas, query the sys_schemas table.
  • Workspace: Required if you are not querying the Workspaces table. This property is not required for querying the Workspaces table, as that query only returns a list of workspace slugs that can be used to set Workspace.

Authenticating to Bitbucket

Bitbucket supports OAuth authentication only. To enable this authentication from all OAuth flows, you must create a custom OAuth application, and set AuthScheme to OAuth.

Be sure to review the Help documentation for the required connection properties for you specific authentication needs (desktop applications, web applications, and headless machines).

Creating a custom OAuth application

From your Bitbucket account:

  1. Go to Settings (the gear icon) and select Workspace Settings.
  2. In the Apps and Features section, select OAuth Consumers.
  3. Click Add Consumer.
  4. Enter a name and description for your custom application.
  5. Set the callback URL:
    • For desktop applications and headless machines, use http://localhost:33333 or another port number of your choice. The URI you set here becomes the CallbackURL property.
    • For web applications, set the callback URL to a trusted redirect URL. This URL is the web location the user returns to with the token that verifies that your application has been granted access.
  6. If you plan to use client credentials to authenticate, you must select This is a private consumer. In the driver, you must set AuthScheme to client.
  7. Select which permissions to give your OAuth application. These determine what data you can read and write with it.
  8. To save the new custom application, click Save.
  9. After the application has been saved, you can select it to view its settings. The application's Key and Secret are displayed. Record these for future use. You will use the Key to set the OAuthClientId and the Secret to set the OAuthClientSecret.
👁 Configure your Bitbucket connection

Getting Bitbucket Data in Tableau Desktop or Tableau Prep Builder

Once you establish the connection to Bitbucket data, you can configure which entities to visualize:

  1. Drag the tables and views you wish to visualize onto the join area. You can include multiple tables.
  2. Select Update Now or Automatically Update:
    • Update Now lets you preview the first 10,000 rows of the data source (or enter the number of rows you want to see in the Rows text box).
    • Automatically Update automatically reflects the changes in the preview area.

Creating Visualizations in Tableau Desktop

With the data source configured, you are ready to create visualizations:

  1. Click the tab for your worksheet.
  2. Columns are listed as Dimensions and Measures, depending on the data type. The CData Tableau Connector discovers data types automatically, allowing you to leverage the powerful data processing and visualization features of Tableau.
  3. Drag a field from the Dimensions or Measures area to Rows or Columns. Tableau creates column or row headers.
  4. Select one of the chart types from the Show Me tab.
  5. Tableau displays the chart type that you selected.
👁 Create visualizations in Tableau Desktop with your Bitbucket data

You can also use Custom SQL queries to further customize the exact Bitbucket data pulled. Click New Custom SQL in the data source pane and enter your SQL query to retrieve specific data from Bitbucket.

Preparing Data in Tableau Prep Builder

With the CData Tableau Connector for Bitbucket installed, you can build data preparation flows in Tableau Prep Builder:

  1. Open Tableau Prep Builder and click Connect to Data.
  2. Search for Bitbucket by CData in the connector list.
  3. Configure the connection by entering your authentication credentials and click Sign In. The connector supports Login, OAuth, and SSO authentication methods.
  4. Once connected, drag tables from the Connections pane to the flow canvas to add them as input steps.
  5. Use Tableau Prep's built-in tools to clean, shape, and transform your Bitbucket data by adding steps for filters, calculated fields, aggregations, pivots, or joins.
  6. Add an Output step to save your prepared data as a hyper extract, published data source, or CSV file.
👁 Prepare your Bitbucket data in Tableau Prep Builder

Tableau Prep Builder allows you to join, cleanse, filter, and aggregate Bitbucket data into reusable, repeatable flows. You can also use Custom SQL queries to define the exact Bitbucket data pulled into your flow by clicking New Custom SQL when adding an input step.

Common Connection Issues

Authentication Failed

Solution: Verify your credentials are current. For OAuth authentication, you may need to re-authorize CData in your Bitbucket Connected Apps settings. If using Basic authentication, ensure your Security Token is valid; tokens must be reset when passwords change. Contact [email protected] for authorization assistance.

Cannot Reach Server

Solution: Check firewall and proxy settings. Ensure outbound HTTPS (port 443) access to Bitbucket endpoints is allowed. You can configure proxy settings using the ProxyServer, ProxyPort, and ProxyUser connection properties. Contact [email protected] for specific port requirements.

Connector Not Appearing in Tableau

Solution: Ensure the TACO file is properly installed. For Tableau Desktop 2020.3+, the installer should automatically place it in your "My Tableau Repository/Connectors" folder. For manual installation, copy "cdata.bitbucket.legacy.taco" from the connector's lib directory to your Tableau Connectors folder. Restart Tableau after installation.

For additional connection troubleshooting, contact [email protected] with your specific error message.

What's Next

Now that you have installed, licensed, and configured the connector, here are some scenarios you can use to explore our Tableau Connectors:

Installation & Licensing

Do I need administrator rights to install the connector?

Yes. Administrator rights are required to install the CData Tableau Connector, as the installer writes to system directories and registers the required components.

Is the connector available for both Windows and Mac?

Yes. The CData Tableau Connector for Bitbucket is available for both Windows and macOS platforms. The connector appears directly in Tableau's native connector gallery for streamlined access to your Bitbucket data.

What versions of Tableau are supported?

The CData Tableau Connectors require Tableau Desktop 2020.3 or later and Tableau Prep Builder 2020.4.1 or later. For older versions of Tableau, use the CData ODBC Driver or JDBC Driver for Bitbucket instead.

Where do I place the license file?

Place the bundled .lic file (cdata.tableau.bitbucket.lic from the lib folder of the installation directory) in the same folder as the connector's JAR file.

Get Support

If you need assistance at any point:

Connecting

Can I use the Connection Builder to test my connection?

Yes. The connector includes a separate Connection Builder tool that allows you to create and test connections outside of Tableau. Access it via the Start menu shortcut (Windows) or by running the .jar file in the connector's lib directory. Use the Test Connection button to validate your settings.

How do I connect to multiple Bitbucket accounts?

Create separate data sources in Tableau, each configured with different Bitbucket credentials. When using OAuth, each connection will prompt for authentication with the respective Bitbucket account. Each data source stores its own connection settings independently.

Can I connect through a proxy server?

Yes. Proxy settings can be configured using the following connection properties:

  • ProxyServer: The hostname or IP address of your proxy server
  • ProxyPort: The TCP port of your proxy server
  • ProxyUser and ProxyPassword: Authentication credentials if required
  • ProxyAuthScheme: The authentication scheme (BASIC, DIGEST, NTLM, etc.)

By default, the connector uses the system proxy. Set ProxyAutoDetect to false to use a different proxy. For SOCKS proxies, use FirewallServer, FirewallPort, and set FirewallType to SOCKS5.

Refer to the Firewall & Proxy section of the documentation for required properties and supported proxy scenarios.

Performance & Troubleshooting

Why are my queries slow?

Check the following:

  • Use Extract mode if you are working with large datasets or performing heavy transformations. Extract mode caches data locally and reduces the number of live API calls.
  • Use Live Connection only when real-time data is required, as it sends every query to Bitbucket in real time.
  • Apply filters in Tableau to reduce the size of the dataset before loading.
  • Avoid selecting all columns if only a subset is needed - drag only the required tables/fields.
  • Monitor Bitbucket API limits, which can throttle performance.
  • Enable ServerSideAggregation to push aggregation operations to Bitbucket servers.

Contact [email protected] for help with query optimization and best practices.

How do I enable logging for troubleshooting?

Logging can be enabled through the connector's connection properties in the Connection Builder or directly in Tableau.

Set the following properties:

  • Logfile: A filepath that designates the name and location of the log file (e.g., C:\logs[rootadoname|tolower].log)
  • Verbosity: A numerical value (1-5) that determines the amount of detail in the log
  • MaxLogFileSize: Maximum log file size (default is 100 MB)
  • MaxLogFileCount: Maximum number of log files to retain

Verbosity Levels:

  • 1 - Errors only (recommended for normal operation)
  • 2 - Warnings and errors
  • 3 - Informational messages, including full request/response bodies
  • 4-5 - Debug-level detail, including binary transfer data

Note: Verbosity should not be set to greater than 1 for normal operation. Higher verbosity levels log substantial amounts of data and may delay execution times. Verbosity 3 and above may capture sensitive information.

Be prepared to upload the log file when contacting [email protected] for analysis.

What ports does the connector need access to?

Most Bitbucket connections require outbound HTTPS (port 443) access. Ensure your firewall allows outbound secure traffic to Bitbucket endpoints.

For environments using proxies or additional security layers, consult the Firewall & Proxy section of the connector documentation.

Can I use the connector in a Linux container or Docker?

Yes, with some considerations. The CData Tableau Connector for Bitbucket can be used on Linux for Tableau Server deployments.

For Tableau Server on Linux:

  1. Copy the connector files to "/opt/tableau/connectors" or "/var/opt/tableau_server/data/tabsvc/vizqlserver/Connectors/".
  2. Generate a license file by running the licensing tool in the lib subdirectory.
  3. Restart Tableau Server.

Note: Tableau Desktop runs only on Windows and macOS. For Tableau Cloud connectivity, use CData Connect Cloud.

General

Where can I find the complete list of supported SQL operations?

Refer to the SQL Compliance section of the Bitbucket connector documentation. The connector supports comprehensive ANSI-92 SQL including filtering, GROUP BY, JOINs, and aggregations. The connector pushes supported SQL operations directly to Bitbucket and uses an embedded SQL engine for client-side processing of unsupported operations.

What's the difference between Live Connection and Extract in Tableau?

Live Connection: Queries Bitbucket in real-time for every interaction. Best for dashboards requiring up-to-the-second data accuracy. It may be slower for large datasets due to API calls.

Extract: Creates a local snapshot of the data in Tableau's high-performance data engine. Best for large datasets, complex calculations, or when working offline. Schedule refreshes to keep data current. Reduces API calls and improves performance.

How often is the connector updated?

CData releases major updates to the Tableau Connector annually, with periodic maintenance updates as needed. Check your CData Account Portal or contact [email protected] for the latest version.

Can I use Custom SQL in Tableau with this connector?

Yes. You can use Custom SQL queries to further customize the exact Bitbucket data pulled. Click New Custom SQL in the data source pane and enter your SQL query. The connector supports standard SQL syntax and will translate queries to retrieve data from Bitbucket.

For questions not covered in this FAQ, contact [email protected].

Ready to get started?

Download a free trial of the Bitbucket Tableau Connector to get started:

 Download Now

Learn more:

👁 Bitbucket Icon
Bitbucket Tableau Connector

The fastest and easiest way to connect Tableau to Bitbucket data. Includes comprehensive high-performance data access, real-time integration, extensive metadata discovery, and robust SQL-92 support.