---
title: Designing a Connector
slug: designing-a-connector
createdAt: 2025-10-29T21:29:32.745Z
---

A connector design defines how data will be matched, imported, and acted upon. This section outlines how to plan and structure a connector before creating it in Activate.

# Key Design Concepts

A connector consists of:

1. **Schema** — Defines what data looks like and how changes are detected. 
2. **Workflow** — Controls how imports and processing occur. 
3. **Handlers** — Define what happens when data changes. 

Each connector should have:

- A unique name 
- A defined source of truth (HR, CMDB, SQL, etc.) 
- Clearly identified key fields (for uniqueness) 
- A delete strategy (how removed records are identified) 

# Choosing a Key

Select a **unique and stable identifier** from the source system (for example, employeeNumber, departmentCode, or ticketNumber).

Mark one column in the schema as the key:

:::BlockQuote
\<column name="employeeNumber" type="varchar(20)" default="''" key="1" />
:::

# Delete Strategy

Two supported patterns exist for handling deletes:

## Option 1 — Result-set Deletes (Recommended)

Only import *current* rows. Any previously imported rows missing from the current import are marked as deleted automatically.

**Example**

:::BlockQuote
SELECT \* FROM Employees WHERE IsActive = 1
:::

## Option 2 — Flagged Deletes

Import *all* rows, including deleted ones, and mark the condition in your schema:

:::BlockQuote
\<deleteCondition>$IMPORT$.Status = 'Deleted'\</deleteCondition>
:::

# Planning for History

Activate automatically logs every detected change into a history table by default.  The history table is specified in the schema like this

:::BlockQuote
\<historyTable enable="true">Employee\_History\</historyTable>
:::

This allows complete auditing of data changes and rollback validation.

This functionality can be disabled by setting enable="false" on the historyTable node in the schema.  The value of the setting can be blank as no history table will be generated.  This does require a regeneration of the schema.

:::BlockQuote
\<historyTable enable="false">\</historyTable>
:::

# Example Connector Lifecycle

1. **Import** data into the import table.&#x20;
2. **Compare** import with current data.&#x20;
3. **Detect** changes (create, update, delete).&#x20;
4. **Process** each change through the selected change handler.&#x20;
5. **Trigger** actions such as job submissions, notifications, or publishing.&#x20;