From an API definition

Create a new connector

1. If you select Start from an API definition, you must provide the API definition:

   • From a local file – Upload a Postman or Swagger collection

   • From a URL – Enter a file URL, such as https://petstore.swagger.io/v2/swagger.json

     
     

     

     
     
2. Click Continue.

Configure your connector

1. In the Confirm import window, you can:

   • Change the Provider name,Application name, and Connector name

   • Modify the resources you want to use in your custom connector. All available resources are automatically selected; unselect the ones you wish to exclude.

     • Use the Search bar to look for a specific resource.

       
       

       

       
       
   • Click Create.
2. The Settings window is now displayed.

3. In the Info tab you can configure the following fields:

   • Connector prefix – for example, documentation. This is reflected in your connector key, for example, documentation-swaggerpetstore-swaggerpetstore
   • Provider name – Enter a provider name.
   • Application name – Enter an application name.
   • API type – This field is disabled by default, as only REST is currently supported.
   • Display name – This is the name of your connector, as it will appear in the Connector catalog.
   • Description – Enter a description for your connector.
   • Icon – Click Browse to upload an image from your computer.
4. Catalog preview displays how your custom connector will appear in the Integration Service connector catalog.

5. Click Save.

   
   

   

   
   

Configure the Base API

In the Base API tab, you configure the base URL for the application API and pagination:

• Base URL – Automatically filled with the value declared at connector creation.
• Pagination type – Options available in the drop-down are: Page start with 1, Page starts with 0, Offset, Custom. If the vendor documentation doesn’t provide any details on pagination, keep the default value.
• Pagination max – Default value is 100. If the vendor documentation doesn’t provide any details on pagination, keep the default value.
• Content-Type header – This field is disabled by default, as only application/json is currently supported.

• Accept header – This field is disabled by default, as only application/json is currently supported.

  
  

  

  
  

Set the authentication method

In the Authentication tab, you configure the authentication type for your connector. Supported options are:

• Basic

• OAuth 2.0:

  • Authorization Code
  • Authorization code with PKCE
  • Client Credentials
• API Key
• Personal Access Token (PAT)

• No Authentication

  Note: When configuring the authentication, you are configuring how anybody using your connector needs to authenticate. This will be you while you are building the connector, but could also be others that end up using your creation.

Basic authentication

1. Click the edit icon under the Action column to configure each property. Username and Password are available by default.

2. Click Add parameter if you want to add another field to be used during authentication:

   • Display name – Shown to the user when connecting.
   • Type – Defines the input field on the connection dialog. Select an option from the drop-down: true/false, password, test, yes/no.
   • Ask the user – Set to Yes when user input is required.
   • Value – Use this field to set a default value.
   • Hint text – User guidance for the input field.
   • Provider name - The technical key for the API call.

   • Send to provider as type – How the API receives the value. Select an option from the drop-down: configuration, header, path, body, query, form. Default value: header.

     
     

     

     
     
3. Click Save to save your new authentication parameter.
4. Use the Reset to default option if you want to reset your authentication to the original values for Basic. This operation cannot be undone.

OAuth 2.0 Authorization Code

To use OAuth 2.0 Authorization Code, you need to create an OAuth app in the application you want to integrate with, and retrieve from there the credentials necessary for configuring your connector.

Configure the following fields:

• Client ID
• Client secret
• Scope
• Authorization URL
• Token URL
• Refresh token URL
• Basic header
• Token revoke URL

• Refresh interval

  Note: The Authorization, Token, and Refresh token URLs should be available in the app's API documentation.
  
  

  

  
  

OAuth 2.0 Authorization Code with PKCE

OAuth 2.0 Authorization Code with PKCE is identical to the OAuth 2.0 Authorization Code method, but it also include the OAuth2 PKCE Code Challenge Method field.

OAuth 2.0 Client Credentials

For OAuth 2.0 Client Credentials, you must configure the following fields:

• Client ID
• Client secret
• Scope
• Token URL
• Basic header

• Refresh interval

  
  

  

  
  

API Key

Use this option for integrating with apps that require an API key to make API calls against.

Set the API Key field to your desired value.

Personal Access Token

Use this option for integrating with apps that require a bearer token to make API calls against.

Set the Personal Access Token field to your bearer token.

No authentication

Use this option if you don’t need users to authenticate to use the connector.

Test your connection

Once you have completed the authentication configuration, select Add connection from the drop-down menu:

If your connection is successful, the status is updated to Connected.

Resources

The Connector Builder generates the list of resources based on the provided API definition.

The left-side menu displays the list of available resources, organized in groups.

1. Click the ellipses icon to further configure each method. You can:

   • Add method – Opens the Create new resource window.
   • Allow method deletion – Activates a Delete icon for each resource in the group.
   • Edit path – Edit the resource’s path. For example: [BASE URL]/pet = https://petstore.swagger.io/v2/pet
   • Delete – Deletes a resource group. A message warns you that the operation cannot be undone.

   • Duplicate – Opens the Duplicate resource window, where you can edit the Path, choose a Display Name and Select methods.

     
     

     

     
     

2. You can also Create new resource group in two ways:

   • from Blank
   • from cURL

3. If you choose to configure a new resource from Blank, configure the following fields:

   • Path - [Base URL]/[path]
   • Display name

   • Select methods: Get, Get By Id, Post, Put, Patch, Delete

     
     

     

     
     
4. If you choose to configure a new resource from cURL, enter a cURL command.

Configure your resources

When you select a resource, the following window is displayed:

Depending on the resource method you select, the following configuration tabs are available: Parameters, Response/Request Fields, Pagination, Search.

Parameters

For example, all four tabs are available for GET methods. For POST methods, you can only see the Parameters, Request Fields, and Response Fields tabs.

In Parameters, you can view the list available parameters for the selected resource, add new parameters or import parameters from an existing resource.

The parameters listed in this table are the ones you will use in Studio when building automations using your custom connector.

For example, here is a Get record activity from the Connector Builder activity pack:

The Pet object corresponds to the Pet resource group, and the available fields are the ones set for the GETBYID resource:

Response and Request fields

The Response and Request fields for each resource are automatically generated upon sending a request.

In each respective tab, you can edit or delete any field. If you click the Edit icon, the following configuration window is displayed:

In the Response/Request fields tab, the following options are also available:

• Overwrite on send request checkbox - If selected, when you execute a Send Request, the fields list is regenerated. Do not select this option if you added new fields to your resource.

• Additional options button:

  Option	What it does
  Update response root key	Define the response key when dealing with nested arrays in the response.
  Delete all fields for method	Deletes all fields for the selected method.
  Generate from payload	Use a sample payload from the service documentation or an API call to generate the resource fields.

• Add row button - Adds new fields to the resource.

Click the Visible columns icon to add or delete columns in the fields table.

Each color under the Methods column corresponds to a certain method: Get, Get by ID, Post, Put, Patch, Delete.

Pagination

Enable Pagination for a resource if you expect a list response. If you enable pagination, you also need to define the Response root key in the configuration tab, for nested lists.

Search

Activate the Enable Search checkbox to allow search setup for a resource.

After you configure everything you need, you can continue with Publishing your connector.