Connector Management
Connectors are the data pipelines that feed external systems into GTM Clarity's canonical schema. The platform supports five connector types, each normalizing source data into a unified format for scoring.
Supported Connectors
| Connector | Type Key | Auth Method | Data Synced |
|---|---|---|---|
| Salesforce | salesforce | OAuth 2.0 (Web Server Flow) | Accounts, Contacts, Leads, Opportunities, Activities |
| Customer.io | customerio | API Key | People, Email events, Behavioral events |
| Delivr.ai | delivrai | API Key | Intent signals, Company enrichment |
| Office 365 | o365 | OAuth 2.0 (Microsoft Graph) | Email metadata (privacy-first, no body content) |
| Fathom.video | fathom | API Key | Meeting transcripts, Participants, Sentiment |
Each tenant can have at most one connector per type. This is enforced by a unique index on (tenant_id, type) in the connectors table.
Adding a Connector
Step 1: Navigate to Connector Settings
Go to Settings > Connectors and click Add Connector. Select the connector type you want to add.
Step 2: Authenticate
For OAuth-based connectors (Salesforce, O365):
- Click Connect to initiate the OAuth flow
- You will be redirected to the external service to authorize access
- After granting access, you are redirected back to GTM Clarity
- Tokens are encrypted with AES-256-GCM and stored securely
For API key-based connectors (Customer.io, Delivr.ai, Fathom):
- Enter your API key in the configuration form
- Click Verify to test the connection
- The key is encrypted before storage
Step 3: Configure Field Mappings
After authentication, review and customize the field mappings. Each connector provides sensible defaults, but you can override them. See Field Mapping Configuration for details.
Step 4: Set Sync Schedule
Syncs are orchestrated by Temporal workflows. The default schedule runs incremental syncs every 4 hours. Admins can:
- Trigger a manual sync at any time
- Configure the cron schedule per connector
- Request a full sync (re-imports all data)
Connector Table Schema
The connectors table stores all connector instances:
| Column | Type | Description |
|---|---|---|
id | text (UUID) | Primary key |
tenant_id | text | Tenant scope |
type | text | Connector type (salesforce, customerio, delivrai, o365, fathom) |
name | text | Display name |
config | jsonb | Encrypted configuration (tokens, keys, settings) |
status | text | disconnected, connected, syncing, error |
last_sync_at | timestamptz | Timestamp of last successful sync |
last_sync_cursor | text | Pagination cursor for incremental sync |
last_sync_error | text | Error message from last failed sync |
field_mappings | jsonb | Legacy field mappings (see field_mappings table) |
Token Encryption
All OAuth tokens and API keys are encrypted at rest using AES-256-GCM:
- Encryption key is stored in the
CONNECTOR_ENCRYPTION_KEYenvironment variable - The key must be a 32-byte hex string (64 hex characters)
- Generate a key:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" - Tokens are decrypted only at runtime when a sync or authentication is needed
- Encrypted tokens are never logged or returned in API responses
Never commit the CONNECTOR_ENCRYPTION_KEY to source control. If the key is lost, all stored tokens become unrecoverable and connectors must be re-authenticated.
Monitoring Sync Health
Sync Status Indicators
| Status | Meaning |
|---|---|
connected | Connector is authenticated and idle |
syncing | A sync workflow is currently running |
error | The last sync encountered an error |
disconnected | Connector has not been authenticated |
Sync Logs
Every sync operation is recorded in the sync_logs table:
| Column | Type | Description |
|---|---|---|
sync_type | text | full or incremental |
status | text | running, completed, failed |
started_at | timestamptz | When the sync began |
completed_at | timestamptz | When the sync finished |
records_created | integer | New records imported |
records_updated | integer | Existing records updated |
records_failed | integer | Records that failed to import |
error_message | text | Error details if failed |
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
Status stuck on syncing | Temporal workflow timed out | Check Temporal UI for failed workflows; trigger manual sync |
error with auth message | Token expired or revoked | Re-authenticate the connector via OAuth |
| Low record counts | Incremental cursor stale | Trigger a full sync to reset the cursor |
| Missing fields | Field mapping misconfigured | Review mappings in Field Mapping Configuration |
Sync Workflow Architecture
The workflow includes a dead letter pattern -- if a batch fails to write after 3 retries, the failure is logged and the sync continues with the next batch.
O365 Special Configuration
The O365 connector has additional privacy controls stored in the o365_config table:
| Setting | Description |
|---|---|
dpa_accepted_at | Data Processing Agreement acceptance timestamp (sync blocked if null) |
allowed_domains | Domain allowlist for email metadata extraction (empty = most restrictive) |
tenant_o365_domain | Tenant's own domain (always excluded from ingestion) |
The O365 connector extracts metadata only (sender, recipient, timestamps) -- it never reads email body content. The DPA must be accepted before any sync can proceed.
Related Pages
- Field Mapping Configuration -- Customizing source-to-canonical mappings
- Temporal Workflows -- Workflow orchestration details
- Environment Setup -- Required environment variables
- Audit Logs -- Connector operation audit trail