## 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 contains 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](https://support.google.com/googleplay/android-developer/table/4419860). |
| configParams | object | Present if the previous call to `getConfig()` had `.setIsSteppedConfig(true)`. An object containing the user-provided configuration values so far. |

##### Request Example

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

    {
      languageCode: "it"
    }

#### Response

### Data Studio Service

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

###### Example

    function getConfig(request) {
      var cc = DataStudioApp.createCommunityConnector();
      var config = cc.getConfig();

      config
          .newTextInput()
          .setId('exampleTextInput')
          .setName('Single line text')
          .setHelpText('Helper text for single line text')
          .setPlaceholder('Lorem Ipsum');

      config
          .newTextArea()
          .setId('exampleTextArea')
          .setName('Text area')
          .setHelpText('Helper text for text area')
          .setPlaceholder('Lorem Ipsum');

      config
          .newSelectSingle()
          .setId('exampleSelectSingle')
          .setName('Select single')
          .setHelpText('Helper text for select single')
          .setAllowOverride(true)
          .addOption(config.newOptionBuilder().setLabel('Lorum foo').setValue('lorem'))
          .addOption(config.newOptionBuilder().setLabel('Ipsum Bar').setValue('ipsum'))
          .addOption(config.newOptionBuilder().setLabel('Sit').setValue('amet'));

      config
          .newSelectMultiple()
          .setId('exampleSelectMultiple')
          .setName('Select multiple')
          .setHelpText('Helper text for select multiple')
          .addOption(config.newOptionBuilder().setLabel('Lorum foo').setValue('lorem'))
          .addOption(config.newOptionBuilder().setLabel('Ipsum Bar').setValue('ipsum'))
          .addOption(config.newOptionBuilder().setLabel('Sit').setValue('amet'));

      config
          .newCheckbox()
          .setId('exampleCheckbox')
          .setName('This is a checkbox')
          .setHelpText('Helper text for checkbox');

      config
          .newInfo()
          .setId('exampleInfo')
          .setText('Examle instructions text used in Info')

      config.setDateRangeRequired(true);
      config.setIsSteppedConfig(false);

      return config.build();
    }

### Legacy

`@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,
            isDynamic: boolean,
            parameterControl: {
              allowOverride: boolean
            },
            options: [
              {
                label: string,
                value: string
              }
            ]
          }
        ],
        dateRangeRequired: boolean,
        isSteppedConfig: boolean
      }

<br />

| Field name | Type | Description |
|---|---|---|
| `configParams[]` | `object` | The user provided values required by the connector. Each item represents a user input field. |
| `configParams[].type` | `string (https://developers.google.com/data-studio/connector/reference#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[].isDynamic` | `boolean` | Whether or not this field is used to dynamically populate later configuration entries. Defaults to `false` |
| `configParams[].parameterControl.allowOverride` | `boolean` | Enables overriding for the parameter. If set to `true`, data source creators can enable this for report editors Default value for `allowOverride` is `false`. If you do not want to enable overriding for a parameter, you can omit the `allowOverride` property. |
| `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 is 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`. |
| `isSteppedConfig` | `boolean` | If `true`, Data Studio will prompt the user to answer the current set of configuration questions, then return those answered questions to subsequent calls to `getConfig()`. If `false` (default), The user will be able to click connect and continue to the Schema page. |

<br />

<br />

###### Response Example

<br />

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. The
single-select value can be overridden in reports.

      {
        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",
            parameterControl: {
              allowOverride: true
            },
            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 contains data with the following structure:

    {
      "configParams": object
    }

| Field Name | Type | Description |
|---|---|---|
| `configParams` | `Object` | A JavaScript object containing the user provided values for the config parameters defined by the connector. |

> [!NOTE]
> **Note:** `SELECT_MULTIPLE` values are a comma separated string. For example, If `foo` and `bar` are selected, the value will be `"foo,bar"`. `CHECKBOX` values are returned as a [truthy value](https://developer.mozilla.org/en-US/docs/Glossary/Truthy).

##### Request Example

Example of a `getSchema` request object:

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

#### Response

### Data Studio Service

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

###### Example

    function getSchema(request) {
      var cc = DataStudioApp.createCommunityConnector();
      var fields = cc.getFields();
      var types = cc.FieldType;

      var created = fields.newDimension()
          .setId('Created')
          .setName('Date Created')
          .setDescription('The date that this was created')
          .setType(types.YEAR_MONTH_DAY)
          .setGroup('Date');

      var amount = fields.newMetric()
          .setId('Amount')
          .setName('Amount (USD)')
          .setDescription('The cost in US dollars')
          .setType(types.CURRENCY_USD)
          .setIsHidden(true);

      var amountper = fields.newMetric()
          .setId('AmountPer')
          .setName('Amount Per Dimension')
          .setDescription('The summed cost')
          .setType(types.CURRENCY_USD)
          .setGroup('Money')
          .setFormula('sum($Amount)');

      var probability = fields.newMetric()
          .setId('Probability')
          .setName('Probability (Close rate)')
          .setDescription('The probability that a store closes')
          .setType(types.PERCENT);

      var opportunityname = fields.newDimension()
          .setId('OpportunityName')
          .setName('Opportunity Name')
          .setDescription('The name of the opportunity')
          .setType(types.TEXT);

      var isverified = fields.newDimension()
          .setId('IsVerified')
          .setName('Verified Status')
          .setDescription('Whether or not the store is verified')
          .setType(types.BOOLEAN);

      var company = fields.newDimension()
          .setId('Company')
          .setName('Incorporated Company Name')
          .setDescription('The name of the company the store belongs to')
          .setType(types.TEXT);

      fields.setDefaultMetric(amountper.getId());
      fields.setDefaultDimension(created.getId());

      return { 'schema': fields.build() };
    }

### BigQuery

`@return {object}` A JavaScript object representing the BigQuery query
configuration.

###### Example

    var bqTypes = DataStudioApp.createCommunityConnector().BigQueryParameterType;
    var configuration = DataStudioApp.createCommunityConnector().newBigQueryConfig()
        .setBillingProjectId('billingProjectId')
        .setQuery('myQueryString')
        .setUseStandardSql(true)
        .setAccessToken('myAccessToken')
        .addQueryParameter('myUrlParameterName', bqTypes.STRING, 'myUrlParameterValue')
        .build();

### Legacy

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

The function returns the schema with the following structure:

      {
        "schema": [
          {
            object(Field)
          }
        ]
      }

<br />

| Field name | Type | Description |
|---|---|---|
| `schema[]` | `object(https://developers.google.com/data-studio/connector/reference#field)` | The schema for the given request which includes details about each field. |

<br />

<br />

###### Response Example

<br />

      {
        "schema": [
          {
            "name": "Created",
            "label": "Date Created",
            "description": "The date that this was created",
            "dataType": "STRING",
            "group": "Date",
            "isDefault": true,
            "semantics": {
              "conceptType": "DIMENSION",
              "semanticGroup": "DATE_AND_TIME",
              "semanticType": "YEAR_MONTH_DAY",
              "isReaggregatable": false
            }
          },
          {
            "name": "Amount",
            "label": "Amount (USD)",
            "description": "The cost in US dollars",
            "dataType": "NUMBER",
            "isHidden": true,
            "semantics": {
              "conceptType": "METRIC",
              "semanticGroup": "CURRENCY",
              "semanticType": "CURRENCY_USD",
            }
          },
          {
            "name": "AmountPer",
            "label": "Amount Per Dimension",
            "description": "The summed cost",
            "dataType": "NUMBER",
            "group": "Money",
            "formula": "sum(Amount)",
            "isDefault": true,
            "semantics": {
              "conceptType": "METRIC",
              "semanticGroup": "CURRENCY",
              "semanticType": "CURRENCY_USD",
              "isReaggregatable": true
            }
          },
          {
            "name": "Probability",
            "label": "Probability (Close rate)",
            "description": "The probability that a store closes",
            "dataType": "NUMBER",
            "semantics": {
              "conceptType": "METRIC",
              "semanticGroup": "NUMERIC",
              "semanticType": "PERCENT",
              "isReaggregatable": false
            }
          },
          {
            "name": "OpportunityName",
            "label": "Opportunity Name",
            "description": "The name of the opportunity",
            "dataType": "STRING",
            "semantics": {
              "conceptType": "DIMENSION",
              "semanticType": "TEXT",
              "isReaggregatable": false
            }
          },
          {
            "name": "IsVerified",
            "label": "Verified Status",
            "description": "Whether or not the store is verified",
            "dataType": "BOOLEAN",
            "semantics": {
              "conceptType": "DIMENSION",
              "semanticType": "BOOLEAN",
              "isReaggregatable": false
            }
          },
          {
            "name": "Company",
            "label": "Incorporated Company Name",
            "description": "The name of the company the store belongs to",
            "dataType": "STRING",
            "semantics": {
              "conceptType": "DIMENSION",
              "semanticType": "TEXT",
              "isReaggregatable": false
            }
          }
        ]
      }

### getData()

Returns the tabular data for the given request.

> [!NOTE]
> **Note:** `getData()` can return at most 1 million rows/records.

#### 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": [
        {
          "name": string
        }
      ],
      "dimensionsFilters": [
        [{
          "fieldName": string,
          "values": string[],
          "type": DimensionsFilterType,
          "operator": Operator
        }]
      ]
    }

| Name | Type | Description |
|---|---|---|
| `configParams` | `object` | An object containing the user provided values for the config parameters defined by the connector. |
| `scriptParams` | [ScriptParams](https://developers.google.com/data-studio/connector/reference#scriptparams) | An object containing information relevant to connector execution |
| `dateRange` | [DateRange](https://developers.google.com/data-studio/connector/reference#dateRange) | By default, the date range provided will be the 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. |
| `fields[].name` | `string` | The names of the requested fields. |
| `fields[].forFilterOnly` | `boolean` | Marks a field only used for filtering the request. Don't return the field if your connector applies [filters](https://developers.google.com/data-studio/connector/filters). |
| `dimensionsFilters` | [DimensionsFilters](https://developers.google.com/data-studio/connector/reference#dimensionsfilters) | A nested array of the user selected filters. The innermost arrays should be `OR`ed together, the outermost arrays should be `AND`ed together. |

**dateRange**

| Name | Type | Description |
|---|---|---|
| `startDate` | `string` | The start date for filtering the data. Applies only if [dateRangeRequired](https://developers.google.com/data-studio/connector/reference#getconfig) is set to `true`. It will be in `YYYY-MM-DD` format. |
| `endDate` | `string` | The end date for filtering the data. Applies only [dateRangeRequired](https://developers.google.com/data-studio/connector/reference#getconfig) is set to `true`. It will be in`YYYY-MM-DD` format. |

**scriptParams**

| Name | Type | Description |
|---|---|---|
| `sampleExtraction` | `boolean` | If `true`, the `getData()` request is for [automatic semantic type detection](https://developers.google.com/data-studio/connector/semantics#semantic-type-detection). |
| `lastRefresh` | `string` | A timestamp that marks the most recent request for a refresh of data. |

**dimensionsFilters**

| name | type | description |
|---|---|---|
| `fieldName` | `string` | The name of the field to be filtered |
| `values` | `string[]` | An array of values to use for the operator. |
| `type` | `"INCLUDE" | "EXCLUDE"` | Whether data matching this filter should be included or excluded from the `getData()` response. |
| `operator` | [FilterOperator](https://developers.google.com/data-studio/connector/reference#filteroperator) | The operator to apply |

> [!NOTE]
> **Note:** If more than 20 fields are in the request, then multiple getData requests will be sent. The requests will be grouped by 20 fields at a time.

##### Request Example

> [!NOTE]
> **Note:** Field names correspond to the names provided by [getSchema()](https://developers.google.com/data-studio/connector/reference#getschema). Requests for data will often include a subset of fields from the schema.

    {
      "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

### Default

`@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
            ]
          }
        ]
      }

| Name | Type | Description |
|---|---|---|
| `schema` | [Field](https://developers.google.com/data-studio/connector/reference#getdatafield)\[\] | The schema for the requested field(s). `field.name` and `field.dataType` are required. The order of the `field` object should match the order of the values for each row. |
| `rows[].values[]` | `string` \| `number` \| `boolean` | The values for the requested field(s). The order of values must correspond to the order of the `Fields` defined in the `schema` |
| `filtersApplied` | `boolean` | Set to true if all filters were successfully applied, false otherwise. |

**Field**

| Name | Type | Description |
|---|---|---|
| `name` | `string` | The name of the field. |
| `dataType` | [DataType](https://developers.google.com/data-studio/connector/reference#datatype) | The type of the field. |

###### Example

> [!NOTE]
> **Note:** In the response, order of values in rows must match the order of fields in the schema.

    {
      "schema": [
        {
          "name": "OpportunityName",
          "dataType": "STRING"
        },
        {
          "name": "IsVerified",
          "dataType": "BOOLEAN"
        },
        {
          "name": "Created",
          "dataType": "STRING"
        },
        {
          "name": "Amount",
          "dataType": "NUMBER"
        }
      ],
      "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"]
        }
      ],
      "filtersApplied": false
    }

### BigQuery

`@return {object}` A JavaScript object representing the BigQuery query
configuration.

###### Example

    var bqTypes = DataStudioApp.createCommunityConnector().BigQueryParameterType;
    var configuration = DataStudioApp.createCommunityConnector().newBigQueryConfig()
        .setBillingProjectId('billingProjectId')
        .setQuery('myQueryString')
        .setUseStandardSql(true)
        .setAccessToken('myAccessToken')
        .addQueryParameter('myUrlParameterName', bqTypes.STRING, 'myUrlParameterValue')
        .build();

### getAuthType()

Returns the connector's authentication method.

#### Request

This function does not accept any arguments.

#### Response

### Data Studio Service

`@return {object}` An object that contains the [`AuthType`](https://developers.google.com/data-studio/connector/reference#authtype) used by the
connector. If the `AuthType` is one of `USER_TOKEN`, `USER_PASS`, `KEY`,
`PATH_USER_PASS`, or `PATH_KEY`, an optional `helpUrl` can also be set.

###### Example

    function getAuthType() {
      var cc = DataStudioApp.createCommunityConnector();
      return cc.newAuthTypeResponse()
        .setAuthType(cc.AuthType.USER_PASS)
        .setHelpUrl('https://www.example.org/connector-auth-help')
        .build();
    }

### Legacy

`@return {object}` An object that contains the [`AuthType`](https://developers.google.com/data-studio/connector/reference#authtype) used by the
connector. If the `AuthType` is one of `USER_TOKEN`, `USER_PASS`, `KEY`,
`PATH_USER_PASS`, or `PATH_KEY`, an optional `helpUrl` can also be set.

The response has the following structure:

     {
       "type": string(AuthType),
       "helpUrl": string
     }

<br />

| Field name | Type | Description |
|---|---|---|
| `type` | `string(https://developers.google.com/data-studio/connector/reference#authtype)` | The value for the type of authentication. |
| `helpUrl` | `string` | An optional URL to be shown to the user if `type` is one of `USER_TOKEN`, `USER_PASS`, `KEY`, `PATH_USER_PASS`, or `PATH_KEY`. This URL should point to a page where users can learn details about how to authenticate the connector. |

<br />

###### Response Example

    {
      "type": "USER_TOKEN",
      "helpUrl": "https://www.example.org/connector-auth-help"
    }

## Required Auth functions

### 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`](https://developers.google.com/data-studio/connector/reference#getdata) and [`getSchema`](https://developers.google.com/data-studio/connector/reference#getschema) will be authorized. If
`false` then the user will likely be notified that auth has expired and they
will be asked to reauthorize.

### resetAuth()

Clears user credentials for the third-party service.

#### Request

This function does not formally accept any arguments.

#### Response

The response is empty.

## Required OAuth2 functions

### 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.

> [!NOTE]
> **Note:** It is expected that an authorization URL will always be returned, regardless of the current auth status.

### 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 that can be used for further OAuth 2.0 handling and creating notifications. |

#### Response

`@return {object}` Return an HTML object that will be rendered and shown to the
user. Please view the [Oauth library
documentation](https://github.com/googlesamples/apps-script-oauth2#3-handle-the-callback)
and also Apps Script [HTML Service
documentation](https://developers.google.com/apps-script/guides/html/) for more
details.

## Required User/Pass \& Key functions

### setCredentials()

Stores the credentials passed in from Data Studio.

#### Request

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

The `request` parameter contains the credentials that the user entered. It will
have one of `pathUserPass`, `pathKey`, `userPass`, `userToken`, or `key` set
depending on the response of `getAuthType()`.

    {
      "pathUserPass": {
        "path": : string,
        "username": string,
        "password": string
      },
      "pathKey": {
        "path": : string,
        "key": string
      },
      "userPass": {
        "username": string,
        "password": string
      },
      "userToken": {
        "username": string,
        "token": string
      },
      "key": string
    }

| Field name | Type |
|---|---|
| `pathUserPass.path` | The path provided by the user. |
| `pathUserPass.username` | The username provided by the user. |
| `pathUserPass.password` | The password provided by the user. |
| `pathKey.path` | The path provided by the user. |
| `pathKey.key` | The API key or token provided by the user. |
| `userPass.username` | The username provided by the user. |
| `userPass.password` | The password provided by the user. |
| `userToken.username` | The username provided by the user. |
| `userToken.token` | The token provided by the user. |
| `key` | The API key or token provided by the user. |

#### Response

`@return {object}` A JavaScript object that contains an error code indicating if
the credentials were able to be set successfully.

    {
      "errorCode": string("NONE" | "INVALID_CREDENTIALS")
    }

| Field name | Type | Description |
|---|---|---|
| `errorCode` | `enum(string)` | The errorCode for the setCredentials call |

| Error Code Name | Description |
|---|---|
| `"NONE"` | The credentials were able to be set successfully. |
| `"INVALID_CREDENTIALS"` | The credentials provided were invalid. |

##### Response Example

    {
      "errorCode": "NONE"
    }

## Optional functions

### isAdminUser()

Checks if the user is an admin of the connector. This function is used to
enable/disable debug features. See [Enabling/Disabling debug features](https://developers.google.com/data-studio/connector/debug#enablingdisabling_debug_features) for more
details.

#### Request

This function does not accept any arguments.

#### Response

`@return {boolean}` Return `true` if the user is an admin of the connector. If
the function is omitted or returns `false`, then the user will not be considered
an admin. See [Enabling/Disabling debug features](https://developers.google.com/data-studio/connector/debug#enablingdisabling_debug_features) for more details.

## Data Types

### Field

### Data Studio Service

See [Class Field](https://developers.google.com/apps-script/reference/data-studio/field) for all
methods that exist on the field type.

<br />

###### Creating A Field

###### <br />
var cc = DataStudioApp.createCommunityConnector();
var types = cc.FieldType;
var aggregations = cc.AggregationType;

var myField = cc.newDimension() // Or newMetric
.setId('my_unique_identifier')
.setName('My friendly name')
.setDescription('My short description')
.setType(types.YEAR_MONTH_DAY)
// formula fields cannot be hidden.
.setIsHidden(true)
.setGroup('My group name');

### Legacy

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

Each field has the following structure:

    {
      "name": string,
      "label": string,
      "description": string,
      "dataType": string(DataType),
      "group": string,
      "formula": string,
      "isDefault": boolean,
      "defaultAggregationType": string(DefaultAggregationType),
      "semantics": {
        "conceptType": string(ConceptType),
        "semanticType": string(SemanticType),
        "semanticGroup": string(SemanticGroup),
        "isReaggregatable": boolean
      }
    }

| Field name | Type | Description |
|---|---|---|
| `name` | `string` | The name of the field. This is 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. |
| `description` | `string` | An optional description for the field. Only plain text is allowed. |
| `dataType` | `string(https://developers.google.com/data-studio/connector/reference#datatype)` | The data type for the field. |
| `isHidden` | `boolean` | An optional property. Set to `true` to hide the field. Hidden fields don't show up on the fields screen, or as a selectable field for charts, but can be used in calculated field formulas. **Formula fields cannot be hidden.** |
| `group` | `string` | An optional property that indicates a field belongs to a group. If `fieldA` and `fieldB` both belong to `groupC`, then they will be grouped together in the "Metric picker" or the "Dimension picker" of the UI. If group is defined for at least one field, then the fields without a group are given a group of `Default Group`. |
| `formula` | `string` | An optional property that determines how a field is calculated. If the formula is invalid, then the field is dropped. If both aggregation properties (`isReaggregatable` and `defaultAggregationType`) *and* `formula` are provided, then the aggregation properties are ignored. Only certain `semanticType`s work with a `formula` field. Generally, it's best if these are text or number, with the exception of `date` and `geo`. If the text output of a date or geo formula matches a semantic type, then that semantic type can be used. Otherwise the semantic type should be `string`. If you manually set this field, then it cannot be edited in the fields editor. For more detail on creating formulas, check [About calculated fields](https://support.google.com/looker-studio/answer/6299685). |
| `isDefault` | `boolean` | An optional property that indicates if one field should be selected as the default `dimension` or `metric`. You should define only one default `dimension` and one default `metric` for the schema. |
| `defaultAggregationType` | `string(https://developers.google.com/data-studio/connector/reference#defaultaggregationtype)` | An optional property that indicates what aggregation Data Studio should default to for this field. Users are able to change this value. |
| `semantics` | `object` | Properties to provide semantic information about the field. If this property (and `semantics.semanticType`) is present on any of the fields in the schema, then automatic semantic detection is disabled. If this property is absent from all of the fields, then [automatic semantic detection](https://developers.google.com/data-studio/connector/semantics#semantic-type-detection) will be enabled. |
| `semantics.conceptType` | `string(https://developers.google.com/data-studio/connector/reference#concepttype)` | Indicates whether the field is a dimension or metric. |
| `semantics.semanticType` | `string(https://developers.google.com/data-studio/connector/reference#semantictype)` | The semantic type for the field. If provided, [automatic semantic detection](https://developers.google.com/data-studio/connector/semantics) is disabled. |
| `semantics.semanticGroup` | `string(https://developers.google.com/data-studio/connector/reference#semanticgroup)` | The semantic group for the field. This optional property allows for semantic types to be grouped. Data Studio doesn't currently use this field, but may in the future. |
| `semantics.isReaggregatable` | `boolean` | `true` indicates that *Aggregation* can be applied to this field; In Data Studio *Aggregation* is set to *SUM* by default and the user can change the *Aggregation* . `false` indicates *Aggregation* should not be applied to this field; In Looker Studio *Aggregation* is set to *Auto* by default and the user can't 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. |

### SemanticType

| Enum Value | Description | Example |
|---|---|---|
| `YEAR` | `YYYY` | `"2017"` |
| `YEAR_QUARTER` | `YYYYQ` | `"20171"` |
| `YEAR_MONTH` | `YYYYMM` | `"201703"` |
| `YEAR_WEEK` | `YYYYww` | `"201707"` |
| `YEAR_MONTH_DAY` | `YYYYMMDD` | `"20170317"` |
| `YEAR_MONTH_DAY_HOUR` | `YYYYMMDDHH` | `"2017031403"` |
| `YEAR_MONTH_DAY_SECOND` | `YYYYMMDDHHMMSS` | `"20170314031545"` |
| `QUARTER` | `(1, 2, 3, 4)` | `"1"` |
| `MONTH` | `MM` | `"03"` |
| `WEEK` | `ww` | `"07"` |
| `MONTH_DAY` | `MMDD` | `"0317"` |
| `DAY_OF_WEEK` | A decimal number 0-6 with 0 representing Sunday | `"0"` |
| `DAY` | `DD` | `"17"` |
| `HOUR` | `HH` | `"02"` |
| `MINUTE` | `mm` | `"12"` |
| `DURATION` | A Duration of Time (in seconds) | `6340918234` |
| `COUNTRY` | [Country](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | `"United States"` |
| `COUNTRY_CODE` | [Country Code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | `"US"` |
| `CONTINENT` | [Continent](https://en.wikipedia.org/wiki/UN_M.49) | `"Americas"` |
| `CONTINENT_CODE` | [Continent Code](https://en.wikipedia.org/wiki/UN_M.49) | `"019"` |
| `SUB_CONTINENT` | [Sub Continent](https://en.wikipedia.org/wiki/UN_M.49) | `"North America"` |
| `SUB_CONTINENT_CODE` | [Sub Continent Code](https://en.wikipedia.org/wiki/UN_M.49) | `"003"` |
| `REGION` | [Region](https://en.wikipedia.org/wiki/ISO_3166-2) | `"California"` |
| `REGION_CODE` | [Region Code](https://en.wikipedia.org/wiki/ISO_3166-2) | `"CA"` |
| `CITY` | [City](https://developers.google.com/adwords/api/docs/appendix/geotargeting) | `"Mountain View"` |
| `CITY_CODE` | [City Code](https://developers.google.com/adwords/api/docs/appendix/geotargeting) | `"1014044"` |
| `METRO_CODE` | [Metro Code](https://support.google.com/richmedia/answer/2745487) | `"200807"` |
| `LATITUDE_LONGITUDE` | [Latitude and Longitude](https://en.wikipedia.org/wiki/ISO_6709) | `"51.5074, -0.1278"` |
| `NUMBER` | Decimal Number | `14` |
| `PERCENT` | Decimal percentage (can be over 1.0) | `1.0` |
| `TEXT` | Free form text | `"Here is some text"` |
| `BOOLEAN` | `true` or `false` | `true` |
| `URL` | A URL as text | `"https://www.google.com"` |

#### Formula Semantic Types

| Enum Value | Description | Formula |
|---|---|---|
| `HYPERLINK` | A link with a text label | `"HYPERLINK($url, $description)"` |
| `IMAGE` | A URL of an image | `"IMAGE($image_url, $alt_text)"` |
| `IMAGELINK` | A link with an image label | `"HYPERLINK($url, $image_field)"` |

> [!NOTE]
> **Note:** See [HYPERLINK](https://support.google.com/looker-studio/answer/7431836) and [IMAGE](https://support.google.com/looker-studio/answer/7570489) help center docs for more information.

#### Currency Semantic Types

All currency values are JavaScript numbers. Negative values are permitted.

| Enum Value | Description |
|---|---|
| `CURRENCY_AED` | United Arab Emirates Dirham (dh) |
| `CURRENCY_ALL` | Albanian Lek (Lek) |
| `CURRENCY_ARS` | Argentine Pesos ($) |
| `CURRENCY_AUD` | Australian Dollar ($) |
| `CURRENCY_BDT` | Bangladeshi Taka (৳) |
| `CURRENCY_BGN` | Bulgarian Lev (lev) |
| `CURRENCY_BOB` | Bolivian Boliviano (Bs) |
| `CURRENCY_BRL` | Brazilian Real (R$) |
| `CURRENCY_CAD` | Canadian Dollar ($) |
| `CURRENCY_CDF` | Congolese Franc (FrCD) |
| `CURRENCY_CHF` | Swiss Franc (CHF) |
| `CURRENCY_CLP` | Chilean Peso ($) |
| `CURRENCY_CNY` | Chinese Yuan (¥) |
| `CURRENCY_COP` | Colombian Peso ($) |
| `CURRENCY_CRC` | Costa Rican Colon (₡) |
| `CURRENCY_CZK` | Czech Koruna (Kč) |
| `CURRENCY_DKK` | Danish Krone (kr.) |
| `CURRENCY_DOP` | Dominican Peso (RD$) |
| `CURRENCY_EGP` | Egyptian Pound (£) |
| `CURRENCY_ETB` | Ethiopian Birr (Birr) |
| `CURRENCY_EUR` | Euro (€) |
| `CURRENCY_GBP` | British Pound Sterling (£) |
| `CURRENCY_HKD` | Hong Kong Dollar ($) |
| `CURRENCY_HRK` | Croatian Kuna (kn) |
| `CURRENCY_HUF` | Hungarian Forint (Ft) |
| `CURRENCY_IDR` | Indonesian Rupiah (Rp) |
| `CURRENCY_ILS` | Israeli New Sheqel (₪) |
| `CURRENCY_INR` | Indian Rupee (₹) |
| `CURRENCY_IRR` | Iranian Rial (Rial) |
| `CURRENCY_ISK` | Icelandic Krona (kr) |
| `CURRENCY_JMD` | Jamaican Dollar ($) |
| `CURRENCY_JPY` | Japanese Yen (¥) |
| `CURRENCY_KRW` | South Korean Won (₩) |
| `CURRENCY_LKR` | Sri Lankan Rupee (Rs) |
| `CURRENCY_LTL` | Lithuanian Litas (Lt) |
| `CURRENCY_MNT` | Mongolian Tugrik (₮) |
| `CURRENCY_MVR` | Maldivian Rufiyaa (Rf) |
| `CURRENCY_MXN` | Mexican Peso ($) |
| `CURRENCY_MYR` | Malaysian Ringgit (RM) |
| `CURRENCY_NOK` | Norwegian Krone (kr) |
| `CURRENCY_NZD` | New Zealand Dollars ($) |
| `CURRENCY_PAB` | Panamanian Balboa (B/.) |
| `CURRENCY_PEN` | Peruvian Nuevo Sol (S/.) |
| `CURRENCY_PHP` | Philippine Peso (₱) |
| `CURRENCY_PKR` | Pakistani Rupee (Rs) |
| `CURRENCY_PLN` | Polish Zloty (zł) |
| `CURRENCY_RON` | Romanian Leu (RON) |
| `CURRENCY_RSD` | Serbian Dinar (din) |
| `CURRENCY_RUB` | Russian Ruble (₽) |
| `CURRENCY_SAR` | Saudi Riyal (Rial) |
| `CURRENCY_SEK` | Swedish Krona (kr) |
| `CURRENCY_SGD` | Singapore Dollar ($) |
| `CURRENCY_THB` | Thai Baht (฿) |
| `CURRENCY_TRY` | Turkish Lira (₺) |
| `CURRENCY_TWD` | New Taiwan Dollar (NT$) |
| `CURRENCY_TZS` | Tanzanian Shilling (TSh) |
| `CURRENCY_UAH` | Ukrainian Hryvnia (грн.) |
| `CURRENCY_USD` | US Dollar ($) |
| `CURRENCY_UYU` | US Dollar ($) |
| `CURRENCY_VEF` | Uruguayan Peso ($) |
| `CURRENCY_VND` | Venezuela Bolivar Fuerte (Bs) |
| `CURRENCY_YER` | Vietnamese Dong (₫) |
| `CURRENCY_ZAR` | Yemeni Rial (Rial) |

### SemanticGroup

This is only a list of suggested values, you are free to choose values outside
this list. However, setting this field will not override the group that Looker
Studio uses in the `Type` option for the fields editor.

| Suggested Value | Description |
|---|---|
| `NUMERIC` | Numeric group |
| `DATETIME` | DateTime group |
| `GEO` | Geo Group |
| `CURRENCY` | Currency Group |

### DefaultAggregationType

| Enum Value | Description |
|---|---|
| `AVG` | The numerical average (mean) of the entries. |
| `COUNT` | The number of entries. |
| `COUNT_DISTINCT` | The number of distinct entries. |
| `MAX` | The maximum of the entries. |
| `MIN` | The minimum of the entries. |
| `SUM` | The sum of the entries. |
| `NONE` | No aggregation |
| `AUTO` | Should be set for calculated fields involving an aggregation |

> [!NOTE]
> **Note:** `AUTO` should only be used for calculated fields. See [calculated fields](https://developers.google.com/data-studio/connector/calculated-fields).

### 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. |
| `KEY` | Indicates the connector uses API key. |
| `USER_PASS` | Indicates the connector uses username/password. |
| `USER_TOKEN` | Indicates the connector uses username/token. |
| `PATH_USER_PASS` | Indicates the connector uses path/username/password. |
| `PATH_KEY` | Indicates the connector uses path/key. |

### 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. Any links will be clickable. |

### Filter Operator

| Operator |
|---|
| [EQUALS](https://developers.google.com/data-studio/connector/reference#filterequals) |
| [CONTAINS](https://developers.google.com/data-studio/connector/reference#filtercontains) |
| [REGEXP_PARTIAL_MATCH](https://developers.google.com/data-studio/connector/reference#filterregexppartialmatch) |
| [REGEXP_EXACT_MATCH](https://developers.google.com/data-studio/connector/reference#filterregexpexactmatch) |
| [IN_LIST](https://developers.google.com/data-studio/connector/reference#filterinlist) |
| [IS_NULL](https://developers.google.com/data-studio/connector/reference#filterisnull) |
| [BETWEEN](https://developers.google.com/data-studio/connector/reference#filterbetween) |
| [NUMERIC_GREATER_THAN](https://developers.google.com/data-studio/connector/reference#filternumericgreaterthan) |
| [NUMERIC_GREATER_THAN_OR_EQUAL](https://developers.google.com/data-studio/connector/reference#filternumericgreaterthanorequal) |
| [NUMERIC_LESS_THAN](https://developers.google.com/data-studio/connector/reference#filternumericlessthan) |
| [NUMERIC_LESS_THAN_OR_EQUAL](https://developers.google.com/data-studio/connector/reference#filternumericlessthanorequal) |

#### `EQUALS`

The comparison value exactly matches the dimension value.

Example clause:

    {
        "operator": "EQUALS",
        "type": "INCLUDE",
        "values": ["USA"],
        "fieldName": "Country"
    }

> [!CAUTION]
> **Caution:** `values` is an `Array`, not a single `string`;

Data before applying filter:

| Country | City |
|---|---|
| USA | Seattle |
| CA | Montreal |
| ROK | Seoul |

Data after applying filter:

| Country | City |
|---|---|
| USA | Seattle |

#### `CONTAINS`

The comparison value is contained within the dimension value.

Example clause:

    {
        "operator": "CONTAINS",
        "type": "INCLUDE",
        "values": ["A"],
        "fieldName": "COUNTRY"
    }

Data before applying filter:

| Country | City |
|---|---|
| USA | Seattle |
| CA | Montreal |
| ROK | Seoul |

Data after applying filter:

| Country | City |
|---|---|
| USA | Seattle |
| CA | Montreal |

#### `REGEXP_PARTIAL_MATCH`

The dimension value contains the regular expression.

Example clause:

    {
        "operator": "REGEXP_PARTIAL_MATCH",
        "type": "INCLUDE",
        "values": ["(?i)R[A-Z]*"],
        "fieldName": ""
    }

Data before applying filter:

| Country | City |
|---|---|
| USA | Seattle |
| CA | Montreal |
| ROK | Seoul |
| RU | Moscow |

Data after applying filter:

| Country | City |
|---|---|
| ROK | Seoul |
| RU | Moscow |

#### `REGEXP_EXACT_MATCH`

The dimension value matches the regular expression.

Example clause:

    {
        "operator": "REGEXP_EXACT_MATCH",
        "type": "INCLUDE",
        "values": ["^R[A-Z]*K$"],
        "fieldName": ""
    }

Data before applying filter:

| Country | City |
|---|---|
| USA | Seattle |
| CA | Montreal |
| ROK | Seoul |
| RU | Moscow |

Data after applying filter:

| Country | City |
|---|---|
| ROK | Seoul |

#### `IN_LIST`

One or more of the comparison values exactly matches the dimension value.

Example clause:

    {
        "operator": "IN_LIST",
        "type": "INCLUDE",
        "values": ["USA", "CA"],
        "fieldName": "Country"
    }

Data before applying filter:

| Country | City |
|---|---|
| USA | Seattle |
| CA | Montreal |
| ROK | Seoul |

Data after applying filter:

| Country | City |
|---|---|
| USA | Seattle |
| CA | Montreal |

#### `IS_NULL`

Matches if the dimension value is null.

Example clause:

    {
        "operator": "IS_NULL",
        "type": "INCLUDE",
        "values": [],
        "fieldName": "COUNTRY"
    }

Data before applying filter:

| Country | City |
|---|---|
| USA | Seattle |
| CA | Montreal |
| ROK | Seoul |
| RU | Moscow |
|   | Terabithia |

Data after applying filter:

| Country | City |
|---|---|
|   | Terabithia |

#### `BETWEEN`

Matches if the dimension value is between the two test values.

Example clause:

    {
        "operator": "BETWEEN",
        "type": "INCLUDE",
        "values": ["20190101", "20190131"],
        "fieldName": "Date"
    }

Data before applying filter:

| Country | Date |
|---|---|
| USA | 20190101 |
| USA | 20190111 |
| USA | 20190201 |

Data after applying filter:

| Country | Date |
|---|---|
| USA | 20190101 |
| USA | 20190111 |

#### `NUMERIC_GREATER_THAN`

Matches if the dimension value is greater than the test value.

Example clause:

    {
        "operator": "NUMERIC_GREATER_THAN",
        "type": "INCLUDE",
        "values": ["20190101"],
        "fieldName": "Date"
    }

Data before applying filter:

| Country | Date |
|---|---|
| USA | 20190101 |
| USA | 20190111 |
| USA | 20190201 |

Data after applying filter:

| Country | Date |
|---|---|
| USA | 20190111 |
| USA | 20190201 |

#### `NUMERIC_GREATER_THAN_OR_EQUAL`

Matches if the dimension value is greater than or equal to the test value.

Example clause:

    {
        "operator": "NUMERIC_GREATER_THAN_OR_EQUAL",
        "type": "INCLUDE",
        "values": ["20190101"],
        "fieldName": "Date"
    }

Data before applying filter:

| Country | Date |
|---|---|
| USA | 20180101 |
| USA | 20190101 |
| USA | 20190111 |
| USA | 20190201 |

Data after applying filter:

| Country | Date |
|---|---|
| USA | 20190101 |
| USA | 20190111 |
| USA | 20190201 |

#### `NUMERIC_LESS_THAN`

Matches if the dimension value is less than or equal to the test value.

Example clause:

    {
        "operator": "NUMERIC_LESS_THAN",
        "type": "INCLUDE",
        "values": ["20190101"],
        "fieldName": "Date"
    }

Data before applying filter:

| Country | Date |
|---|---|
| USA | 20180101 |
| USA | 20190101 |
| USA | 20190111 |
| USA | 20190201 |

Data after applying filter:

| Country | Date |
|---|---|
| USA | 20180101 |

#### `NUMERIC_LESS_THAN_OR_EQUAL`

Matches if the dimension value is less than or equal to the test value.

Example clause:

    {
        "operator": "NUMERIC_LESS_THAN_OR_EQUAL",
        "type": "INCLUDE",
        "values": ["20190101"],
        "fieldName": "Date"
    }

Data before applying filter:

| Country | Date |
|---|---|
| USA | 20180101 |
| USA | 20190101 |
| USA | 20190111 |
| USA | 20190201 |

Data after applying filter:

| Country | Date |
|---|---|
| USA | 20180101 |
| USA | 20190101 |