twenty-migrate-salesforce

v1.0.0

Published

a month ago

CLI migration tool for Salesforce to Twenty CRM

0High
0Medium
0Low

deliveredbyai

twenty crm salesforce migration cli data-migration jsforce soql

Twenty Salesforce Migration Tool

CLI migration tool for Salesforce to Twenty CRM.

Installation

npm install -g twenty-migrate-salesforce

Usage

Basic Migration

twenty-migrate-salesforce \
  --login-url https://login.salesforce.com \
  --username YOUR_SALESFORCE_USERNAME \
  --password YOUR_SALESFORCE_PASSWORD \
  --security-token YOUR_SALESFORCE_SECURITY_TOKEN \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY

Dry Run (Preview)

twenty-migrate-salesforce \
  --login-url https://login.salesforce.com \
  --username YOUR_SALESFORCE_USERNAME \
  --password YOUR_SALESFORCE_PASSWORD \
  --security-token YOUR_SALESFORCE_SECURITY_TOKEN \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY \
  --dry-run

Select Objects

twenty-migrate-salesforce \
  --login-url https://login.salesforce.com \
  --username YOUR_SALESFORCE_USERNAME \
  --password YOUR_SALESFORCE_PASSWORD \
  --security-token YOUR_SALESFORCE_SECURITY_TOKEN \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY \
  --objects contacts,accounts

Features

Salesforce API Integration - jsforce library with SOQL support
Paginated Extraction - Handle large datasets efficiently
Schema Mapping - Salesforce → Twenty CRM field mapping
Batch Processing - Process records in configurable batches
Progress Tracking - Real-time migration progress
Dry Run Mode - Preview migration without changes
Error Handling - Detailed error logging and recovery
Duplicate Prevention - Check for existing records

Migration Mapping

| Salesforce | Twenty | |------------|--------| | Contact → FirstName, LastName, Email, Phone | people → name, email, phone | | Account → Name, Website, Industry | companies → name, website, industry | | Opportunity → Name, Amount, CloseDate, StageName | opportunities → name, amount, stage | | Note → Body, ParentId | notes → body, associations |

What Migrates

✅ Supported Objects:

Contacts → People (name, email, phone, account association)
Accounts → Companies (name, website, industry, description)
Opportunities → Opportunities (name, amount, close date, stage)
Notes → Notes (content, associations to parent objects)

❌ What Doesn't Migrate:

Custom fields and objects
File attachments
Activity history and logs
Campaigns and leads
Reports and dashboards
Users and owners
Workflow rules and processes

Command Line Options

Options:
  -l, --login-url <url>         Salesforce login URL (required)
  -u, --username <username>     Salesforce username (required)
  -p, --password <password>     Salesforce password (required)
  -t, --security-token <token>  Salesforce security token (required)
  -w, --twenty-url <url>        Twenty CRM URL (required)
  -k, --twenty-key <key>        Twenty CRM API key (required)
  -d, --dry-run                 Preview migration without writing data
  -o, --objects <objects>       Objects to migrate (comma-separated)
  -b, --batch <number>          Batch size for API calls (default: 60)
  -h, --help                    Show help
  -v, --version                 Show version

Environment Variables

Create a .env file:

# Salesforce API Configuration
SALESFORCE_LOGIN_URL=https://login.salesforce.com
SALESFORCE_USERNAME=your_salesforce_username
SALESFORCE_PASSWORD=your_salesforce_password
SALESFORCE_SECURITY_TOKEN=your_salesforce_security_token

# Twenty CRM Configuration
TWENTY_URL=http://localhost:3000
TWENTY_API_KEY=your_twenty_api_key_here

# Migration Settings
BATCH_SIZE=60
RATE_LIMIT_DELAY=600
DRY_RUN=false
OBJECTS=contacts,accounts,opportunities,notes

Salesforce Setup

1. Get Security Token

Login to Salesforce
Go to Setup → Users → Users
Click your username
Click "Reset Security Token"
Check your email for the security token

2. Enable API Access

Go to Setup → Manage Users → Profiles
Select your profile
Enable "API Enabled" permission

3. Test API Access

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  https://your-instance.salesforce.com/services/data/v56.0/query?q=SELECT+Id+FROM+Account+LIMIT+1

Rate Limiting

Salesforce API: 100 requests per minute
Automatic delay: 600ms between requests
Batch processing: 60 records per batch
Retry mechanism: Automatic retry on failures

Reports

Migration Report

{
  "timestamp": "2026-04-04T14:30:00.000Z",
  "migration": {
    "tool": "twenty-migrate-salesforce",
    "version": "1.0.0",
    "objects": ["contacts", "accounts", "opportunities", "notes"],
    "dryRun": false
  },
  "summary": {
    "total": 1000,
    "success": 985,
    "errors": 15,
    "successRate": "98.50%"
  },
  "objectResults": {
    "people": {
      "attempted": 500,
      "success": 495,
      "errors": 5,
      "successRate": "99.00%"
    },
    "companies": {
      "attempted": 200,
      "success": 198,
      "errors": 2,
      "successRate": "99.00%"
    },
    "opportunities": {
      "attempted": 150,
      "success": 147,
      "errors": 3,
      "successRate": "98.00%"
    },
    "notes": {
      "attempted": 150,
      "success": 145,
      "errors": 5,
      "successRate": "96.67%"
    }
  },
  "errors": [],
  "recommendations": []
}

Error Log

Batch 1 (people): Duplicate email detected - [email protected]
Batch 2 (companies): Invalid industry format - "Tech & IT"
Batch 3 (opportunities): Invalid amount format - "$50,000"

Examples

Large Dataset Migration

twenty-migrate-salesforce \
  --login-url https://login.salesforce.com \
  --username [email protected] \
  --password yourpassword \
  --security-token 1234567890ABCDEF \
  --twenty-url https://your-company.twenty.com \
  --twenty-key twenty_api_key_1234567890 \
  --batch 30 \
  --objects contacts,accounts,opportunities

Test Migration

twenty-migrate-salesforce \
  --login-url https://test.salesforce.com \
  --username [email protected] \
  --password testpassword \
  --security-token TEST1234567890ABCDEF \
  --twenty-url http://localhost:3000 \
  --twenty-key twenty_api_key_1234567890 \
  --dry-run \
  --objects contacts

Development

# Clone repository
git clone https://github.com/deliveredbyai/twenty-migrate-salesforce.git
cd twenty-migrate-salesforce

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development
npm run dev

Contributing

Fork the repository
Create feature branch
Make your changes
Run tests
Submit pull request

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

"Salesforce login failed"

Check username, password, and security token
Verify Salesforce account permissions
Ensure API access is enabled

"Rate limit exceeded"

Increase batch size delay
Reduce concurrent requests
Check Salesforce API limits

"Duplicate records"

Tool automatically prevents duplicates
Check existing data in Twenty CRM
Use dry-run to preview duplicates

"Invalid field mapping"

Review field mapping table
Check Salesforce field names
Verify Twenty CRM field requirements

"Security token expired"

Generate new security token
Update environment variables
Re-run migration

Support

Acknowledgments

jsforce - Salesforce JavaScript library
Salesforce API - REST API documentation
Twenty CRM - Open-source CRM
Commander.js - CLI framework
CLI Progress - Progress bars