Salesforce Upgrade & Migration

Overview

Guide for upgrading Salesforce API versions (v55.0 to v59.0+), migrating between jsforce major versions, and handling Salesforce seasonal release changes.

Prerequisites

• Current jsforce or simple-salesforce installed
• Git for version control
• Test suite with Salesforce integration tests
• Sandbox environment for validation

Instructions

Step 1: Check Current Versions

# jsforce version
npm list jsforce

# Current API version in use
node -e "const jsforce = require('jsforce'); const c = new jsforce.Connection({}); console.log('Default API version:', c.version)"

# Available API versions from your org
sf org display --target-org my-org --json | jq '.result.apiVersion'

Step 2: Salesforce API Version Changes

TYPEOF

Salesforce retires API versions periodically. Versions older than 3 years are typically deprecated. Check Salesforce Release Notes each season.

Step 3: jsforce Major Version Migration

// jsforce v1.x → v2.x/v3.x migration
// Key breaking changes:

// BEFORE (v1.x): Callback-based
import jsforce from 'jsforce';
const conn = new jsforce.Connection();
conn.login(username, password, (err, userInfo) => {
  conn.query('SELECT Id FROM Account', (err, result) => {});
});

// AFTER (v2.x+): Promise-based (still supports callbacks)
import jsforce from 'jsforce';
const conn = new jsforce.Connection();
await conn.login(username, password);
const result = await conn.query('SELECT Id FROM Account');

// BEFORE (v1.x): Bulk API v1
const job = conn.bulk.createJob('Account', 'insert');
const batch = job.createBatch();

// AFTER (v2.x+): Bulk API 2.0
const results = await conn.bulk2.loadAndWaitForResults({
  object: 'Account',
  operation: 'insert',
  input: csvData,
});

Step 4: Update API Version in Code

// Pin API version explicitly (recommended for stability)
const conn = new jsforce.Connection({
  loginUrl: process.env.SF_LOGIN_URL,
  version: '59.0', // Pin to specific version
});

// Or use latest (auto-detected from org)
const conn = new jsforce.Connection({
  loginUrl: process.env.SF_LOGIN_URL,
  // version defaults to org's latest
});

Step 5: Create Upgrade Branch and Test

# Create upgrade branch
git checkout -b upgrade/jsforce-v3

# Upgrade jsforce
npm install jsforce@latest

# Run tests against sandbox
SF_LOGIN_URL=https://test.salesforce.com npm test

# Check for deprecation warnings
npm test 2>&1 | grep -i "deprecat"

# If tests pass, merge

Step 6: Handle Seasonal Release Breaking Changes

// Salesforce releases 3 times/year (Spring, Summer, Winter)
// Check release notes for:
// 1. Retired API versions
// 2. Changed field behavior (e.g., field becoming read-only)
// 3. New required fields on standard objects
// 4. Permission model changes

// Query org's supported API versions
const versions = await conn.request('/services/data/');
console.log('Supported versions:', versions.map((v: any) => v.version));
// If your pinned version isn't listed, you must upgrade

Output

• Updated jsforce/simple-salesforce to latest
• API version pinned to current stable release
• Breaking changes identified and resolved
• Test suite passing against sandbox
• Rollback procedure documented

Error Handling

UNSUPPORTED_API_VERSION

INVALID_FIELD

MODULE_NOT_FOUND

conn.bulk2

Resources

• Salesforce Release Notes
• jsforce Changelog
• API Version Lifecycle
• Minimum API Version Retirement

Next Steps

For CI integration during upgrades, see

salesforce-ci-integration