Connector API Reference

In this section

• Connection Resolver *.tdr
  • connection-builder
    • JavaScript function call signature:
  • connection-properties
    • JavaScript function call signature (Recommended, added in 2019.4.1):
    • JavaScript function call signature (Deprecated):
  • connection-normalizer
  • driver-resolver
• C++ objects and methods available to your JavaScript
  • Connection Helper
  • Driver Locator
• Deprecated API
  • ConnectionNormalizer and ConnectionMatcher JavaScript files
  • SetImpersonateAttributes connection helper
  • <setImpersonateAttributes/> XML tag
  • Logging

Connection Resolver *.tdr

Defines the connection to your data source.

File extension: .tdr

See resolvers for examples.

The Connection Resolver is made up of several components:

connection-builder

Builds the ODBC ConnectString or JDBC Connection URL. For a JDBC Connection URL, we require that the connection-builder contains only non-secure attributes, such as server, port, and dbname.

Type: JavaScript

JavaScript function call signature:

Input: attr, an object of key/value pairs

{"server" : "myserver.somewhere.net"}

Return: array of formatted key=value pairs

["DRIVER={My ODBC Driver}", "Host=myserver.somewhere.net"];

connection-properties

Similar to connection-builder but is used to build the JDBC properties file. For JDBC Connection URL, we require that connection-properties contain secure attributes such as username and password.

Type: JavaScript

JavaScript function call signature (Recommended, added in 2019.4.1):

Input: attr, an object of key/value pairs

{"server" : "myserver.somewhere.net", "username" : "myusername", "password" : "mypassword"}

Return: an object of key/value pairs that will be written to the properties file(recommended and available since 2019.4.1)

["UID" : "myusername", "Host" : "myserver.somewhere.net", "PWD" : "mypassword"];

JavaScript function call signature (Deprecated):

Note: A bug in the JavaScript translation layer means that you cannot use values containing the ‘=’ character. You can mitigate this by using the preceding recommended API. This API should only be used to maintain backwards compatibility with Tableau versions older than 2019.4.1.

Input: attr, an object of key/value pairs

{"server" : "myserver.somewhere.net", "username" : "myusername", "password" : "mypassword"}

Return: an array of formatted key=value pairs that will be written to the properties file

["UID=myusername", "Host=myserver.somewhere.net", "PWD=mypassword"]

connection-normalizer

Defines the unique set of connection attributes that is used to generate a connection “key” and has important security considerations. Connections can be reused and shared within Tableau processes based on this key, so it must contain attributes whose values will be unique in a given security context. Username is a commonly used attribute that will make a unique connection for each user, for example.

Type: XML

The connection-normalizer is represented using an XML component in the connectionResolver.tdr file. An example is :

<connection-normalizer>
    <required-attributes>
        <attribute-list>
            <attr>server</attr>
            <attr>port</attr>
            <attr>dbname</attr>
            <attr>username</attr>
            <attr>password</attr>
        </attribute-list>
    </required-attributes>
</connection-normalizer>

The following table shows the most commonly used attributes in the attribute-list. You can also add custom attributes.

Attribute names

driver-resolver

Determines the driver name to use when connecting. This is only used for ODBC connections. You can specify regex or string matches for the driver name, specify driver versions (if the driver correctly returns them through the ODBC interface), and have a list of multiple drivers that can be used in order.

Note: We do not recommend using ODBC driver version constraints, unless required for your scenario. There are inconsistencies in the version values returned due to differences in the underlying operating and file systems on MacOS and Linux.

Type: XML

See resolvers for examples.

C++ objects and methods available to your JavaScript

Connection Helper

Attribute names

Functions

String FormatKeyValuePair(String key, String value);

Format the attributes as ‘key=value’. By default, some values are escaped or wrapped in curly braces to follow the ODBC standard, but you can also do it here if needed.

String GetProductName();

Returns the Tableau product name. This value should not be used for conditional logic within the connector. Available in Tableau 2022.1 and newer. Possible values are: TableauDesktop, TableauServer, TableauCloud, TableauPrep, TableauBridge, Tableau

String GetProductVersion();

Returns the Tableau version as a string in Version.MaintenanceRelease format. This value should not be used for conditional logic within the connector. Available in Tableau 2022.1 and newer. Example value: 2022.1.3

String GetPlatform();

Returns the name of the operating system Tableau is running on. Possible values are: win, mac, linux

bool MatchesConnectionAttributes(Object attr, Object inKey);

Invokes attribute matching code.

Map ParseODBCConnectString(String odbcConnectString);

Returns a map of the key value pairs defined in the odbc-connect-string-extras string.

Example:

formattedParams.push(connectionHelper.FormatKeyValuePair(key, params[key]));

params[connectionHelper.keywordODBCUsername] = attr[connectionHelper.attributeUsername];

odbcConnectStringExtrasMap = connectionHelper.ParseODBCConnectString(attr["odbc-connect-string-extras"]);

if (attr[connectionHelper.attributeTableauServerAuthMode] == connectionHelper.valueAuthModeDBImpersonate) {
     props["DelegationUID"] = attr[connectionHelper.attributeTableauServerUser];
}

Throw Tableau Exception

Normally, throwing an exception in a JavaScript component will show the user a more generic error message in the product. To have a custom error message appear in Tableau, use the following format:

return connectionHelper.ThrowTableauException("Custom Error Message");

The full error is always logged.

Driver Locator

Functions

String LocateDriver (Object attr);

Get the name of your chosen driver that was matched using the rules in your TDR file.

String LocateDriverVersion(Object attr);

Get the version number of the chosen driver as a string.

Example:

formattedParams.push(connectionHelper.FormatKeyValuePair(driverLocator.keywordDriver, driverLocator.LocateDriver(attr)));

Deprecated API

ConnectionNormalizer and ConnectionMatcher JavaScript files

The JavaScript files for connection normalizer and connection matcher are deprecated as of Tableau 2020.3. In Tableau 2021.2 support was removed and an error will occur when loading the connector. The element <script file="fileName.js"/>, which was added inside the <connection-matcher> and <connection-normalizer> element, and the <connection-matcher> element itself, are the deprecated APIs. The <connection-normalizer> element is still supported in the connectionResolver.tdr file as shown in the connection-normalizer section above.

SetImpersonateAttributes connection helper

This connection helper is deprecated as of Tableau 2020.1, since we always set impersonate attributes for all connectors. Trying to use this in a JavaScript component will throw an error when attempting to connect.

<setImpersonateAttributes/> XML tag

<setImpersonateAttributes/> xml tag is deprecated as of Tableau 2020.1, though it has not yet been removed from the XSD. Since we always set this property starting with 2020.1, this tag is redundant.

Logging

logging.Log() JavaScript function is deprecated in Tableau 2022.1 and maintainence releases starting in April 2022. Any call to this function will log message “Connector SDK logging.log() function is deprecated.” in the log file.