Skip to content

Creating a Connector

This guide walks you through creating a new connector using the Connector Builder UI. By the end, you will have a working connector template ready for testing and publishing.

Before You Begin

To create a connector, you need:

  • Platform Admin role (or Enterprise Admin with SDK access enabled)
  • The external system's API documentation
  • Understanding of the system's authentication method
  • Optionally: sample API credentials for testing

Step 1: Start a New Connector

  1. Navigate to the Connector SDK page
  2. Click Create Connector
  3. The Connector Builder opens with a tabbed interface

Step 2: Overview Tab

Configure the connector's identity:

Field Description Example
Name Display name for the connector "OpenWeatherMap"
Slug URL-safe identifier (auto-generated from name) openweathermap
Type Category of the system General, OEM, DMS, CRM, Finance, Telematics, Logistics
Description What the connector does "Weather data for any location worldwide"
Base URL The root URL for all API calls https://api.openweathermap.org
Icon Upload a system icon (PNG/SVG, 64x64 recommended)
Documentation URL Link to the external system's API docs https://openweathermap.org/api

Choosing a Slug

The slug is used in URLs, configuration references, and API calls. Choose something short, lowercase, and descriptive. It cannot be changed after the connector is published.

Step 3: Auth & Credentials Tab

Configure how the connector authenticates with the external system.

Select Auth Type

Auth Type When to Use
None Public APIs that require no authentication
API Key APIs that use a key in a header or query parameter
Basic Auth APIs that use HTTP Basic Authentication (username/password)
OAuth2 APIs that use OAuth2 client credentials or authorization code
Bearer Token APIs that accept a static bearer token

Configure Credential Schema

For each credential field the user must provide, define:

Property Description
Field Name Internal name (e.g., api_key, client_id)
Display Label What the user sees (e.g., "API Key", "Client ID")
Type string or password (password fields are masked in the UI)
Required Whether the field must be provided
Sensitive Whether the value should be encrypted (always true for secrets)
Help Text Instructions for the user (e.g., "Find your API key at Settings > API Access")

Example: API Key Configuration

auth_type: api_key
credential_schema:
  api_key:
    label: "API Key"
    type: password
    required: true
    sensitive: true
    help: "Get your API key from your OpenWeatherMap account settings"
header_name: "X-API-Key"
key_prefix: ""

Example: OAuth2 Configuration

auth_type: oauth2
credential_schema:
  client_id:
    label: "Client ID"
    type: string
    required: true
    sensitive: false
  client_secret:
    label: "Client Secret"
    type: password
    required: true
    sensitive: true
  token_url:
    label: "Token URL"
    type: string
    required: true
    sensitive: false
    default: "https://auth.example.com/oauth/token"
grant_type: client_credentials
scopes: "read write"

Step 4: Operations Tab

Define the API operations that the connector exposes.

Adding an Operation

Click Add Operation and configure:

Field Description Example
Name Operation identifier get_current_weather
Display Name Human-readable name "Get Current Weather"
Description What the operation does "Returns current weather for a location"
HTTP Method GET, POST, PUT, DELETE, PATCH GET
Path URL path (appended to base URL) /data/2.5/weather

Defining Parameters

For each parameter the operation accepts:

Property Description
Name Parameter name (matches the API's expected name)
Location Where the parameter goes: query, path, header, or body
Type Data type: string, number, integer, boolean
Required Whether the parameter must be provided
Default Default value (if not required)
Description What the parameter does

Example: Weather by City

operation: get_current_weather
method: GET
path: /data/2.5/weather
parameters:
  - name: q
    location: query
    type: string
    required: true
    description: "City name (e.g., 'London' or 'London,UK')"
  - name: units
    location: query
    type: string
    required: false
    default: "metric"
    description: "Units: standard, metric, or imperial"

Defining Response Schema

Optionally, define the expected response structure. This helps with:

  • Auto-generating field mapping suggestions
  • Validating responses during testing
  • Documenting what the operation returns
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "description": "City name" },
    "main": {
      "type": "object",
      "properties": {
        "temp": { "type": "number", "description": "Temperature" },
        "humidity": { "type": "integer", "description": "Humidity %" }
      }
    }
  }
}

Step 5: Resilience Tab

Configure how the connector handles failures:

Setting Description Default
Timeout (seconds) How long to wait for a response 30
Max Retries Number of retry attempts on failure 3
Retry Delay (seconds) Initial delay between retries 1
Retry Backoff Backoff strategy: None, Linear, Exponential Exponential
Rate Limit (per minute) Maximum requests per minute 60
Circuit Breaker Threshold Consecutive failures before opening the circuit 5
Circuit Breaker Recovery (seconds) Time to wait before testing the circuit again 30

Circuit Breaker

The circuit breaker protects both DIBOP and the external system when failures are persistent:

Closed (normal) → Open (after N failures) → Half-Open (test) → Closed
                                                  ↓
                                             Open (if test fails)

When the circuit is open:

  • Requests fail immediately without calling the external system
  • The connection's health status changes to "degraded"
  • After the recovery period, a single test request is allowed
  • If the test succeeds, the circuit closes and normal operation resumes

Step 6: Save and Test

  1. Click Save to save the connector template as a Draft
  2. Click Test to open the testing panel
  3. Enter test credentials (if the auth type requires them)
  4. Test each operation individually
  5. Review the responses

See Connector Builder for details on the testing workflow.

Step 7: Publish

Once testing is complete:

  1. Click Publish to make the connector available
  2. Choose the scope:
    • Catalogue (Platform Admin): Available to all enterprises
    • Enterprise (Enterprise Admin): Available only to your enterprise
  3. Confirm the publication

See Publishing Connectors for the full publishing workflow.

Next Steps