Connection Dialog v1


Connection Dialog v2 is the recommended pattern for new connectors. For more details see the Connection Dialog v2 page.

Define Tableau Custom Dialog file elements

The TCD file defines which UI elements display in the dialog. The Connection Dialog V1 is a fixed list as defined by the file XSD.

Here’s an example of a TCD file:

<connection-dialog class='postgres_odbc'>
  <connection-config>
    <authentication-mode value='Basic' />
    <authentication-options>
      <option name="UsernameAndPassword" default="true" value="auth-user-pass" />
    </authentication-options>
    <db-name-prompt value="Database: " />
    <has-pre-connect-database value="true" />
    <port-prompt value="Port: " default="5432" />
    <show-ssl-checkbox value="true" />
  </connection-config>
</connection-dialog>

The authentication-mode and authentication-options tags control how a user is prompted to enter data source credentials. For more information on authentication modes, see Authentication modes.

The other tags control what prompts show up in the connection dialog. For example, this shows the Port prompt with the label of Port and a default value of 5432:

<port-prompt value="Port: " default="5432" />

Define custom vendor attributes

Vendors can add customized attributes (fields) to their connector plugin by using the vendor attributes.

These fields have a custom label and can be used for attributes in the connection strings that are not available in the attribute list. You can currently add three custom fields in your connector plugin.

To add a custom vendor attribute for an ODBC-based connector, you must modify these files:

To add a custom vendor attribute for an JDBC-based connector, you must modify these files:

Vendor defined attributes will be logged and persisted to Tableau workbook XML in plain text. This means the input for these fields cannot contain any Personally Identifiable Information (PII), as they are not secure and could leak sensitive customer information.

See examples below.

connection-resolver.tdr

    ...
    <required-attributes>
      <attribute-list>
        ...
        <attr>vendor1</attr>
        <attr>vendor2</attr>
        <attr>vendor3</attr>

      </attribute-list>
    </required-attributes>
    ...

connection-dialog.tcd

<connection-dialog class='postgres_jdbc'>
  <connection-config>
    ...
    <vendor1-prompt value="Log Level: "/>
    <vendor2-prompt value="Protocol Version: "/>
    <vendor3-prompt value="Char Set: "/>

  </connection-config>
</connection-dialog>

connectionBuilder.js (ODBC only)

(function dsbuilder(attr)
  {
    ...
    params["loglevel"] = attr[connectionHelper.attributeVendor1];
    params["protocolVersion"] = attr[connectionHelper.attributeVendor2];
    params["charSet"] = attr[connectionHelper.attributeVendor3];
    ...

connectionProperties.js (JDBC only)

      ...
      props["logLevel"] = attr[connectionHelper.attributeVendor1];
      props["protocolVersion"] = attr[connectionHelper.attributeVendor2];
      props["charSet"] = attr[connectionHelper.attributeVendor3];
      ...

See complete files here.

Supported Authentication Modes

No Authentication

User is never prompted for credentials.

<!-- Connection Dialog -->
<connection-dialog class='sample'>
    <connection-config>
        <authentication-mode value='None' />
        <authentication-options>
            <option name="None" default="true" value="auth-none" />
        </authentication-options>
        ...
    </connection-config>
</connection-dialog>
<!-- Connection Resolver -->
<tdr class='sample'>
    <connection-resolver>
        ...
        <connection-normalizer>
            <required-attributes>
                <attribute-list>
                    ...
                    <attr>authentication</attr>
                    ...
                </attribute-list>
            </required-attributes>
        </connection-normalizer>
    </connection-resolver>
    ...
</tdr>

Sample connection dialog noAuthOption.tcd

Username only

User is prompted for username during initial connection creation. Before Tableau 2020.3 the option element required value='no' instead of example below.

<!-- Connection Dialog -->
<connection-dialog class='sample'>
    <connection-config>
        <authentication-mode value='BasicUserNameOnly' />
        <authentication-options>
            <option name="Username" default="true" value="auth-user"/>
        </authentication-options>
        ...
    </connection-config>
</connection-dialog>
<!-- Connection Resolver -->
<tdr class='sample'>
    <connection-resolver>
        ...
        <connection-normalizer>
            <required-attributes>
                <attribute-list>
                    ...
                    <attr>authentication</attr>
                    <attr>username</attr>
                    ...
                </attribute-list>
            </required-attributes>
        </connection-normalizer>
    </connection-resolver>
    ...
</tdr>

Password only

Tableau 2019.4 and later

User is prompted for password during initial connection creation and reconnecting to the data source.

<!-- Connection Dialog -->
<connection-dialog class='sample'>
    <connection-config>
        <authentication-mode value='PasswordOnly' />
        <authentication-options>
            <option name="Password" default="true" value="auth-pass"/>
        </authentication-options>
        ...
    </connection-config>
</connection-dialog>
<!-- Connection Resolver -->
<tdr class='sample'>
    <connection-resolver>
        ...
        <connection-normalizer>
            <required-attributes>
                <attribute-list>
                    ...
                    <attr>authentication</attr>
                    <attr>password</attr>
                    ...
                </attribute-list>
            </required-attributes>
        </connection-normalizer>
    </connection-resolver>
    ...
</tdr>

Username and Password

User is prompted for username and password during initial connection creation, and password only when reconnecting to the data source. If the username can be blank replace value='Basic' with value='BasicNoValidateFields' below.

<!-- Connection Dialog -->
<connection-dialog class='sample'>
    <connection-config>
        <authentication-mode value='Basic' />
        <authentication-options>
            <option name="UsernameAndPassword" default="true" value="auth-user-pass"/>
        </authentication-options>
        ...
    </connection-config>
</connection-dialog>
<!-- Connection Resolver -->
<tdr class='sample'>
    <connection-resolver>
        ...
        <connection-normalizer>
            <required-attributes>
                <attribute-list>
                    ...
                    <attr>authentication</attr>
                    <attr>username</attr>
                    <attr>password</attr>
                    ...
                </attribute-list>
            </required-attributes>
        </connection-normalizer>
    </connection-resolver>
    ...
</tdr>

Multiple Authentication Modes

User is prompted for which authentication option to use, then a set of fields appear, conditional on that option. Depending on the option selected the user may or may not be prompted for credentials when reconnecting to the data source.

Supported authentication options are below. Starting in Tableau 2019.4, Password option is supported.

None
Username
Password
UsernameAndPassword
<!-- Connection Dialog -->
<connection-dialog class='sample'>
    <connection-config>
        <authentication-mode value='ComboBoxIntegrated' />
        <authentication-options>
            <option name="None" value="auth-none" />
            <option name="Username" value="auth-user" />
            <option name="UsernameAndPassword" value="auth-user-pass" default="true" />
        </authentication-options>
        ...
    </connection-config>
</connection-dialog>

Note: the value attribute value for all options is customizable by connector author, except None, which is required to be auth-none. These option values are the persisted value of the authentication attribute in a Tableau workbook (twb) or Tableau data source (tds) file. Starting in Tableau 2020.3, the recommendation is to standardize value to the following when possible:

Option value
None auth-none
Username auth-user
UsernameAndPassword auth-user-pass
Password auth-pass
<!-- Connection Resolver -->
<tdr class='sample'>
    <connection-resolver>
        ...
        <connection-normalizer>
            <required-attributes>
                <attribute-list>
                    ...
                    <attr>authentication</attr>
                    <attr>username</attr>
                    <attr>password</attr>
                    ...
                </attribute-list>
            </required-attributes>
        </connection-normalizer>
    </connection-resolver>
    ...
</tdr>
// Connection Builder
(function dsbuilder(attr)
{
    ...
    var authAttrValue = attr[connectionHelper.attributeAuthentication];
    if (authAttrValue == "auth-none")
        // no-op
    else if (authAttrValue == "auth-user")
        params["UID"] = attr[connectionHelper.attributeUsername];
    else if (authAttrValue == "auth-user-pass")
    {
        params["UID"] = attr[connectionHelper.attributeUsername];
        params["PWD"] = attr[connectionHelper.attributePassword];
    }

    ...
})