Articles on: Connectors

Configure Connectivity

Obtain connector keys



After the connector created, it will generate the following keys:

Identifier
OAUTH2 Redirect URL


Steps to get the keys value


Navigate to, Left panel --> More --> My Apps
Click the connector you want
In the Manage modal options, Click Connector Information
In the Connector Information modal, copy the required key value.




Where to use Identifier



When configuring an OAUTH2 Connector, The Identifier should be used under parameters [ ] --> redirect_uri.

Example: Obtain the Identifier (APP_XXXXXXXXX) and concatenate it to the redirect_uri value it as shown below

Code Snippet
{
  "name": "redirect_uri",
  "value": "?identifier=APP_XXXXXXXXX"
}


Where to use OAUTH2 Redirect URL



When registering an oauth2 App on 3rd-party website.

Example: User registered an App on Typeform website
Obtain the OAUTH2 Redirect URL and add it to Typeform App






Configure Connectivity



Setup basic, apikey and oauth2 connections.

Navigate to, Left panel --> More --> My Apps
Click the connector to be modified
In the Manage modal options, Click Configure Connectivity
Modify the fields and click Save




The JSON editor contains the following Arrays of Objects:

annotation
items
urls
parameters
headers
data
settings




annotation


Array of Objects. It contains one Object.

note_general - To add general notes or instructions when create/modify a connection. For example, the user need to know where to find the API Key from 3rd party App. This content will appear on top of the modal when creating a connection. Accept HTML formatting.



Code Snippet
[
  {
    "name": "note_general",
    "value": "YOUR_CUSTOM_CONNECTOR_NOTES"
  }
]





items


This array used for the following connection types
apikey
basic

component - Fixed value (ascx_connection_component_textbox), don't modify it.
id - Combination of two parts:
Part1: txt_connection_ : Technical name, don't modify it.
Part2: 3rd-party API Docs - key name, Example: API-Key
The id value will be txt_connection_API-Key

name - the key name used in the API Docs, Example: API-Key
placeholder - The text appears in the textbox when its empty. Its used as an helper about the kind of data to be added. Example: Authorisation Code...
required - Specify if this field is required. Possible values: true, false
subTitle - Text under title label. Used as a description of the textbox.
tabindex - The component order. in case the Connector has multiple components. Sorting in ascending order will depend on this value added on each component. Example: First component: tabindex=0, Second component: tabindex=1, Third component: tabindex=2
title - Component title. Example: username, password, Authorization code.
type - The component type. Possible values: text, password.
validationNote - Data validation note for this component.
isDisabled - Some Apps requires keys to be added with no value. Possible values: true, false
defaultValue - Specify if the component has a default value.


Connection type: apikey

The number of keys depending on App API Docs. Most Apps uses one key, each key need an Object from the code snippet below.




Code Snippet
[
    {
      "component": "ascx_connection_component_textbox",
      "id": "txt_connection_key",
      "name": "key",
      "placeholder": null,
      "required": "true",
      "subTitle": null,
      "tabindex": "0",
      "title": "Key",
      "type": "text",
      "validationNote": null,
      "isDisabled": null,
      "defaultValue": null
    }
]




Connection type: basic

Most Apps of security type basic uses username, password & Authorisation Code keys as shown in the code snippet below. This depend on the App API Docs.



Code Snippet
[
    {
      "component": "ascx_connection_component_textbox",
      "id": "txt_connection_username",
      "name": "username",
      "placeholder": "username...",
      "required": "optional",
      "subTitle": null,
      "tabindex": "0",
      "title": "Username",
      "type": "text",
      "validationNote": "validation note here!",
      "isDisabled": "false",
      "defaultValue": null
    },
    {
      "component": "ascx_connection_component_textbox",
      "id": "txt_connection_password",
      "name": "password",
      "placeholder": "password...",
      "required": "optional",
      "subTitle": null,
      "tabindex": "1",
      "title": "Password",
      "type": "password",
      "validationNote": null,
      "isDisabled": "false",
      "defaultValue": null
    },
    {
      "component": "ascx_connection_component_textbox",
      "id": "txt_connection_authorisationcode",
      "name": "Authorisation",
      "placeholder": "Authorisation Code...",
      "required": "true",
      "subTitle": null,
      "tabindex": "2",
      "title": "Authorisation Code",
      "type": "text",
      "validationNote": null,
      "isDisabled": "false",
      "defaultValue": null
    }
]




urls


Its an Array of Objects, each object should have 2 keys: name & value.

name - key name
value - key value

Example: An oauth2 app requires the following keys for the connection process:
authorisation
authentication
refresh_token

Code Snippet
[ 
    {
      "name": "authorisation",
      "value": "https://accounts.google.com/o/oauth2/v2/auth?scope={params.scope}&redirect_uri={params.redirect_uri}&response_type=code&client_id={params.client_id}&prompt=consent&access_type=offline"
    },
    {
      "name": "authentication",
      "value": "https://www.googleapis.com/oauth2/v4/token?code={query.code}&client_id={params.client_id}&client_secret={params.client_secret}&redirect_uri={params.redirect_uri}&grant_type={params.grant_type}"
    },
    {
      "name": "refresh_token",
      "value": "https://accounts.google.com/o/oauth2/token?client_id={params.client_id}&client_secret={params.client_secret}&refresh_token={query.refresh_token}&grant_type=refresh_token"
    }
]





parameters


It represent the request payload parameters (appending query parameters to the url). The parameters array used to organize the connection process configuration.
Its an Array of Objects, each object should have 2 keys: name & value.
Each key in parameters array belongs to the same key in the urls array.

Example:
Key name scope exists in urls array.
Key name scope exists in parameters array

Code Snippet
{
  "urls": [
    {
      "name": "authorisation",
      "value": "https://accounts.google.com/o/oauth2/v2/auth?scope={params.scope}"
    }
  ],
  "parameters": [
    {
      "name": "scope",
      "value": "https://www.googleapis.com/auth/drive"
    }
  ]
}




Example: An App requires the following keys for the connection process:
redirect_uri
response_type
client_id
client_secret
grant_type
scope
state

Code Snippet
[ 
    {
      "name": "redirect_uri",
      "value": "?identifier=YOUR_CUSTOM_APP_IDENTIFIER"
    },
    {
      "name": "response_type",
      "value": "YOUR_CUSTOM_APP_RESPONSE_TYPE"
    },
    {
      "name": "client_id",
      "value": "YOUR_CUSTOM_APP_CLIENT_SECRET"
    },
    {
      "name": "client_secret",
      "value": "YOUR_CUSTOM_APP_CLIENT_SECRET"
    },
    {
      "name": "grant_type",
      "value": "YOUR_CUSTOM_APP_GRANT_TYPE"
    },
    {
      "name": "scope",
      "value": "YOUR_CUSTOM_APP_SCOPES"
    },
    {
      "name": "state",
      "value": "YOUR_STATE_KEY_VALUE"
    }
]



headers


It represent the request payload headers. Its an Array of Objects, each object should have 2 keys: name & value.

Example: An App requires the following keys for the content type and connection process
Content-Type
Authorization

Code Snippet
[
    {
      "name": "Content-Type",
      "value": "application/x-www-form-urlencoded"
    },
    {
      "name": "Authorization",
      "value": "YOUR_CUSTOM_APP_AUTHORIZATION_KEY"
    }
]



data


It represents the request payload body. The data array used to organize the connection process configuration.
Its an Array of Objects, each object should have 3 keys: type, name & value.
Each key in data array belongs to the same key in the urls array.

type - belongs to the same key name that exists in the urls array
name - belongs to the same key value that exists in the urls array --> query parameters
value - key value

Example:
Key type authorisation in data array belong to the key name authorisation in the urls array.
Key name scope in the urls array will read its value from value in data array

Code Snippet
{
"urls": [
    {
      "name": "authorisation",
      "value": "https://accounts.google.com/o/oauth2/v2/auth?scope={params.scope}"
    }
],
"data": [
    {
      "type": "authorisation",
      "name": "scope",
      "value": "{params.scope}"
    }
],
"parameters": [
    {
      "name": "scope",
      "value": "https://www.googleapis.com/auth/drive"
    }
]
}




Example: An App requires the following data keys to be used in urls array:
authorisation
authentication
refresh_token

Code Snippet
[
    {
      "type": "authorisation",
      "name": "response_type",
      "value": "{params.response_type}"
    },
    {
      "type": "authorisation",
      "name": "client_id",
      "value": "{params.client_id}"
    },
    {
      "type": "authorisation",
      "name": "redirect_uri",
      "value": "{params.redirect_uri}"
    },
    {
      "type": "authorisation",
      "name": "scope",
      "value": "{params.scope}"
    },
    {
      "type": "authentication",
      "name": "grant_type",
      "value": "{params.grant_type}"
    },
    {
      "type": "refresh_token",
      "name": "grant_type",
      "value": "refresh_token"
    },
    {
      "type": "authentication",
      "name": "code",
      "value": "{query.code}"
    },
    {
      "type": "authentication",
      "name": "client_secret",
      "value": "{params.client_secret}"
    },
    {
      "type": "refresh_token",
      "name": "refresh_token",
      "value": "{connection.refresh_token}"
    }
  ]



settings


Some Apps requires special configuration to work. The settings array used for this case. Its an Array of Objects, each object should have 2 keys: name & value.
Example: The refresh_token of an App will expire after first use. The UPDATE_REFRESH_TOKEN_FROM_CONNECTION will be used and set its value to true (All keys/values will be available in the below table name Key-Value Guidance)

Code Snippet
[
  {
     "name": "UPDATE_REFRESH_TOKEN_FROM_CONNECTION",
     "value": "true, false"
  },
  {
     "name": "KEY_AUTHENTICATION_IDENTIFIER",
     "value": "identifier, state"
  },
  {
     "name": "SUPRESS_REFRESH_TOKEN",
     "value": "true, false"
  },
  {
     "name": "SUPRESS_TOKEN_BEARER",
     "value": "true"
  }
]




General Guidance



VariablesPossible ValueNotes
{params.value}scope, redirect_uri, client_id, client_secret, grant_type, response_type, promptparams → It represent the request payload parameters(appending query parameters to the url)
{header.value}It represent the request payload headers
{connection.value}refresh_token
{query.value}code, refresh_tokenquery → it read from response url
{data.value}It represents the request payload body



Key-Value Guidance



VariablesPossible ValueNotes
securityTypeoauth2, basic, apikey
settings { }
settings.UPDATE_REFRESH_TOKEN_FROM_CONNECTIONtrue, falsesome oauth2 application, for example, Xero, their refresh_token will expire after first use. In this case, the expected response of the refresh_token type endpoint will return a new “refresh_token” key. This new “refresh_token” key will replace the old refresh_token once used.
settings.KEY_AUTHENTICATION_IDENTIFIERidentifier, statesome oauth2 application, for example, Microsoft needs to use the state as an identifier because it does not allow to add query string parameters to the redirect_uri. If this value not existing then by default means identifier
settings.SUPRESS_REFRESH_TOKENtrue,falsesome oauth2 application, for example, Slack their refresh_token does not exist, this key should be set to true. If this value not existing then the default means false
settings.ROOT_TOKEN_RESPONSEExample: parent1, partent1.child1The path of the response payload returned by the authentication call.
settings.SUPRESS_TOKEN_BEARERtrue,falseif the word Bearer/bearer does not exist in the Authorization value, this key should be set to true. If this value not existing then the default means false
host{ }some basic application, for example, Jira cloud, has a variable part in their URL
host.namethis key represents the name of the variable part in the URL
host.patternthis key represents the URL including the variable part location

Updated on: 15/11/2022

Was this article helpful?

Share your feedback

Cancel

Thank you!