Sync

Data Sync Protocol - LEVEL 1: Simple Synchronization

Inspired by Salesforce Connect, Segment Sync, and Census Reverse ETL.

Positioning in 3-Layer Architecture:

• L1: Simple Sync (THIS FILE) - Business users - Sync Salesforce to Sheets

• L2: ETL Pipeline (automation/etl.zod.ts) - Data engineers - Aggregate 10 sources to warehouse

• L3: Enterprise Connector (integration/connector.zod.ts) - System integrators - Full SAP integration

Data sync provides bidirectional or unidirectional data synchronization

between ObjectStack and external systems, maintaining data consistency

across platforms.

SCOPE: Simple field mappings only. NO complex transformations.

For complex transformations (joins, aggregates, custom SQL), use ETL Pipeline (Level 2).

When to Use This Layer

Use Simple Sync when:

• Syncing 1:1 fields between two systems

• Simple field transformations (uppercase, cast, etc.)

• No complex logic required

• Business users need to configure integrations

Examples:

• Salesforce Contact ↔ Google Sheets

• HubSpot Company ↔ CRM Account

• Shopify Orders → Accounting System

When to upgrade:

• Need multi-source joins → Use ETL Pipeline

• Need complex authentication/webhooks → Use Enterprise Connector

• Need aggregations or data warehousing → Use ETL Pipeline

@see ./etl.zod.ts for Level 2 (data engineering)

@see ../integration/connector.zod.ts for Level 3 (enterprise integration)

Use Cases

1. CRM Integration

• Sync contacts between ObjectStack and Salesforce

• Keep opportunity data synchronized

• Bidirectional updates

2. Customer Data Platform (CDP)

• Sync user profiles to Segment

• Enrichment data from Clearbit

• Marketing automation sync

3. Operational Analytics

• Sync production data to analytics warehouse

• Real-time dashboards

• Business intelligence

@see https://help.salesforce.com/s/articleView?id=sf.platform_connect_about.htm

@see https://segment.com/docs/connections/sync/

@see https://www.getcensus.com/

@example

const contactSync: DataSyncConfig = \{

name: 'salesforce_contact_sync',

label: 'Salesforce Contact Sync',

source: \{

object: 'contact',

filters: \{ status: 'active' \}

\},

destination: \{

connector: 'salesforce',

operation: 'upsert_contact',

mapping: \{

first_name: 'FirstName',

last_name: 'LastName',

email: 'Email'

\}

\},

syncMode: 'incremental',

schedule: '0 * * * *' // Hourly

\}

TypeScript Usage

import { DataDestinationConfig, DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation';
import type { DataDestinationConfig, DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation';

// Validate data
const result = DataDestinationConfig.parse(data);

DataDestinationConfig

Properties

DataSourceConfig

Properties

SyncDirection

Allowed Values

• push
• pull
• bidirectional

SyncExecutionResult

Properties

SyncExecutionStatus

Allowed Values

• pending
• running
• completed
• partial
• failed
• cancelled

SyncMode

Allowed Values

• full
• incremental
• realtime