Connectors Settings Configuration

Overview

When creating a connector, you can define custom settings fields that will automatically generate user-friendly forms for your integration. This guide shows you all the possibilities for creating powerful, flexible configuration interfaces.

What You Can Build

• Simple text inputs for API keys, URLs, usernames
• Dropdown menus for selecting options like regions or modes
• Toggle switches for enabling/disabling features
• Date pickers for scheduling and time-based settings
• Rich text editors for custom code or JSON configuration
• Dynamic collections for managing multiple items (warehouses, credentials, etc.)
• Smart selectors for choosing integrations, locations, or products
• Secure fields for passwords and sensitive data

Getting Started

Basic Field Structure

Every field you create has these essential parts:

1. Field Name (Path): A unique identifier for your field (e.g., "apiKey", "settings.timeout")
2. Data Type: What kind of data the field stores (text, number, true/false, etc.)
3. Display Options: How the field appears to users (label, help text, input type)
4. Validation Rules: Requirements the user input must meet

Quick Example

Here's a simple API key field:

{
  "path": "apiKey",
  "type": "string",
  "secret": true,
  "options": {
    "label": "API Key",
    "placeholder": "Enter your API key here",
    "helperText": "You can find this in your account settings",
    "component": "text"
  }
}

This creates a password-protected text input with helpful guidance for users.

How Fields Appear in the UI

Your field configurations automatically become professional-looking forms with:

• Clear labels and descriptions
• Appropriate input types (text boxes, dropdowns, toggles)
• Built-in validation and error messages
• Helpful tooltips and guidance
• Responsive design that works on all devices

Field Organization

Fields can be organized into different sections:

• Connection Setup: Essential fields shown during initial setup
• Common Settings: Standard fields shared across many connectors
• Advanced Settings: Connector-specific detailed configuration

Field Types

Choose the right data type for your field based on what kind of information you're collecting:

Text Fields (type: "string")

For collecting text-based information:

• API keys and tokens
• URLs and endpoints
• Usernames and account names
• Descriptions and notes
• Configuration values

Example Use Cases:

• Store URL: https://mystore.shopify.com
• API Key: sk_test_abc123...
• Region: us-east-1

Number Fields (type: "number")

For numeric values and settings:

• Timeouts and delays
• Limits and thresholds
• Port numbers
• Quantities and counts

Example Use Cases:

• Connection timeout: 30 (seconds)
• Rate limit: 1000 (requests per hour)
• Port: 8080

True/False Fields (type: "boolean")

For on/off switches and yes/no options:

• Feature toggles
• Enable/disable settings
• Permission flags
• Default behaviors

Example Use Cases:

• Enable logging: true/false
• Use sandbox mode: true/false
• Auto-sync enabled: true/false

Date/Time Fields (type: "date")

For scheduling and time-based configuration:

• Sync schedules
• Cutoff dates
• Business hours

Example Use Cases:

• Last sync date: 2024-01-15T10:30:00Z
• Business start time: 09:00

List Fields (type: "array")

For multiple values or collections:

• Tags and categories
• Multiple locations
• List of permissions
• Multiple credentials

Example Use Cases:

• Product tags: ["electronics", "mobile", "accessories"]
• Warehouse locations: Multiple warehouse configurations

Complex Data (type: "json")

For advanced configuration requiring structured data:

• Custom field mappings
• Advanced API configurations
• Complex business rules

Example Use Cases:

• Field mapping: {"external_name": "internal_name"}
• Custom API headers: {"Authorization": "Bearer token"}

Input Components

Choose the right input component to create the best user experience for your field:

Basic Text Inputs

Text Input (component: "text")

• Single line text entry
• Perfect for: API keys, URLs, usernames, simple settings
• Shows: Text box with placeholder and help text

Multi-line Text (component: "textarea")

• Multiple lines of text
• Perfect for: Descriptions, notes, custom instructions
• Shows: Expandable text area

Search Input (component: "search-input"))

• Text input with search suggestions
• Perfect for: Finding products, locations, or other searchable items
• Shows: Text box with dropdown suggestions

Selection Inputs

Dropdown Menu (component: "select")

• Choose one option from a list
• Perfect for: Countries, regions, modes, statuses
• Shows: Dropdown menu with predefined options

Multi-Select (component: "multiselect")

• Choose multiple options from a list
• Perfect for: Categories, permissions, features to enable
• Shows: Dropdown that allows multiple selections

Radio Buttons (component: "radio")

• Choose one option with all choices visible
• Perfect for: Payment methods, sync frequencies (when few options)
• Shows: List of radio button options

On/Off Controls

Toggle Switch (component: "switch")

• Enable or disable a feature
• Perfect for: Feature toggles, enable/disable settings
• Shows: Professional toggle switch

Checkbox (component: "checkbox")

• Simple yes/no or accept/decline
• Perfect for: Accepting terms, enabling optional features
• Shows: Checkable box with label

Date and Time

Date/Time Picker (component: "datetime")

• Select dates and times
• Perfect for: Sync schedules, cutoff dates, business hours
• Shows: Calendar picker with time selection

Smart Selectors

Integration Picker (component: "integration")

• Choose from existing integrations
• Perfect for: Source integrations, related connections
• Shows: Dropdown of user's integrations

Location Picker (component: "location")

• Choose from defined locations
• Perfect for: Warehouse selection, shipping locations
• Shows: Dropdown of available locations

Product Picker (component: "product")

• Choose from product catalog
• Perfect for: Default products, product mappings
• Shows: Searchable product selector

Advanced Inputs

Tag List (component: "text-array")

• Add multiple text items as tags
• Perfect for: Categories, keywords, permissions
• Shows: Tag input with add/remove functionality

JSON Editor (component: "json")

• Edit structured data
• Perfect for: Custom mappings, advanced configurations
• Shows: Code editor with JSON syntax highlighting

Code Editor (component: "javascript")

• Write custom code or scripts
• Perfect for: Custom transformations, business logic
• Shows: Code editor with syntax highlighting

Template Editor (component: "handlebars")

• Edit text templates
• Perfect for: Email templates, custom formatting
• Shows: Code editor optimized for templates

Dynamic Collections

Collection Manager (component: "collection")

• Manage lists of related items
• Perfect for: Multiple credentials, warehouse configurations, custom rules
• Shows: Add/remove interface for managing multiple items

Each collection item can contain multiple fields of any type, creating powerful nested configuration options.

Field Organization

Organize your fields to create a smooth user experience:

Connection Setup vs Detailed Settings

Quick Setup Fields (wizard: true)

• Essential fields needed to establish the connection
• Shown during initial connector setup
• Keep this minimal - only what's absolutely required
• Examples: API key, server URL, account credentials

Detailed Settings (wizard: false or not specified)

• Advanced configuration options
• Shown in the full settings page after connection is established
• Can include complex options and fine-tuning
• Examples: Sync frequency, field mappings, advanced features

Shared vs Connector-Specific Settings

Common Settings (common: true)

• Standard fields used by many connectors
• Displayed in a "Connection Flow" section
• Reusable across different connector types
• Examples: OAuth client ID/secret, basic authentication

Connector-Specific Settings (common: false or not specified)

• Unique to your particular connector
• Displayed in sections specific to your connector
• Custom to your service's requirements
• Examples: Your API endpoints, service-specific options

Security & Access

Secure Fields (secret: true)

• Sensitive information that needs protection
• Automatically encrypted when stored
• Displayed as password fields (hidden input)
• Never shown in logs or exports
• Examples: API keys, passwords, authentication tokens

Read-Only Fields (readonly: true)

• Information displayed to users but cannot be edited
• Useful for showing computed values or system status
• Examples: Account status, last sync time, calculated values

Hidden Fields (hidden: true)

• Not shown to users but stored in configuration
• Used for internal settings or conditional logic
• Examples: Internal IDs, feature flags, system configuration

Validation & Security

Input Validation

Ensure users enter correct data with built-in validation rules:

Required Fields

• Make fields mandatory for connection
• Shows error if left empty
• Use for essential configuration

Text Length Limits

• Set minimum/maximum character limits
• Prevents too short or too long inputs
• Good for passwords, descriptions

Number Ranges

• Set minimum/maximum values
• Prevents invalid numeric inputs
• Good for timeouts, limits, ports

Format Validation

• Use patterns to validate specific formats
• Examples: email addresses, URLs, phone numbers
• Provides immediate feedback to users

Custom Validation Messages

• Write clear, helpful error messages
• Tell users exactly what's wrong and how to fix it
• Use friendly, non-technical language

Security Features

Automatic Encryption

• Fields marked as secret: true are automatically encrypted
• Stored securely in the database
• Never exposed in logs or API responses

Secure Input Display

• Secret fields show as password inputs (dots instead of text)
• Users can toggle visibility when needed
• Prevents shoulder surfing and accidental exposure

Access Control

• Read-only fields prevent accidental changes
• Hidden fields keep internal settings private
• Granular control over what users can see and edit

Common Configuration Examples

Example 1: Simple API Key Setup

Perfect for services that just need an API key to connect:

{
  "path": "apiKey",
  "type": "string",
  "secret": true,
  "options": {
    "label": "API Key",
    "placeholder": "sk_live_...",
    "helperText": "Find this in your account dashboard under API Settings",
    "component": "text",
    "wizard": true
  },
  "validation": [
    {
      "type": "required",
      "message": "API key is required to connect"
    }
  ]
}

What users see: A password field with clear instructions on where to find their API key.

Example 2: E-commerce Store Connection

For connecting to an online store with customizable sync options:

[
  {
    "path": "storeUrl",
    "type": "string",
    "options": {
      "label": "Store URL",
      "placeholder": "https://mystore.shopify.com",
      "component": "text",
      "wizard": true,
      "helperText": "The main URL for your online store"
    },
    "validation": [
      {
        "type": "required",
        "message": "Store URL is required"
      }
    ]
  },
  {
    "path": "syncFrequency",
    "type": "string",
    "options": {
      "label": "How often should we sync?",
      "component": "select",
      "defaultValue": "hourly",
      "values": [
        {"label": "Every 15 minutes", "value": "15min"},
        {"label": "Every hour", "value": "hourly"},
        {"label": "Every 6 hours", "value": "6hourly"},
        {"label": "Once daily", "value": "daily"}
      ]
    }
  },
  {
    "path": "enableRealTime",
    "type": "boolean",
    "options": {
      "label": "Enable real-time updates",
      "component": "switch",
      "helperText": "Get instant notifications when orders change",
      "defaultValue": false
    }
  }
]

What users see: A simple form asking for their store URL, sync preferences, and real-time options.

Example 3: Multiple Warehouse Management

For services that need to manage multiple physical locations:

{
  "path": "warehouses",
  "type": "array",
  "options": {
    "component": "collection",
    "label": "Warehouse Locations",
    "helperText": "Add all your warehouse or fulfillment center locations",
    "fields": [
      {
        "path": "name",
        "type": "string",
        "options": {
          "label": "Warehouse Name",
          "component": "text",
          "placeholder": "Main Warehouse"
        }
      },
      {
        "path": "address",
        "type": "string",
        "options": {
          "label": "Address",
          "component": "textarea",
          "placeholder": "Full warehouse address"
        }
      },
      {
        "path": "isDefault",
        "type": "boolean",
        "options": {
          "label": "Primary warehouse",
          "component": "checkbox",
          "helperText": "Orders will be fulfilled from here by default"
        }
      }
    ]
  }
}

What users see: An interface to add multiple warehouses, with an "Add Warehouse" button and forms for each location.

Example 4: Advanced Configuration

For services that need complex, custom configuration:

{
  "path": "fieldMapping",
  "type": "json",
  "options": {
    "label": "Custom Field Mapping",
    "component": "json",
    "helperText": "Map your system's fields to our standard format",
    "defaultValue": {
      "product_name": "title",
      "product_price": "price",
      "product_sku": "sku"
    }
  }
}

What users see: A code editor with syntax highlighting where they can define custom field mappings.

Example 5: OAuth Setup (Common Fields)

For services using OAuth authentication (reusable across connectors):

[
  {
    "path": "clientId", 
    "type": "string",
    "options": {
      "label": "Client ID",
      "component": "text",
      "common": true,
      "wizard": true,
      "helperText": "From your app's OAuth settings"
    }
  },
  {
    "path": "clientSecret",
    "type": "string", 
    "secret": true,
    "options": {
      "label": "Client Secret",
      "component": "text",
      "common": true,
      "wizard": true,
      "helperText": "Keep this secret and secure"
    }
  }
]

What users see: Standard OAuth fields that appear consistently across all OAuth-enabled connectors.

Advanced Features

Dynamic Collections

Create powerful interfaces for managing multiple related items:

Use Cases:

• Multiple API credentials for different environments
• Several warehouse or location configurations
• Custom business rules or mappings
• Multi-step workflows

How it works:

• Users see an "Add Item" button
• Each item has its own set of fields
• Items can be reordered, edited, or removed
• Perfect for variable-length configuration

Conditional Logic

Fields can be shown or hidden based on other field values:

Examples:

• Show advanced options only when "Advanced Mode" is enabled
• Display different fields based on selected integration type
• Hide irrelevant settings based on user choices

Default Values and Pre-filling

Make setup easier with smart defaults:

Pre-filled values:

• Common settings based on connector type
• Suggested values based on best practices
• User's previous configurations

Dynamic defaults:

• Values calculated from other fields
• API-driven suggestions
• Environment-specific defaults

Help and Documentation

Guide users with contextual assistance:

Helper Text:

• Brief explanations under each field
• Links to relevant documentation
• Examples of valid input formats

Rich Documentation:

• Markdown-formatted help sections
• Step-by-step setup guides
• Troubleshooting tips

Field Grouping

Organize complex forms into logical sections:

Visual Organization:

• Group related fields together
• Create tabbed interfaces for different categories
• Collapsible sections for optional settings

Progressive Disclosure:

• Show basic options first
• Reveal advanced options on demand
• Guided setup flows

Best Practices

Creating User-Friendly Forms

Use Clear, Simple Language

• Write labels that non-technical users can understand
• Avoid jargon and technical terms
• Use action-oriented language ("Enable notifications" vs "Notification flag")

Provide Helpful Guidance

• Include placeholder text showing the expected format
• Add helper text explaining where to find required information
• Use examples to clarify complex fields

Organize Logically

• Group related fields together
• Put the most important fields first
• Use progressive disclosure for advanced options

Make Forms Forgiving

• Provide clear error messages that explain how to fix problems
• Use validation to prevent common mistakes
• Allow users to go back and edit previous steps

Field Naming and Structure

Choose Meaningful Field Names

• Use descriptive paths like "storeUrl" instead of "url1"
• Keep names consistent across similar connectors
• Avoid deeply nested structures when possible

Plan Your Field Hierarchy

• Group settings into logical sections
• Use collections for repeating data structures
• Keep wizard fields minimal and essential

Security Best Practices

Protect Sensitive Information

• Always mark credentials as secret fields
• Use secure default values for testing/sandbox modes
• Never include real credentials in examples or documentation

Validate User Input

• Require essential fields for connection
• Validate formats (URLs, emails, etc.)
• Provide immediate feedback on invalid input

Performance and User Experience

Keep Forms Fast and Responsive

• Minimize the number of fields shown initially
• Use progressive enhancement for advanced features
• Load heavy components (like code editors) only when needed

Design for Different Users

• Provide both simple and advanced configuration options
• Use sensible defaults to minimize required input
• Make forms accessible to users with disabilities

Testing Your Configuration

Validate Your Setup

• Test all field types and validation rules
• Verify that error messages are helpful and clear
• Check that secret fields are properly encrypted

User Testing

• Have real users try your connector setup
• Watch for confusion or repeated errors
• Iterate based on user feedback

Field Reference

Required Properties

Every field must have these basic properties:

Optional Properties

Display Options (options object)

Organization Options

Validation Rules (validation array)

Selection Options (values array for dropdowns)

For select and multiselect components, provide options:

"values": [
  {"label": "United States", "value": "US"},
  {"label": "Canada", "value": "CA"},
  {"label": "United Kingdom", "value": "UK"}
]

Collection Fields (component: "collection")

For managing multiple items, use nested field definitions:

{
  "component": "collection",
  "fields": [
    {
      "path": "name",
      "type": "string",
      "options": {"label": "Name", "component": "text"}
    },
    {
      "path": "value", 
      "type": "string",
      "options": {"label": "Value", "component": "text"}
    }
  ]
}

Complete Field Example

{
  "path": "syncSettings.frequency",
  "type": "string",
  "options": {
    "label": "Sync Frequency",
    "helperText": "How often should we check for new data?",
    "component": "select", 
    "defaultValue": "hourly",
    "wizard": false,
    "values": [
      {"label": "Every 15 minutes", "value": "15min"},
      {"label": "Every hour", "value": "hourly"},
      {"label": "Every 6 hours", "value": "6hourly"},
      {"label": "Once daily", "value": "daily"}
    ]
  },
  "validation": [
    {
      "type": "required",
      "message": "Please select a sync frequency"
    }
  ]
}

Remember

• Start simple with essential fields in the wizard
• Use clear, non-technical language in labels and help text
• Test your configuration with real users
• Mark sensitive fields as secret
• Provide helpful validation messages

For questions or support, please consult the examples in this guide or reach out to the development team.