Build a Community Connector

The steps to building a Community Connector are:

  1. Create a new Apps Script project.
  2. Write the connector code.
  3. Complete the project manifest.

Create a new project in Apps Script

Visit Google Apps Script to create a new project. Apps Script will create a default script for you. Feel free to remove the myFunction function and rename the project. (Learn more about Apps Script)

Write the connector code

Every connector is required to have a specific set of functions defined. The hosting application (e.g. Data Studio) will execute these functions. Your connector is expected to handle incoming requests and respond as described in the Community Connector API reference. If you face issues while developing your code, read the debugging guide for help.

Define configuration via getConfig()

The getConfig() function is called to get the configuration for the connector, including the user provided values that your connector requires. See getConfig() reference for details.

Based on the response provided by getConfig(), Data Studio will render the connector configuration screen. The configuration elements supported are listed in ConfigType reference.

If your data source requires date as a parameter, you should set dateRangeRequired to true in getConfig() response. If your data source does not require date as a parameter, you can omit this.

The following is an example of a connector that requires the user to enter a ZIP code. A single input field is defined in the getConfig() function:

function getConfig(request) {
  var config = {
    configParams: [
      {
        name: 'ZipCode',
        displayName: 'ZIP Code',
        helpText: 'Enter the ZIP Code for which you would like to retrieve the weather forecast.',
        placeholder: '94043'
      }
    ]
  };
  return config;
}

Define the data schema with getSchema()

This function is called to get the schema for the given request. Any configuration parameters defined by the getConfig() function will be provided in the request argument. See getSchema() reference for details.

Depending on your connector's data source and the configuration provided by the user, the schema may be fixed or you may have to dynamically provide this at request time.

For example, if a connector is fetching report data based on a Report ID, the data returned for that report and hence the schema may not be known beforehand. In this case getSchema() may require a data fetch and the schema will have to be calculated.

Two important notes regarding getSchema:

  • For each configParam item, the user provided values are returned as string. That means for SELECT_MULTIPLE elements, the return value would be a string with comma separated values. For CHECKBOX elements, the return value would also be a string: "true" or "false".
  • Only three dataTypes are supported: STRING, NUMBER, and BOOLEAN. However, dataTypes are different from semantic types. Semantic types are visible in the fields selection screen and are derived using the automatic semantic type detection process. Therefore, you should set fields like date or geolocation to dataType STRING and then rely on semantic detection. See Data types and semantic types for details.

The example below shows a fixed schema and the getSchema method for weather information:

var fixedSchema = [
  {
    name: 'CityName',
    label: 'City',
    dataType: 'STRING',
    semantics: {
      conceptType: 'DIMENSION'
    }
  },
  {
    name: 'ForecastTime',
    label: 'Time',
    dataType: 'STRING',
    semantics: {
      conceptType: 'DIMENSION'
    }
  },
  {
    name: 'MaxTemp',
    label: 'Max Temp (C)',
    dataType: 'NUMBER',
    semantics: {
      conceptType: 'METRIC',
      isReaggregatable: false
    }
  },
  {
    name: 'MinTemp',
    label: 'Min Temp (C)',
    dataType: 'NUMBER',
    semantics: {
      conceptType: 'METRIC',
      isReaggregatable: false
    }
  },
  {
    name: 'RainAmount',
    label: 'Rain (mm)',
    dataType: 'NUMBER',
    semantics: {
      conceptType: 'METRIC',
      isReaggregatable: true
    }
  }
];

function getSchema(request) {
  return {schema: fixedSchema};
}

Fetch and return data with getData()

This function is called to get data for the given request. Any configuration parameters defined by the getConfig() function will be provided in the request argument. See getData() reference for details.

The following parameters from the getData() request require additional attention:

  • sampleExtraction
    If sampleExtraction is true, then the request is for the automatic semantic type detection process. Rather than returning the entire data set, you can choose to return a subset, or first n number of records, or predefined values for each fields. This helps with API rate limits and also makes the semantic detection process faster. However, you can choose not to handle sampleExtraction separately and let semantic detection use the entire data set. Note that in this scenario, your data set will get queried at least twice.

  • lastRefresh
    lastRefresh represents a timestamp that marks the time of the most recent request for a refresh of data. You should be able to parse the value with new Date(timestampString). If you are using Apps Script Cache Service or any other caching method, the lastRefresh timestamp can help you to determine whether to make a new fetch request to the data source or serve data from the cache.

  • dateRange
    If dateRangeRequired is set to true in getConfig(), each getData() call will contain the selected date range in the request. See Working with Date Ranges for more details.

The following example fetches data based on the incoming request and returns the weather forecast data:

function getData(request) {
  // Craft URL to fetch weather forecast data using OpenWeatherMap API.
  var url = [
    'http://api.openweathermap.org/data/2.5/forecast/daily?units=metric&cnt=16&appid=',
    API_KEY,
    '&zip=',
    request.configParams.ZipCode];

  // Fetch the data.
  // By default URL fetch will throw an exception if the response code indicates failure.
  var response = UrlFetchApp.fetch(url.join(''));
  var forecast = JSON.parse(response.getContentText());

  // Prepare the schema for the fields requested.
  var dataSchema = [];
  request.fields.forEach(function(field) {
    for (var i=0; i < fixedSchema.length; i++) {
      if (fixedSchema[i].name == field.name) {
        dataSchema.push(fixedSchema[i]);
        break;
      }
    }
  });

  // Prepare the tabular data.
  var data = [];
  forecast.list.forEach(function(day) {
    var values = [];
    // Provide values in the order defined by the schema.
    dataSchema.forEach(function(field) {
      switch(field.name) {
        case 'CityName':
          values.push(forecast.city.name);
          break;
        case 'ForecastTime':
          var dayTime = new Date(day.dt*1000);
          values.push(
            dayTime.toISOString().slice(0,10).replace(/-/g,"") +
            (dayTime.getHours()<10?'0':'') + dayTime.getHours()
          );
          break;
        case 'MaxTemp':
          values.push(day.temp.max);
          break;
        case 'MinTemp':
          values.push(day.temp.min);
          break;
        case 'RainAmount':
          values.push(day.rain ? day.rain : 0);
          break;
        default:
          values.push('');
      }
    });
    data.push({
      values: values
    });
  });

  return {
    schema: dataSchema,
    rows: data
  };
}

Define authentication type in getAuthType()

This function is called to identify the authentication method used for the 3rd-party service. See getAuthType() reference for details. Currently supported authentication methods are listed in AuthType reference.

For example, the following connector does not require authentication:

function getAuthType() {
  var response = {
    "type": "NONE"
  };
  return response;
}

If your data source requires OAuth 2.0 authentication, view the OAuth 2.0 authentication guide and add the additional required functions to your connector.

Complete the project manifest

The manifest file contains information about your Community Connector that is required to deploy and use your connector in Data Studio.

To edit the manifest file in the Apps Script development environment, click on the View menu and click Show manifest file. This will create a new appsscript.json manifest file.

For details on Data Studio manifest, see the reference manifest reference.

Open Source Community Connectors

You can explore Open Source Community Connectors for additional example code. The examples highlight various use cases and best practices for Community Connector development.

Next steps

The next step will be to deploy your Community Connector.