Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/salesforce-upgrade-migration/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill salesforce-upgrade-migration. Copyright stays with the author (MIT).

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

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

Examples

Upgrade an API version behind a sandbox verification gate

Pin the candidate API and SDK versions in a branch, deploy the metadata and application to a sandbox, and run regression tests covering queries, bulk operations, and authentication refresh. Compare error codes and response shapes to the previous version before approving production promotion. Keep the prior dependency lock and deployment artifact available for rollback, and split incompatible field or endpoint changes into separately reviewed migrations.

Resources

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

Next Steps

For CI integration during upgrades, see salesforce-ci-integration.