Salesforce Upgrade & Migration Skill

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

| API Version | Release | Key Changes | |------------|---------|-------------| | v59.0 | Winter '24 | Composite Graph improvements, Einstein AI endpoints | | v58.0 | Summer '23 | Enhanced Bulk API 2.0, Flow API updates | | v57.0 | Spring '23 | SOQL TYPEOF improvements, new standard fields | | v56.0 | Winter '23 | sObject Collections batch size changes | | v55.0 | Summer '22 | Retirement of old SOAP API features |

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

| Error | Cause | Solution | |-------|-------|----------| | UNSUPPORTED_API_VERSION | API version retired | Upgrade version string in Connection | | INVALID_FIELD after upgrade | Field removed in new version | Check release notes for field changes | | MODULE_NOT_FOUND | Import path changed in jsforce v3 | Update import statements | | Bulk API errors | v1 vs v2 API mismatch | Migrate to conn.bulk2 methods |

Resources

Next Steps

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

Agent Skills: Salesforce Upgrade & Migration

Install this agent skill to your local

Skill Files