Create a Cloud File Connector

🕐 4 min read

The cloud file boilerplate is a connector that ingests large file-based comma-separated values (CSV) data with loadCsvData Fetch API and built-in taco file parser.

Use cases

• React
• CSV
• Built-in CSV parser
• Large file ingestion
• Paginated ingestion

Instructions

To create your connector, we recommend that you first create a sample cloud file connector from the boilerplate and edit the generated files. It’s easier to get all the files and directory structure your connector needs by just using an existing example.

To create your cloud file connector, do the following steps.

Step 1: Create a boilerplate React connector

1. Enter the following command to create the connector:

   taco create my-cloud-file-connector --boilerplate cloud-file 
   

   This creates a directory with the cloud file data boilerplate code, which is included with the toolkit.

2. Change directories to the my-cloud-file-connector directory.

   cd my-cloud-file-connector
   

3. Build the connector by entering the following command:

   taco build
   

   This command clears any previous or existing build caches, then installs the dependencies, then builds the frontend code and the backend code (handlers), then copies the connector.json file (the configuration file).

Step 2: Configure your connector’s properties

In your new cloud file connector directory, find and open the connector.json file.

{
  "name": "my-cloud-file-connector",
  "displayName": "Cloud File Sample Connector",
  "version": "1.0.0",
  "tableau-version": {
    "min": "2023.3"
  },
  "vendor": {
    "name": "vendor-name",
    "support-link": "https://vendor-name.com",
    "email": "support@vendor-name.com"
  },
  "permission": {
    "api": {
      "https://*.usgs.gov/": [
        "GET",
        "POST"
      ]
    }
  },
  "auth": {
    "type": "none"
  },
  "window": {
    "height": 800,
    "width": 600
  }
}

Make the following changes:

1. Change the general properties.

   Name	Value
   name	Your connector’s directory name
   displayName	Your connector’s name. This is the name that appears in the Tableau connectors area.
   version	Your connector’s version
   min	The earliest Tableau version your connector supports

2. Change the company properties.

   Name	Value
   vendor.name	Your company name
   vendor.support-link	Your company’s URL
   vendor.email	Your company’s email

3. Change the permissions.

   Name	Value
   permission.api	The URI for the API that the connector is allowed to access, along with the methods (POST, GET, PUT, PATCH, DELETE) that the connector is allowed to use.

4. Change the authentication type.

   Name	Value
   auth.type	Accepted values are custom, oauth, and none.

   For more information about authentication, see the Authentication section in the Considerations for Building Your Connector topic.

5. Change the HTML pane size.

   Name	Value
   window.height	The height of the connector HTML pane
   window.width	The width of the connector HTML pane

Step 3: Edit the user interface

When you open a web data connector in Tableau, the connector displays an HTML page that links to your code and to your connector’s handlers. Optionally, this page can also display a user interface (UI) for your users to select the data that they want to download.

The /app/components/ConnectorView.tsx file is the main component for the connector UI. You can modify or replace this file based on your connector UI requirements.

Step 4: Edit the connector object

The /app/components/useConnector.ts file contains a custom React hook that abstracts common connector object operations. The hook creates a connector object. A component can:

• Track the connector object state (for example, isInitializing)
• Directly invoke the functions returned from the hook to interact with connector object (for example, handleSubmit)

The following is the code in userConnector.ts file for the connector creation.

const [connector] = useState<Connector>(
    () =>
      new Connector(
        (_: Connector) => {
          Logger.info('Connector initialized.')

          setConnectorState({ ...connectorState, isInitializing: false })
        },
        (_: Connector, error: Error) => {
          Logger.error(`Connector Initialized Error: ${error.message}`)
          setConnectorState({ ...connectorState, errorMessage: error.message, isInitializing: false })
        }
      )
  )

Step 5: Update the fetcher file

If your data is complex and needs preprocessing, use the TACO Toolkit library to prepare your data. The following is the default code that the /handlers/LoadCsvDataFetcher.ts files uses to get the data:

import { Fetcher, FetchUtils } from '@tableau/taco-toolkit/handlers'

export default class LoadCsvDataFetcher extends Fetcher {
  async *fetch() {
    const csvDataUrls = [
      'https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/1.0_month.csv',
      'https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_month.csv',
    ]

    for (const url of csvDataUrls) {
      await FetchUtils.loadCsvData(url, {
        trimColumnHeader: true,
      })
    }
    yield
  }
}

Step 6: Build your connector

Enter these commands to build, pack, and run your new connector:

taco build

taco pack

taco run Desktop