WebDataConnectorAPI

WebDataConnectorAPI:

This API Reference contains all of the functions and objects for the WDC API version 2. WDC version 1 is no longer supported.

ColumnInfo

ColumnInfo:

Represents metadata about a column in a table.

aggType

aggType: aggTypeEnum

(Optional) The default aggregation type for this column.

alias

alias: string

(Optional) The user friendly alias of this column. If this property is omitted, the column id will be used.

columnRole

columnRole: columnRoleEnum

(Optional) The default role of this column: dimension or measure.

columnType

columnType: columnTypeEnum

(Optional) The default type of this column: discrete or continuous.

dataType

dataType: dataTypeEnum

The data type of this column.

description

description: string

(Optional) A description of the column. This description is added to the metadata for the column and is saved when you save the workbook. You can view the column metadata in the Simulator.

filterable

filterable: bool

(Optional) Whether the column should be used as the join filtering column in the dependent table. For more information, see Join Filtering.

Note: This feature is only supported in version 2.2 and later of the WDC.

foreignKey

foreignKey: Object

(Optional) An object that specifies the table ID and column ID to use in join filtering to create the primary to foreign key relationship. Set this property on the column used in the dependent table (the foreign key) and point to the table ID and column ID of the primary table (the primary key). For more information, see Join Filtering.

Note: This feature is only supported in version 2.2 and later of the WDC.

For example, you might enter a foreign key object like this:

foreignKey: { "tableId": "users", "columnId": "id" }

geoRole

(Optional) The default geographic role of this column.

id

id: string

The id of this column. Column ids must be unique within a table. The id can only contain alphanumeric (a-z, A-Z, 0-9) and underscore characters (_). The id must match the regular expression: "^[a-zA-Z0-9_]\*$".

numberFormat

numberFormat: numberFormatEnum

(Optional) The default number formatting for this column.

unitsFormat

unitsFormat: unitsFormatEnum

(Optional) The default units formatting for this column.

DataDoneCallback

  • __call(): void
  • Callback function to tell Tableau that the connector has finished gathering data.

    Returns void

InitCallback

  • __call(): void
  • Callback function to tell Tableau the connector's init method has finished.

    Returns void

SchemaCallback

  • Callback function for reporting the tables this WDC contains. tables is a list of all tables in the connection and is required.

    Parameters

    Returns void

ShutdownCallback

  • __call(): void
  • Callback function to tell Tableau the connector's shutdown method has finished.

    Returns void

StandardConnection

StandardConnection:

The metadata for standard connections, or predefined joins.

Note: This feature is only supported in version 2.1 and later of the WDC.

alias

alias: string

An alias for the standard connection. This is the name of the connection that is displayed in Tableau Desktop.

tables

tables: array

Specifies the tables that you want to join. The table properties must match the properties defined in the table schema.

  • id. The table ID.
  • alias. An alias for the table.
"tables": [{
    "id": "The table id",
    "alias": "The table alias"
}, {
    "id": "The table id",
    "alias": "The table alias"
}]

joins

joins: array

An array of join objects which specifies which objects to join and with which join type. Each join object takes the following form:

"joins": [{
    "left": {
        "tableAlias": "The alias for the table",
        "columnId": "The id for the column"
    },
    "right": {
        "tableAlias": "The alias for the table",
        "columnId": "The id for the column"
    },
    "joinType": "The join type, either 'inner' or 'left'"
}]

Example

var standardConnection = {
    "alias": "Joined earthquake data",
    "tables": [{
        "id": "magPlace",
        "alias": "Magnitude and Place"
    }, {
        "id": "timeUrl",
        "alias": "Time and URL"
    }],
    "joins": [{
        "left": {
            "tableAlias": "Magnitude and Place",
            "columnId": "id"
        },
        "right": {
            "tableAlias": "Time and URL",
            "columnId": "id"
        },
        "joinType": "inner"
    }]
};

Table

Table:

Object which is used to actually append data when creating an extract.

incrementValue

incrementValue: string

If this is an incremental refresh and the table supports incremental refreshes, this property will contain the largest value from the incrementColumn in the current extract. This value will be an empty string otherwise. See Incremental Refresh for details.
 

tableInfo

tableInfo: TableInfo

The metadata about this table

appendRows

  • appendRows(rows: Array<Array<any>>): any
  • Called to actually append rows of data to the extract and is called in the getData function during the Gather Data Phase. Takes either an array of arrays or an array of objects which contain the actual rows of data for the extract. The format for these match version 1 of the API.

    Parameters

    • rows: Array<Array<any>>

    Returns any

Example

To avoid overwhelming the data pipeline, which currently has a 128MB limit per function call, you can create a while loop for the appendRows function. This is important if you are working with very large data sets. The following code uses a size variable along with the row_index to add rows of data in size increments. Each row in the table is assigned an index value, represented by the row_index value. It is a best practice to also call the reportProgress function as you add data so that Tableau can report the progress to end-users during the extract creation process. In this example, 1000 rows are added at a time. If you are working with a large data set, you might want to choose a larger size to improve performance. Each append operation needs to be under the 128MB data limit.

       var row_index = 0;
       var size = 1000;
       while (row_index < tableData.length){
            table.appendRows(tableData.slice(row_index, size + row_index));
            row_index += size;
            tableau.reportProgress("Getting row: " + row_index);
        }

TableInfo

TableInfo:

Represents metadata about a table of data

columns

columns: Array<ColumnInfo>

An array of columns that belong to this table.

alias

alias: string

(Optional) An alias for this table to be shown to the user. This alias is editable by the user and must be unique across all tables used in a join. If this property is omitted, the table id will be used.

description

description: string

(Optional) A user friendly description of the contents in this table.

id

id: string

A unique id for this particular table. The id can only contain alphanumeric (a-z, A-Z, 0-9) and underscore characters (_). The id must match the regular expression: "^[a-zA-Z0-9_]\*$".

Note: May not contain certain characters such as a hyphen.

incrementColumnId

incrementColumnId: string

(Optional) The id of the column which can be used for incremental refreshes. Must be an int, date, or datetime column. See Incremental Refresh for details.

joinOnly

joinOnly: bool

(Optional) Whether you want to make join filtering required for this table. If you set this value to true, you cannot connect to the table without first connecting to the other table. Join Filtering for details.

WebDataConnector

WebDataConnector:

This is the actual interface a WDC will be asked to implement. init and shutdown are optional and will be filled in automatically if a connector does not implement these.

getData

  • Called to create or update the data for a particular instance of this WDC. data is returned for each table in the connection. Once all data has been returned, the connector must call doneCallback to indicate that data gathering has finished.

    Parameters

    Returns void

getSchema

  • Called to retrieve the schema information for this WDC.

    Parameters

    • schemaCallback: SchemaCallback

      Called to inform Tableau about the schema.

    Returns void

init

  • Called first in each phase of the web data connector. See WDC Lifecycle and Phases for details. @param initCallback - Called to inform Tableau when the connector has finished initializing.

    Parameters

    Returns void

shutdown

  • Called at the end of each phase of the web data connector. See WDC Lifecycle and Phases for details. @param shutdownCallback - Called to inform Tableau when the connector has finished shutdown.

    Parameters

    Returns void

tableau

tableau:

The tableau object represents state and functionality of the Tableau product.

authPurpose

authPurpose: authPurposeEnum

Current context of auth. See WDC Authentication for details.
 

authType

authType: authTypeEnum

Current type of authentication for this connector.

connectionData

connectionData: String

A string that you can use to store data between phases. For example, you might store user input that you want to use in the getData phase. Note that this string is saved as plain text, so you should not use connectionData to store sensitive information. For passwords or authentication tokens, use the password property.

To store and retrieve JavaScript objects with the connectionData property, that is to serialize and deserialize objects, use JSON.stringify and JSON.parse.

connectionName

connectionName: String

Name of this connection.

locale

locale: localeEnum

Current locale, or locale with most similar language, of the web data connector user

password

password: Object

You can use this property to store a password, OAuth authentication token, or other secret. This property can be a JSON object and is not written to disk.

phase

phase: phaseEnum

Current phase of the web data connector.

platformBuildNumber

platformBuildNumber: String

The build number for Tableau Desktop.

Note: This feature is only supported in version 2.1 and later of the WDC.

For example, you might see a build number like this:

10100.16.1005.2001

platformEdition

platformEdition: String

The edition of Tableau Desktop.

Note: This feature is only supported in version 2.1 and later of the WDC.

Either pro, standard, or public.

platformOs

platformOs: String

The operating system on which Tableau Destkop is installed.

Note: This feature is only supported in version 2.1 and later of the WDC.

Either win for Windows or mac for MacOS.

platformVersion

platformVersion: String

The version of Tableau Desktop.

Note: This feature is only supported in version 2.1 and later of the WDC.

Tableau uses semantic versioning, which means that the version matches the following syntax:

major.minor.patch

For example, you might see the following version:

10.1.0

username

username: String

Username tied to data source, persisted in a .twb, .twbx, etc.

version

version: String

Current version of the Web Data Connector API

abortForAuth

  • abortForAuth(errorMessage: string): void
  • Called whenever the connector has invalid credentials and needs to reauthenticate its user. This method must be called from the init method during the gather data phase.

    Parameters

    • errorMessage: string

      message which only shows up in logs and on Tableau Server.

    Returns void

abortWithError

  • abortWithError(errorMessage: string): void
  • Throws an error within Tableau with the passed errorMessage

    Parameters

    • errorMessage: string

      message to display to the user in Tableau.

    Returns void

enableCookiePersistence

  • enableCookiePersistence(): void
  • Enables cookie persistence in the current Tableau Desktop session. Cookies generated in any WDC will be made available to all WDC connections in a given Tableau Desktop session after this function is called. Once enabled, this behavior will remain in effect until Tableau Desktop is closed. This does not have an effect on WDC extract refreshes in Tableau Server.

    Returns void

log

  • log(logMessage: string): void
  • Logs a message in the Tableau log system

    Parameters

    • logMessage: string

    Returns void

makeConnector

registerConnector

  • Registers your connector with Tableau. You call this function after you have created the connector instance and attached functions to the instance.

    Parameters

    Returns void

reportProgress

  • reportProgress(progressMessage: string): void
  • Displays a progress message to the user while an extract is being created. For example, if you switch from the Data Source pane to a sheet, a dialog appears that displays the progress message.

    Note that this progress message is intended to inform Tableau Desktop users. Tableau Server users will not see the message, and calling this method with a very high frequency could adversely affect performance.

    Note: This feature is only supported in version 2.1 and later of the WDC.

    Parameters

    • progressMessage: string

    Returns void

    Example

    In the getData function of your connector, you iterate over the rows in a table where each row has an index value assigned to a variable called row_index. You use the following code to display a progress message after every 100 rows:

    if (row_index % 100 === 0) {
    	tableau.reportProgress("Getting row: " + row_index);
    }
    

submit

  • submit(): void
  • Tells Tableau that the connector has finished the interactive phase or the authentication phase. After this method is called, Tableau proceeds to the gather data phase.

    Returns void

aggTypeEnum

aggTypeEnum:

This enum represents the default aggregation that can optionally be assigned as metadata for columns of the int and float dataType.

avg

avg:

count

count:

count_dist

count_dist:

median

median:

sum

sum:

authPurposeEnum

authPurposeEnum:

This enum represents the context in which authentication is being requested. See WDC Authentication for details.
 

enduring

enduring: Indicates that the WDC running in the context of Tableau Server.

ephemeral

ephemeral: Indicates that the WDC is running in the context of Tableau Desktop.

authTypeEnum

authTypeEnum:

This enum represents the authentication type of the web data connector. See WDC Authentication for details.
 

basic

basic:

custom

custom:

none

none:

columnRoleEnum

columnRoleEnum:

This enum represents the default role of a column.

dimension

dimension:

measure

measure:

columnTypeEnum

columnTypeEnum:

This enum represents the default type of a column.

continuous

continuous:

discrete

discrete:

dataTypeEnum

dataTypeEnum:

This Enum represents the different data types available to each column

bool

bool:

date

date:

datetime

datetime:

float

float:

geometry

geometry:

int

int:

string

string:

geographicRoleEnum

geographicRoleEnum:

This enum represents the default geographic role that can be assigned to a column.

area_code

area_code:

cbsa_msa

cbsa_msa:

city

city:

congressional_district

congressional_district:

country_region

country_region:

county

county:

state_province

state_province:

zip_code_postcode

zip_code_postcode:

localeEnum

localeEnum:

This enum represents the locale, or the locale with the most similar language, of the of the web data connector user.

america

en-us:

brazil

pt-br:

china

zh-cn:

france

fr-fr:

germany

de-de:

japan

ja-jp:

korea

ko-kr:

spain

es-es:

numberFormatEnum

numberFormatEnum:

This enum represents the default number format that can optionally be assigned as metadata for columns of the int and float dataType.

currency

currency:

number

number:

percentage

percentage:

scientific

scientific:

phaseEnum

phaseEnum:

This enum represents the different phases in which a web data connector can be run. See WDC Lifecycle and Phases for details.
 

authPhase

authPhase:

gatherDataPhase

gatherDataPhase:

interactivePhase

interactivePhase:

unitsFormatEnum

unitsFormatEnum:

This enum represents the default unit format that can optionally be assigned as metadata for columns of the int and float dataType.

billions_english

billions_english:

billions_standard

billions_standard:

millions

millions:

thousands

thousands:

Legend

  • Enumeration
  • Enumeration member
  • Interface
  • Property
  • Method

Generated using TypeDoc