Community Connector API Reference

Required functions

getConfig()

Returns the user configurable options for the connector.

Request

@param {Object} request A JavaScript object containing the config request parameters.

The parameter JavaScript object will contain data with the following structure:

{
  "languageCode": string
}
Field name Type Description
languageCode string A code that represents the user's language. This code can optionally be used to return a localized version of configuration options for the user. See the complete list of supported languages and codes.
Request Example

Example of a getConfig request for a user whose language is set to Italian:

{
  "languageCode": "it"
}

Response

@return {object} A JavaScript object representing the connector configuration that should be displayed to the user.

The response contains the connector configuration with the following structure:

{
  "configParams": [
    {
      "type": string(ConfigType),
      "name": string,
      "displayName": string,
      "helpText": string,
      "placeholder": string,
      "options": [
        {
          "label": string,
          "value": string
        }
      ]
    }
  ],
  "dateRangeRequired": boolean
}
Field name Type Description
configParams[] object The user provided values required by the connector. Each item represents a user input field.
configParams[].type string (ConfigType) The type of the input field.
configParams[].name string The ID of the input field.
This should be a non-empty string with no spaces.
configParams[].displayName string The text label for the input field.
configParams[].helpText string The text to display to provide additional assistance to the user about the expected value for the field.
configParams[].placeholder string Used only when type is TEXTINPUT or TEXTAREA
Placeholder text to be used as a short hint to describe the expected value of the input field.
configParams[].options[] list Used only of type is SELECT
This provides the list of all the options.
options[].label string The label for the option.
options[].value string The value for the option.
This should be a non-empty string with no spaces or commas.
dateRangeRequired boolean If true, a date range will be provided for getData() requests. By default, the last 28 days excluding today is chosen as the date range. This must be set for data APIs that require a date range to accompany queries, and should be set if requests to data APIs can be more efficient due to limiting the date range. Defaults to false.
Response Example

The following example shows the configuration for a single line text box, a text area, a single-select, a multi-select, a checkbox and an info box:

{
  "configParams": [
    {
      "type": "TEXTINPUT",
      "name": "exampleTextInput",
      "displayName": "Single line text",
      "helpText": "Helper text for single line text",
      "placeholder": "Lorem Ipsum"
    },
    {
      "type": "TEXTAREA",
      "name": "exampleTextArea",
      "displayName": "Text area",
      "helpText": "Helper text for text area",
      "placeholder": "Lorem Ipsum"
    },
    {
      "type": "SELECT_SINGLE",
      "name": "exampleSELECT_SINGLE",
      "displayName": "Select single",
      "helpText": "Helper text for select-single",
      "options": [
        {
          "label": "Lorem foo",
          "value": "lorem"
        },
        {
          "label": "Ipsum bar",
          "value": "ipsum"
        },
        {
          "label": "Sit",
          "value": "amet"
        }
      ]
    },
    {
      "type": "SELECT_MULTIPLE",
      "name": "exampleSELECT_MULTIPLE",
      "displayName": "Select multiple",
      "helpText": "Helper text for select-multiple",
      "options": [
        {
          "label": "Lipsum",
          "value": "lipsum"
        },
        {
          "label": "Foo Bar",
          "value": "foobar"
        },
        {
          "label": "Dolor Sit",
          "value": "amet"
        }
      ]
    },
    {
      "type": "CHECKBOX",
      "name": "exampleCheckbox",
      "displayName": "This is a checkbox",
      "helpText": "Helper text for checkbox",
    },
    {
      "type": "INFO",
      "name": "exampleInfo",
      "text": "Example instructions text used in Info"
    }
  ],
  "dateRangeRequired": false
}

getSchema()

Returns the schema for the given request. This provides the information about how the connector's data is organized. For each field it includes details such as identifiers, names, data types, etc.

Request

@param {Object} request A JavaScript object containing the schema request parameters.

The parameter JavaScript object will contain data with the following structure:

{
  "configParams": object,
  "scriptParams": object
}
Field name Type Description
configParams Object A JavaScript object containing the user provided values for the config parameters defined by the connector.
scriptParams Object A JavaScript object containing information relevant to connector execution. Not used for getSchema now.
Request Example

Example of a getSchema request object:

{
  "configParams": {
    "exampleSelectMultiple": "foobar,amet",
    "exampleSelectSingle": "ipsum",
    "exampleTextInput": "Lorem Ipsum Dolor Sit Amet",
    "exampleTextArea": "NA",
    "exampleCheckbox": "true"
  },
  "scriptParams": {}
}

Response

@return {object} A JavaScript object representing the schema for the given request.

The function returns the schema with the following structure:

{
  "schema": [
    {
      object(Field)
    }
  ]
}
Field name Type Description
schema[] object(Field) The schema for the given request which includes details about each field.
Response Example
{
  "schema": [
    {
      "name": "Created",
      "label": "Date Created",
      "dataType": "STRING",
      "semantics": {
        "conceptType": "DIMENSION"
      }
    },
    {
      "name": "Amount",
      "label": "Amount (USD)",
      "dataType": "NUMBER",
       "semantics": {
        "conceptType": "METRIC",
        "isReaggregatable": true
      }
    },
    {
      "name": "Probability",
      "label": "Probability (Close rate)",
      "dataType": "NUMBER",
       "semantics": {
        "conceptType": "METRIC",
        "isReaggregatable": false
      }
    },
    {
      "name": "OpportunityName",
      "label": "Opportunity Name",
      "dataType": "STRING",
       "semantics": {
        "conceptType": "DIMENSION"
      }
    },
    {
      "name": "IsVerified",
      "label": "Verified Status",
      "dataType": "BOOLEAN",
       "semantics": {
        "conceptType": "DIMENSION"
      }
    },
    {
      "name": "Company",
      "label": "Incorporated Company Name",
      "dataType": "STRING",
       "semantics": {
        "conceptType": "DIMENSION"
      }
    }
  ]
}

getData()

Returns the tabular data for the given request.

Request

@param {Object} request A JavaScript object containing the data request parameters.

The request parameter contains user provided values and additional information that can be used to complete the data request. It has the following structure:

{
  "configParams": object,
  "scriptParams": {
    "sampleExtraction": boolean,
    "lastRefresh": string
  },
  "dateRange": {
    "startDate": string,
    "endDate": string
  },
  "fields": [
    {
      object(Field)
    }
  ]
}
Field name Type Description
configParams object A JavaScript object containing the user provided values for the config parameters defined by the connector.
scriptParams object A JavaScript object containing information relevant to connector execution.
dateRange object By default, the date range provided will be last 28 days excluding today. If a user applies a date range filter for a report then the date range provided will reflect the user selection.
When sampleExtraction is set to true, the date two days earlier than today is given as both the start and end date.
dateRange.startDate string Applies only if dateRangeRequired is set to true. The start date for filtering the data.
It will be in YYYY-MM-DD format.
dateRange.endDate string Applies only if dateRangeRequired is set to true. The end date for filtering the data.
It will be in YYYY-MM-DD format.
scriptParams.sampleExtraction boolean If value is true, the getData request is for the purpose of automatic semantic type detection. Value is omitted or false otherwise.
scriptParams.lastRefresh string This represents a timestamp that marks the time of the most recent request for a refresh of data. You should try to return data that is newer than the last refresh timestamp. You should be able to parse the value with new Date(timestampString).
fields[] object(Field) The list of fields for which data has been requested. This is typically a subset of the schema. The only Field data guaranteed to be provided for the request will be Field.name.
Request Example

The example below shows a data request that includes user provided values requestId and reportType along with the requested fields: Created, OpportunityName, Amount, and IsVerified.

{
  "configParams": {
    "multiSelectExample": "foo,bar",
    "singleSelectExample": "Lipsum",
    "singleTextExample": "Lorem Ipsum",
    "multiTextExample": "Dolor Sit Amet",
    "includeCheckExample": "true"
  },
  "dateRange": {
    "endDate": "2017-07-16",
    "startDate": "2017-06-19"
  },
  "fields": [
    {
      "name": "count"
    },
    {
      "name": "family"
    }
  ]
}

Response

@return {object} A JavaScript object that contains the schema and data for the given request.

The function returns tabular data that satisfies the given request. The schema for the tabular data is included in the response. The response is expected to have the following structure:

{
  "schema": [
    {
      object(Field)
    }
  ],
  "rows": [
    {
      "values": [
        string
      ]
    }
  ],
  "cachedData": boolean
}
Field name Type Description
schema[] object(Field) The schema for the requested field(s). The Field.name and Field.dataType are required. The order of the Field objects determines the expected order of values for each row.
rows[] object The rows of values for the requested field(s).
rows[].values[] string The values for the requested field(s).
The order of values must correspond to order of the Fields defined in schema.
cachedData boolean If true, this means the data response was from a cache. If false or omitted, this means the data response was fetched directly from the source.
Note that parameter is not currently used, you should set this value as it will become effective in an upcoming release. For now, setting this value will have no effect.
Response Example
{
  "schema": [
    {
      "name": "OpportunityName",
    },
    {
      "name": "IsVerified",
    },
    {
      "name": "Created",
    },
    {
      "name": "Amount",
    }
  ],
  "rows": [
    {
      "values": ["Interesting", true, "2017-05-23", "120453.65"]
    },
    {
      "values": ["SF", false, "2017-03-03", "362705286.92"]
    },
    {
      "values": ["Spring Sale", true, "2017-04-21", "870.12"]
    }
  ],
  "cachedData": true
}

getAuthType()

Returns the authentication method required by the connector to authorize the 3rd-party service.

Request

This function does not formally accept any arguments.

Response

@return {object} A JavaScript object that contains the AuthType indicating the authentication method used by the connector.

The function returns the AuthType with a JavaScript object with the following structure:

{
  "type": string(AuthType)
}
Field name Type Description
type string (AuthType) The value for the type of authentication.
Response Example
{
  "type": "NONE"
}

Required functions for OAuth2

isAuthValid()

Checks if the 3rd-party service credentials are valid.

Request

This function does not formally accept any arguments.

Response

@return {boolean} Returns true if the 3rd-party service credentials are valid, false otherwise. If true it is expected that calls to getData and getSchema will be authorized. If false then the user will likely be notified that auth has expired and they will be asked to reauthorize.

get3PAuthorizationUrls()

Returns the authorization URL to initiate the OAuth 2.0 flow for the 3rd-party service.

Request

This function does not formally accept any arguments.

Response

@return {string} Returns the authorization URL for the 3rd-party service. The authorization URL will be presented to the user to initiate the OAuth 2.0 flow to grant access to the 3rd-party service.

authCallback()

Handles the authorization response received from the 3rd party service as part of the OAuth 2.0 authorization process.

Request

@param {string} request A JSON encoded object representing the request data from the completion of the OAuth 2.0 flow.

The request parameter from the completion of an OAuth 2.0 flow is expected to contain data with the following structure (There are 2 representations below, one for a successful request and another for a failed request):

// Success
{
  "parameter":
    {
      "code": string
    }
}

// Error
{
  "parameter":
    {
      "error": string
    }
}
Field name Type Description
parameter object The code or error values from a successful or failed OAuth 2.0 flow. These values are can be used for further callback handling.
code string On a successful OAuth 2.0 flow this will be present and contain the value of the code query parameter from OAuth 2.0 callback request received from the 3rd-party service. This is an authorization code that can be used for further OAuth 2.0 handling.
error object On a failed OAuth 2.0 flow attempt this will be present and contain the value of the error query parameter from OAuth 2.0 callback request received from the 3rd-party service. This is an error message can be used for further OAuth 2.0 handling and notifications.

Response

@return {object} Return an HTML object that will be rendered and shown to the user. Please view the Oauth library documentation and also Apps Script HTML Service documentation for more details.

resetAuth()

Clears user credentials for the third-party service.

Request

This function does not formally accept any arguments.

Response

The response is empty.

Optional functions

isAdminUser()

This is an optional function.

This checks whether the current user is an admin user of the connector. In Data Studio this function is used to enable/disable debug features. See how you can debug your code using this function.

Request

This function does not formally accept any arguments.

Response

@return {boolean} Returns true if the current authenticated user at the time of function execution is an admin user of the connector. If the function is omitted or if it returns false, then the current user will not be considered an admin user of the connector.

Data Types

Field

Describes a specific field of a record/row as part of a schema.

Each field has the following structure:

{
  "name": string,
  "label": string,
  "dataType": string(DataType),
  "semantics": {
    "conceptType": string(ConceptType),
    "isReaggregatable": boolean
  }
}
Field name Type Description
name string The name of the field.
This will be used as a unique identifier. Only alphanumeric characters and underscores are allowed.
label string The display name for the field. This is used as a "friendly" name in the UI.
dataType string(DataType) The data type for the field.
semantics object Additional properties to provide semantic information about the field. If omitted then the host application may attempt to automatically detect semantics for the field.
semantics.conceptType string(ConceptType) Indicates whether the field is a dimension or metric.
semantics.isReaggregatable boolean true indicates that Aggregation can be applied to this field; In Data Studio Aggregation will be set to SUM by default and the user will be allowed to change the Aggregation.
false indicates Aggregation should not be applied to this field; In Data Studio Aggregation will be set to Auto by default and the user will not be able to change the Aggregation.
Default value is true.
Note: This property only affects metric fields.

ConceptType

The values for semantic concept types can be one of the following:

Enum Value Description
DIMENSION A dimension. Dimensions are data categories with values such as names, descriptions or other characteristics of a category.
METRIC A metric. Metrics measure dimension values and represent measurements such as a sum, count, ratio, etc.

DataType

The values for schema data types can be one of the following:

Enum Value Description
STRING An arbitrary string. Defined by the JSON Schema spec.
NUMBER A numeric data type in the double-precision 64-bit floating point format (IEEE 754).
BOOLEAN A boolean value, either true or false. Defined by the JSON Schema spec.

AuthType

The values for authentication method type can be one of the following:

Enum Value Description
NONE Indicates there is no authentication required for the connector.
OAUTH2 Indicates the connector uses OAuth 2.0 for authentication.

ConfigType

The values for configuration form element types can be one of the following:

Enum Value Description
TEXTINPUT The input element will be a single-line text box.
TEXTAREA The input element will be a multi-line textarea box.
SELECT_SINGLE The input element will be a dropdown for single-select options.
SELECT_MULTIPLE The input element will be a dropdown for multi-select options.
CHECKBOX The input element will be a single checkbox that can be used to capture boolean values.
INFO This is a static plain-text box that can be used to provide instructions or information to the user.