Connection Dialog v2

IMPORTANT: This feature is available only in Tableau 2020.3 or later. For compatibility with older versions, use Connection Dialog v1 (documentation found here).

Connection Dialog v2 is a new feature that enables a more fully data-driven connection dialog for plugin connectors. Additionally, it provides some control over the metadata hierarchy elements–Database, Schema, and Table–both in the connection dialog and in the schema viewer, which the user sees after the connection is established.

In this section

• How to Use Connection Dialog v2
• The Connection Fields File
  • XML Elements
    • <connection-fields>
    • <field>
    • <validation-rule>
    • <boolean-options>
    • <false-value>
    • <true-value>
    • <selection-group>
    • <option>
    • <conditions>
    • <condition>
  • Connection Field Platform Integration
    • Endpoint
    • SSL
    • Authentication
    • Vendor Defined
  • Example 1 - A Non-Editable Field
  • Example 2 - Conditional Display of Fields
  • Example 3 - Boolean Field
• The Connection Metadata File
  • XML Elements
    • <connection-metadata>
    • <database>
    • <field>
    • <schema>
    • <table>
  • Example

How to Use Connection Dialog v2

To use Connection Dialog v2, in the manifest replace <connection-dialog> with <connection-fields>, shown in the following example. The connector will fail to load if both elements appear in the manifest.

If you want to modify metadata hierarchy behavior you can add to the manifest a <connection-metadata> element, which is also shown in the following example.

  manifest.xml

  <?xml version='1.0' encoding='utf-8' ?>

  <connector-plugin class=...>
    ...
    <connection-fields   file='connection-fields.xml'/>    <!-- use this instead of connection-dialog -->
    <connection-metadata file='connection-metadata.xml'/>  <!-- add this to modify metadata hierarchy behavior -->
    <connection-resolver file="connectionResolver.tdr"/>
    <dialect file='dialect.tdd'/>
  </connector-plugin>

The Connection Fields File

The Connection Fields file dictates the content and behavior of Connection Dialog as seen by the user. It also specifies the names of the connection attributes that will be available, along with the values specified by the user, in the ConnectionBuilder().

The Connection Fields file (XSD) is identified in the manifest using the <connection-fields> element. Here we discuss the structure of this file.

To avoid confusion, in the following we use the term “field” in place of “connection attribute,” and use the generic term “attribute” to mean an XML element attribute.

XML Elements

<connection-fields>

This is the parent element for fields.

<field>

Each connection attribute is represented by a field element in the XML. The field element has the following XML attributes.

<validation-rule>

An optional child of field, validation-rule lets you specify a regular expression for validating the user input. It has the following XML attributes.

<boolean-options>

A required child of field when value-type is boolean, this is the container element for the two boolean options. It has no XML attributes.

<false-value>

A required child of boolean-options when value-type is boolean. This is the value to send to ConnectionBuilder() when the user does not check the box.

<true-value>

A required child of boolean-options when value-type is boolean. This is the value to send to ConnectionBuilder() when the user checks the box.

<selection-group>

A required child of field when value-type is option. This is the container element for the options that will appear in the dropdown. It has no XML attributes.

Multiple selection-group elements can be used; see <conditions>.

<option>

A child of selection-group, this represents one entry in the dropdown. It has the following XML attributes.

<conditions>

An optional child of field or selection group, this is used for conditional display. It specifies whether the field or selection group should be visible in the dialog based on the values the user has specified for other fields.

Multiple condition elements can be used, and will be OR’d. That is, the field or selection group will be visible when any one or more of the <condition> elements is matched. Hence, this is a container element for the condition elements. It has no XML attributes.

The connector will not load if there are circular references.

<condition>

Connection Field Platform Integration

As referenced above in the <field> element section, some name attribute values describe platform functionality. It is important that if the desired connector functionality matches any of the descriptions below then the names and values below must be used.

If the field functionality does not match any of the descriptions below see ‘Vendor Defined’ section.

For each <field> element used its name attribute value is required to be listed in the <attribute-list> section of the .tdr file as well. See connection-normalizer for more details.

Additionally there are a set of reserved name attribute values not documented at this time. Recommendations, documentation, and enforcement coming soon.

Endpoint

The endpoint attributes describe the unique parameters of a connection. Many connections provide additional field names and values not defined by the platform. server is a required attribute and the packager will give warning if it is not present in connection-fields.xml and connection-resolver.tdr files.

The connection field names below should specify the endpoint category.

SSL

The SSL requirements of the connection. No platform functionality is provided at this time, but field name and values are reserved based on historical usage. If used, the value is generally passed to driver via ODBC connection string or JDBC properties.

The connection field names below can specify the endpoint, ssl, or general category depending on dialog layout preference.

Authentication

The authentication attributes control how and when a user is prompted to enter data source credentials. authentication is a required attribute and the packager will give warning if it is not present in connection-fields.xml and connection-resolver.tdr files. The primary scenarios where authentication occurs:

• Creating a connection with the connection dialog
• Opening a workbook and reconnecting to the data source
• Publishing a workbook or data source to Tableau Server

The connection field names below should specify the authentication category.

Vendor Defined

The vendor defined attributes are unique to an individual connector and do not imply platform functionality. They are pass-through to the connection normalizer, connection builder and properties builder.

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.

Example 1 - A Non-Editable Field

The image shows the Connection Dialog produced using the Connection Fields file below. The username and password fields are required and don’t have default-values, so the Sign In button will not be enabled until the user provides values for them.

The field “authentication” is non-editable and so will not be visible in the connection dialog, but its default value of “auth-user-pass” will be available in ConnectionBuilder() to add to the connection string.

<?xml version="1.0" encoding="utf-8"?>

<connection-fields>

  <field name="server" label="Server" category="endpoint" value-type="string">
    <validation-rule reg-exp="^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-]*[A-Za-z0-9])$"/>
  </field>

  <field name="port" label="Port" category="endpoint" value-type="string" default-value="5432"/>

  <field name="authentication" label="Authentication" category="authentication" value-type="string" editable="false" default-value="auth-user-pass" />

  <field name="username" label="Username" category="authentication" value-type="string" />

  <field name="password" label="Password" category="authentication" value-type="string" secure="true" />

</connection-fields>

Example 2 - Conditional Display of Fields

The images show the Connection Dialog produced using the Connection Fields file below. The left side shows the dialog as it is initially displayed, after the user enters a Server name. Note that the default Authentication option is No Authentication, and the Sign In button is enabled. If the user clicks Sign In at this point, in ConnectionBuilder() the field “authentication” will have value “auth-none”. The right side shows what it changes to when the user selects Authentication Username and Password. If the user enters a username and password then clicks Sign In, in ConnectionBuilder() the field “authentication” will have value “auth-user-pass”.

<?xml version="1.0" encoding="utf-8"?>

<connection-fields>

  <field name="server" label="Server" category="endpoint" value-type="string">
    <validation-rule reg-exp="^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-]*[A-Za-z0-9])$"/>
  </field>

  <field name="port" label="Port" category="endpoint" value-type="string" default-value="5432"/>

  <field name="authentication" label="Authentication" category="authentication" value-type="selection" >
    <selection-group>
      <option value="auth-none" label="No Authentication"/>
      <option value="auth-user" label="Username"/>
      <option value="auth-user-pass" label="Username and Password"/>
    </selection-group>
  </field>

  <field name="username" label="Username" category="authentication" value-type="string">
    <conditions>
      <condition field="authentication" value="auth-user"/>
      <condition field="authentication" value="auth-user-pass"/>
    </conditions>
  </field>

  <field name="password" label="Password" category="authentication" value-type="string" secure="true">
    <conditions>
      <condition field="authentication" value="auth-user-pass"/>
    </conditions>
  </field>

</connection-fields>

Example 3 - Boolean Field

This example shows how to add a checkbox to the dialog. For sslmode custom boolean values are required to be defined, following ‘Connection Field Platform Integration’ section below. The default-value matches false-value, ensuring the checkbox is unchecked by default. Within the ConnectionBuilder() the field “sslmode” will only have value “” or “require”.

<?xml version="1.0" encoding="utf-8"?>

<connection-fields>
  ...

  <field name="sslmode" label="Require SSL" value-type="boolean" category="general" default-value="" >
    <boolean-options>
      <false-value value="" />
      <true-value value="require" />
    </boolean-options>
  </field>

</connection-fields>

The Connection Metadata File

The Connection Metadata file provides some limited control over the metadata hierarchy elements Database, Schema, and Table. For example, it can be used to:

• provide a default value for Database on the connection dialog, and
• suppress the Database, Schema, or Table selectors from the schema viewer, which the user sees after the connection is established.

If you don’t provide a Connection Metadata file, then by default all three selectors will be shown.

The Connection Metadata file (XSD) is the one named in the manifest in the <connection-metadata> element. Here we discuss the structure of this file.

XML Elements

<connection-metadata>

This is the parent element for the metadata hierarchy elements.

<database>

An optional child of <connection-metadata>, this controls whether the Database selector is shown in the connection dialog and the schema viewer. If it is not present, Database does not appear. It has the following XML attributes.

<field>

An optional child of <database>, this indicates whether the user must provide a value for Database, and a default value for it. It has the following XML attributes.

<schema>

An optional child of <connection-metadata>, this controls whether the Schema selector is shown in the schema viewer. If it is not present, Schema does not appear. It has the following XML attributes.

<table>

An optional child of <connection-metadata>, this controls whether the Table selector is shown in the schema viewer. If it is not present, Table does not appear. It has the following XML attributes.

Example

The Connection Metadata file below matches the default–that is, what you get if you don’t reference the file in the manifest at all–except that it provides a default value of ‘TestV1’ for Database.

<?xml version="1.0" encoding="utf-8"?>

<connection-metadata>
  <database enabled='true' label='Database'>
    <field optional='true' default-value='TestV1' />
  </database>
  <schema enabled='true' label="Schema" />
  <table enabled='true' label="Table" />
</connection-metadata>

The left side image below shows what the Schema Viewer will look like with this Connection Metadata file. The right side shows what it will look like if you remove the <schema> element from the file.