wdcw

wdcw

new wdcw(config)

Constructs a new web data connector wrapper object, given a WDC wrapper configuration object.

Parameters:
Name Type Description
config wdcw~config

Declarative configuration representing your connector.
Source:
See:
Examples

Declaratively instantiate a WDC Wrapper.

var wrapper = new wdcw({
  name: 'My Web Data Connector',
  schema: function () {
    return Promise.all([
      $.getJSON('/schema/table1.json'),
      $.getJSON('/schema/table2.json')
    ]);
  }
});

Instantiate a wrapper, then chain the definition.

var wrapper = new wdcw({name: 'My Web Data Connector'});
wrapper.registerSchema(function() {
  return Promise.all([
    $.getJSON('/schema/table1.json'),
    $.getJSON('/schema/table2.json')
  ]);
});

Methods

getConnector() → {Connector}

Return the wrapped, native connector. Useful for debugging.

Source:
Returns:

The wrapped, native web data connector.

Type
Connector

registerData(tableId, dataRetrievalFunction) → {wdcw}

Register custom data retrieval logic for a particular table on the connector.

Parameters:
Name Type Description
tableId string

The table ID (as returned in your schemaFunction) associated with the data you are returning in your dataFunction.
dataRetrievalFunction wdcw~dataRetrieval

A function that encapsulates data retrieval logic for a particular table provided by your connector. @see wdcw~dataRetrieval
Source:
Returns:

Returns itself (useful for chaining).

Type
wdcw

registerPostProcess(tableId, postProcessFunction) → {wdcw}

Register custom post-processing logic for a particular table on the connector.

Parameters:
Name Type Description
tableId string

The table ID (as returned in your schemaFunction) associated with the data you are transforming or filtering in your postProcessFunction.
postProcessFunction wdcw~postProcess

A function that encapsulates data post-processing logic for a particular table provided by your connector. @see wdcw~postProcess
Source:
Returns:

Returns itself (useful for chaining).

Type
wdcw

registerSchema(schemaRetrievalFunction) → {wdcw}

Register custom schema retrieval logic on the connector.

Parameters:
Name Type Description
schemaRetrievalFunction wdcw~schemaRetrieval

A function that encapsulates schema retrieval logic for your connector.
Source:
See:
Returns:

Returns itself (useful for chaining).

Type
wdcw

registerSetup(setupFunction) → {wdcw}

Register custom initialization logic on the connector.

Parameters:
Name Type Description
setupFunction wdcw~connectorSetup

A function that encapsulates all setup logic for your connector. @see wdcw~connectorSetup
Source:
Returns:

Returns itself (useful for chaining).

Type
wdcw

registerTeardown(shutdownFunction) → {wdcw}

Register custom shutdown logic on the connector.

Parameters:
Name Type Description
shutdownFunction wdcw~connectorTeardown

A function that encapsulates all teardown logic for your connector. @see wdcw~connectorTeardown
Source:
Returns:

Returns itself (useful for chaining).

Type
wdcw

Type Definitions

config

A configuration object used to instantiate wrapped Web Data Connectors. You may choose to provide all details on this configuration object or omit them and use the various methods on the wdcw class to build your connector.

Type:
  • Object
Properties:
Name Type Attributes Description
name string

The name of your web data connector as it should appear in Tableau.
authType string <optional>

The type of authentication that your connector uses. One of:

  • none: this value is assumed if you don't provide one.
  • basic: this will cause Tableau to show a username/password connection dialogue to users in some refresh scenarios.
  • custom: this will let Tableau know to call your connector in an "auth" phase if it needs to (rather than showing the basic auth dialogue).
setup wdcw~connectorSetup <optional>

Callback method used to register custom initialization logic for your connector. If you do not provide one here, you may optionally provide one via wdcw#conectorSetup.
teardown wdcw~connectorTeardown <optional>

Callback method used to register custom shutdown logic for your connector. If you do not provide on here, you may optionally provide one via wdcw#connectorTeardown.
schema wdcw~schemaRetrieval <optional>

Callback method used to retrieve schema details for your connector. If you do not provide one here, you must provide one via wdcw#registerSchema.
tables Object <optional>

An object with as many properties as your data source provides tables. Its keys represent table IDs. Rather than declaring them here, you may wish to use the wdcw#registerData or wdcw#registerPostProcess methods.

Properties
Name Type Description
tableId Object

Here, "tableId" is just an example; it should be the actual ID used to identify a table in your connector's schema retrieval method via wdcw#schemaRetrieval. You should have as many keys here as your connector provides tables.

Properties
Name Type Attributes Description
getData wdcw~dataRetrieval

Nested under each table ID, you must provide a data retrieval method on the getData property.
postProcess wdcw~postProcess <optional>

You may optionally provide a method for post-processing, filtering, and any other data transformation needs you may have on the postProcess method.
Source:
Examples
<caption>All of the basics<caption>
wdcw({
  name: 'My Web Data Connector',
  authType: 'basic',
  schema: function () {},
  tables: {
    tableOne: {
      getData: function (lastRecordToken) {},
      postProcess: function (tableOneData) {}
    }
  }
});

Using helper methods

wdcw({name: 'My Web Data Connector'})
  .registerSchema(function () {})
  .registerData('tableOne', function (lastRecordToken) {})
  .registerPostProcess('tableOne', function (tableOneData) {});

connectorSetup(phase) → {Promise}

Should return a promise that resolves once initialization / setup logic is complete.

This:
Parameters:
Name Type Description
phase string

The phase of the Web Data Connector lifecycle that the connector is currently in. One of: auth, interactive, or gatherData.
Source:
Returns:
Type
Promise
Example

Basic auth phase example

function setupCallback(phase) {
  // If we are in the auth phase we only want to show the UI needed for auth
  if (phase === 'auth') {
    $('input, textarea, select').not('.auth-field').css('display', 'none');
  }

  return Promise.resolve();
}

connectorTeardown() → {Promise}

Should return a promise that resolves once shutdown / end-of-request logic is complete.

This:
Source:
Returns:
Type
Promise
Example
function teardownCallback() {
  // Custom shutdown function here.
  return Promise.resolve();
}

dataRetrieval(lastRecordTokennullable, tableDependencyData, appendRows) → {Promise.<Array.<Array.<any>>>|null}

Should always return a promise which resolves when data retrieval for the given table is complete. The data passed back when resolved can vary depending on your use-case, see below.

This:
Parameters:
Name Type Attributes Description
lastRecordToken string <nullable>

If this table supports incremental refreshes, the first argument will be the last value/record of this table's incrementColumnId column. If your table does not support incremental refreshes or if the execution context is not an incremental refresh, this parameter will be null.
tableDependencyData Array.<Array.<any>> | null

If you specified an array of tables that this table depends on (via the dependsOn key in this table's schema definition), then this argument will be populated with table data for each dependency. The top layer of arrays will respect the order in which you specified the dependencies in your schema, underneath which the actual table data resides. If your table does not depend on the table data of other tables, this parameter will be null.
appendRows function

In some cases (for example, if you are dealing with a very large number of records), for performance or resource usage reasons, you may wish to bypass the WDC Wrapper's data handling and write data directly to Tableau. If this fits your use-case, you may use this function to do so; it is identical to the Table.appendRows method in the native Tableau WDC API's getData method. Note that if you use this, you'll want to resolve this method with no data, otherwise your data may be duplicated.
Source:
Returns:

In most cases, this promise should resolve with data in the format exactly as expected by Tableau in the Table.appendRows method of the native Tableau WDC API. Before being written to Tableau, data resolved here will be passed directly to the post processing method you have registered with this table. If you made use of the appendRows parameter to write data to Tableau directly, you should return NULL here so that the WDC Wrapper does not do any additional data writing to Tableau.

Type
Promise.<Array.<Array.<any>>> | null
Examples

Simple data retrieval

function dataCallbackForSomeTable() {
  var connector = this,
      filterVal = connector.getConnectionData().filter;

  return $.when($.getJSON('/path/to/resource.json?filter=' + filterVal));
}

Incremental refresh

function dataCallbackForSomeTable(lastRecordToken) {
  return $.when($.getJSON('/path/to/resource.json?afterRecord=' + lastRecordToken));
}

Data retrieval for a table that depends on another

function dataCallbackForSomeTable(lastRecordToken, tableDependencyData) {
  var keysFromFirstTable = [];

  // Aggregate some foreign key values from the dependency.
  tableDependencyData[0].forEach(function (row) {
    keysFromFirstTable = keysFromFirstTable.concat(row.other_ids);
  });

  // Retrieve data based on those keys.
  return $.when($.getJSON('/path/to/resource.json?keysIn=' + keysFromFirstTable.join(',')));
}

For extremely large data sets

function dataCallbackForSomeTable(lastRecordToken, tableDependencyData, appendRows) {
  var allRowsLoaded = [],
      i;

  // Iterate through some huge amount of data.
  for (i=0; i < 10000; i++) {
    // Keep track of when each AJAX request completes.
    allRowsLoaded[i] = $.getJSON('/path/to/resource.json?page=' + i, function (response) {
      // As soon as we have the data, write it directly to Tableau.
      appendRows(response.data);
    });
  }

  // Resolves a value-less "promise" once all page deferreds are resolved.
  return $.when(allRowsLoaded);
}

postProcess(tableData) → {Promise.<Array.<Array.<any>>>|null}

Function called once all data for a given table has been retrieved. Can be used to transform, filter, or append data for the given table. Should return a promise that resolves to data in the format exactly as expected by Tableau in the Table.appendRows method of the native Tableau WDC API.

This:
Parameters:
Name Type Description
tableData Array.<Array.<any>> | null

Contains data as resolved by your table's corresponding dataRetrieval method. In some exotic use-cases, you may wish for your dataRetrieval to resolve to "raw" data in a format not expected by Tableau, but then to process and re-shape the data here into the format expected by Tableau. This would allow any tables you've declared that depend on this table to base their data retrieval on the raw data while Tableau gets the properly formatted version.
Source:
Returns:

This promise should resolve with data in the format exactly as expected by Tableau in the Table.appendRows method of the native Tableau WDC API.

Type
Promise.<Array.<Array.<any>>> | null
Examples

Simple data filtering

function postProcessCallback(data) {
  var transformedData = [];

  // Only write odd-indexed row data to Tableau.
  data.forEach(function (row, index) {
    if (index % 2) {
      transformedData.push(row);
    }
  });

  return Promise.resolve(transformedData);
}

Reverse your data

function postProcessCallback(data) {
  return Promise.resolve(data.reverse());
}

schemaRetrieval() → {Promise.<Array.TableInfo>}

Should return a promise to an array of native Tableau TableInfo objects.

This:
Source:
Returns:
Type
Promise.<Array.TableInfo>
Examples

Simple, static schema declaration.

function schemaCallback() {
  return Promise.resolve([{
    "defaultAlias": "Table Name",
    "description": "Description of table.",
    "id": "tablename",
    "columns": [
      // Columns here...
    ]
  }]);
}

Load schema from JSON asynchronously.

function schemaCallback() {
  return Promise.all([
    $.getJSON('/schema/for/table-name.json'),
    $.getJSON('/schema/for/another-table.json')
  ]);
}