Schema definition

This topic describes the root-level properties required for custom connectors and their related parameters, the scope and limitations of custom connectors, and requirements of the API you wish to use. See Scope and limitations.

schema

The schema property specifies the schema version of the connector.

Property Type Required? Example
schema string Yes The version of the schema used

name

The name property specifies the name of the connector. This property is visible in the UI. See Connector visual properties.

Property Type Required? Example
name string Yes My custom connector

description

The description property specifies the description of the connector. This property is visible in the UI. See Connector visual properties.

Property Type Required? Example
description string No My custom connector description

auth_components

The auth_components object specifies the property necessary for authenticating to third-party APIs. Some APIs may not require authentication, while others may require a certain type of authentication method, for example OAuth1.

Property Type Required?
type

string

 Yes

requiredSettings

The requiredSettings object specifies the properties required by the API for successful communication.

Property Type Required? Description
authFields array Yes The fields that are required for authentication

requiredSettings (authFields)

The authFields array specifies the fields required for authenticating to the API. For APIs that don't require authentication, leave the authFields array empty.

Property Type Required? Description Example

label

 string No The label of the authentication field Access Token
key string No The key for the authentication field access_token
description string No The description of the authentication field My field description
errorText string No The description of a specific error scenario My error message
masked boolean No Whether the value of the field will be masked to hide sensitive information True
choices object No A pull-down list with values that user can choose from { options_a: "Option A", options_b: "Option B"}
preAddOn string No A value that can be prepended to the authentication field "https://"
emptyAllowed boolean No Whether the value of the authentication field can be empty True
extLink string No A link to external documentation https://help.claris.com/en/connect-help/
postAddOn string No A value that can be postpended to the authentication field example.com

auth_request

The auth_request object specifies the type of authorization request used when communicating with the API to determine the access level of the current user.

Property Type Required? Description Authorization type Example
type string Yes The type of the authorization request basic auth, bearer, custom, custom body, custom header, custom query, or none bearer
errorMessageKey string No The key for the error message found in the third-party app response All error.message
token string No The token property for bearer authorization bearer '{{authFields.api_key}}'
headers object No The HTTP headers to be included in the authorization request All { 'X-Algolia-API-Key': '{{authFields.api_key}}', 'X-Algolia-Application-Id': '{{authFields.app_id}}' }
query_parameters object No The query parameters to be included in the authorization request custom_query { access_token: '{{authFields.access_token}}' }
username string No The username attribute to be used for basic authorization basic_auth '{{authFields.username}}'
password string No The password attribute to be used for basic authorization basic_auth '{{authFields.password}}'
body_parameters object No The body parameters to be included in the authorization request custom_body { access_token: '{{authFields.access_token}}' }

endpoints

The endpoints object specifies the HTTP methods to be used in the request to the API, the target resources of the API, and the root path (URL) of the resource.

For example, to return a list of fields from a table in Claris Studio using the Claris Studio connector, insert a GET method object with a nested /field object that targets resources located at https://api.platform.claris.com. See below for an example:

Copy 
"endpoints": {
      "GET": {
        "/field": {
          "url": "https://api.platform.claris.com"
        }
      }
    },
Property Type Required? Description Example
url string Yes The root URL of the third-party API https://api.platform.claris.com
custom_behavior object No The custom behavior object  

endpoints (custom_behavior)

For each resource, you can optionally add a custom_behavior object where you can apply custom logic to the headers, query, and body of the HTTP request made for that resource.

Property Type Required? Description
headers object No An object specifying custom headers to be sent in the request
body_options object No

An object where custom behavior can be applied to the entire body of the request.

send_as_urlencoded (boolean)

  • Specifies whether to send the request as the application/x-www-form-urlencoded content type.

send_as_multipart (boolean)

  • Specifies whether to send the request as multipart/form-data content type.

actions

The actions array specifies the actions and associated properties to be included in the connector. Actions reference resource endpoints specified in the endpoints object and are used to manipulate data coming from or going to the third-party API.

Property Type Required? Description Example
modelId string Yes The model ID of the action. Creates a compound index with actionID. files
actionId string Yes The action ID of the action. Creates a compound index with modelID. search
method string Yes The HTTP method of the action GET
endpoint string Yes

The resource endpoint of the action.

Note  You can also use a variable in the endpoint path. See Using endpoint variables.

 '/search'
isNotTestable boolean No Whether the action is not testable by the user True
label string No The name of the action Search by query
helpText string Yes The description of the action Search using a custom query
urlFields array No An object that specifies the fields to be included in the action  
actionFields array Yes An object that specifies the fields to be included in the action  

actionFields and urlFields

The actionFields and urlFields objects specifies the fields for an action and controls how the action works. some elements of urlFields and actionFields are visible in the UI. See Actions visual properties and Fields visual properties.

Property Type Required? Description Example
key string Yes The HTTP method of the action GET
helpText string No The placeholder value for the field Example: Value
type string No The data type of the field string
choices object No The list of available choices "choiceA" : "Choice A", "choiceB" : "Choice B"
required boolean Yes Whether the actionField or urlField is required True

testConnection

The testConnection object specifies the properties used to test the connection between Claris Connect and the API as well as ensure that authentication credentials are valid. The call specified in testConnection inherits auth_request settings and is made when authenticating to the API.

Note  The testConnection endpoint must be specified in the endpoints object, otherwise authentication will fail.

Property Type Required? Description Example
endpoint string Yes The resource endpoint used to test the connection to the third-party API /users
queryParameters string No The query parameters to append to the resource endpoint used to test the connection to the third-party API q=Claris
method string No The HTTP method to be used to test the connection to the third-party API GET
body object No The body of the HTTP request used to test the connection to the third-party API {"text":"Connect"}

Visual properties

The table below shows which component properties in the schema are visible in the UI after the connector is created.

Connector

The properties in the connector object correspond to the card you see when you click the (i) icon for your connector in the Select tab.

Property Type Required? UI
name string Yes Custom connector name
description string No Custom connector description

Actions

The properties in the actions object correspond to the list of actions your see in the Action tab after you select your connector.

Property Type Required? UI
label string Yes Custom connector action name
helpText string Yes Custom connector action description

Fields (urlFields and actionFields)

The properties in the fields object correspond to the fields you see in the Configure tab after choosing an action from your connector.

Property Type Required? UI
label string Yes Custom connector action, field name
description string Yes Custom connector action, field description
required string Yes Custom connector action, field required

Using endpoint variables

Paths to endpoints specified in the endpoints object can contain variables. Variables indicate that a part of an endpoint is a placeholder that can be any value and are denoted with a colon (:). For example, mydomain.com/api/myEndpoint/:myVariable.

To use endpoints with variables in the actions or testConnection objects, you must do three things:

  1. In the endpoints object, declare the endpoint.

  2. In the urlFields array within the actions array, specify a "key" attribute with the same value as the variable used in the endpoint.
    For example, if the endpoint variable is :id, the urlFields array should contain "key" : "id".

  3. In the actions array, specify the endpoint by using the syntax /myEndpoint/{{urlField.myVariable}}, where myVariable is the value specified for "key" in the urlFields array, which corresponds to the endpoint variable declared in the endpoints array.

    For example, if the value of key is id, the endpoint reference would be /myEndpoint/{{urlField.id}}.

The screenshot below shows an example using PokéAPI to return a Pokémon by ID using an /:id variable attached to the /pokemon endpoint.

Endpoint variable

Scope and limitations

Some features and functionality of custom connectors are limited but will be improved upon over time:

  • Only one API can be used per connector.

  • Steps

    • Triggers are not supported.

    • Each action in a connector corresponds to one endpoint of the target API.

  • Authentication

    • Only basic auth, bearer token, custom query, and custom body authentication methods are supported.

      In the auth_request object:

      • To send a username and password, use basic_auth.

      • To send an API key as a bearer token, use bearer.

      • To send an API key as part of the URL, use custom_query.

      • To send an API key as part of the body, use custom_body.

    • Only one authentication method can be used per connector.

  • Custom icons are not supported.

  • Custom connectors are only available to the owner's team.

  • Custom connectors can't be updated.