Salesforce API Integration Guide for JavaScript
Overview
This guide provides comprehensive information about integrating with Salesforce APIs using JavaScript, focusing on the most popular libraries and best practices for implementation.
Primary Library: JSforce
What is JSforce?
JSforce (formerly Node-Salesforce) is the most widely adopted JavaScript library for Salesforce API integration. It serves as an isomorphic JavaScript library, meaning it operates seamlessly in both browser and Node.js environments.
Key Features
JSforce provides comprehensive access to Salesforce's extensive API ecosystem:
Core API Support:
- REST API - Primary interface for querying, searching, and describing objects
- Bulk API - Optimized for handling large data volumes efficiently
- Metadata API - Manages customizations and deployments
- SOAP API - Legacy but still supported protocol
- Streaming API - Real-time data updates and notifications
- Apex REST - Custom REST endpoints
- Analytics API - Business intelligence and reporting
- Chatter API - Social collaboration features
- Tooling API - Development and debugging tools
Additional Capabilities:
- Asynchronous Operations - Built-in support for modern async/await patterns
- Command Line Interface - Interactive REPL for testing and learning
- Simplified Syntax - Abstracted complexity of direct API calls
- Authentication Management - Handles OAuth2 and session management
- Promise Support - Modern JavaScript promise-based architecture
Implementation Workflow
1. Installation
npm install jsforce
2. Authentication Setup
Establish secure connections using OAuth2 authentication protocols.
3. API Operations
Execute operations including:
- SOQL queries for data retrieval
- Record creation, updates, and deletion
- Bulk data operations
- Metadata management
Alternative Libraries
ForceJS 2
A modern JavaScript library specifically designed for Salesforce REST APIs, built on ECMAScript 6 standards. Ideal for integration with contemporary frameworks like React and Angular.
Lightning Data Service (LDS)
For Lightning Web Components (LWCs) deployed within the Salesforce ecosystem, LDS provides native data and metadata interaction capabilities.
Security and Best Practices
Security Considerations
- Credential Management - Store credentials securely using environment variables or secure vaults
- Rate Limit Management - Implement appropriate handling for API rate limits
- Access Control - Follow principle of least privilege for API access
Error Handling
Implement robust error handling mechanisms to manage:
- API call failures
- Network timeouts
- Authentication issues
- Data validation errors
API Limitations
Monitor and respect Salesforce API limits:
- Timeout Limits - Maximum request duration
- Concurrent Limits - Simultaneous request restrictions
- Total Request Limits - Daily/hourly quotas
Advanced Use Case: Email Notification Control
Business Requirement
Provide library users with granular control over email notifications when creating cases in Salesforce through JSforce and the REST API.
Implementation Strategy
1. Salesforce Configuration
Configure Salesforce automation to respect email control flags:
Custom Field Creation:
- Add a custom checkbox field:
Suppress_Email_Notifications__c - This field acts as a control flag for email generation
Workflow/Flow Modification:
- Modify existing email alerts in Workflow Rules or Flow Builder
- Add conditional logic that checks the
Suppress_Email_Notifications__cfield - Prevent email alerts when the field is set to true
Default Settings Review:
- Examine "Support Settings" in Salesforce
- Disable default email notifications like "Notify case owners on new emails"
- Ensure reliance on custom automation rather than system defaults
2. Library Implementation
async function createCaseWithEmailControl(caseData, suppressEmails = false) {
try {
const caseRecord = { ...caseData };
// Set the custom field based on user preference
caseRecord.Suppress_Email_Notifications__c = suppressEmails;
// Use JSforce to create the case
const result = await conn.sobject('Case').create(caseRecord);
if (result.success) {
console.log('New case created with ID: ' + result.id);
return result.id;
} else {
console.error('Error creating case:', result.errors);
throw new Error('Failed to create case');
}
} catch (error) {
console.error('An error occurred:', error);
throw error;
}
}
3. Usage Examples
// Create a case with email notifications enabled (default behavior)
createCaseWithEmailControl({ Subject: 'Urgent Issue' });
// Create a case with email notifications suppressed
createCaseWithEmailControl({ Subject: 'Routine Query' }, true);
Implementation Details
Function Parameters:
caseData- Object containing case field valuessuppressEmails- Boolean flag controlling email notifications (defaults to false)
Process Flow:
- Accept case data and email suppression preference
- Create case record object with provided data
- Set custom field based on suppression preference
- Execute JSforce REST API call to create case
- Handle success/error responses appropriately
Prerequisites
This implementation requires:
- Custom field
Suppress_Email_Notifications__cconfigured in Salesforce - Workflow Rules or Flow Builder logic that respects the custom field
- Proper field-level security and permissions
- Testing to ensure email suppression works as expected
Conclusion
JSforce remains the most versatile and powerful JavaScript library for Salesforce API integration, supporting comprehensive API coverage and diverse integration scenarios. For specific requirements such as modern REST API integrations or Lightning Web Component development, ForceJS 2 or Lightning Data Service provide specialized alternatives. The email notification control example demonstrates how to extend basic API functionality with sophisticated business logic while maintaining user control and system flexibility.
JSforce's create() method accepts an optional second parameter for additional options.
Here are several useful options you can expose to your API callers:
Enhanced Implementation with Multiple Options
async function createCaseWithEmailControl(caseData, options = {}) {
try {
const {
suppressEmails = false,
assignmentRuleHeader = null,
duplicateRuleHeader = null,
allowFieldTruncation = false,
allOrNone = false,
} = options;
const caseRecord = { ...caseData };
// Set the custom field based on user preference
caseRecord.Suppress_Email_Notifications__c = suppressEmails;
// Build the options object for JSforce
const createOptions = {};
// Assignment Rule Header - controls case assignment rules
if (assignmentRuleHeader) {
createOptions.AssignmentRuleHeader = assignmentRuleHeader;
}
// Duplicate Rule Header - controls duplicate detection
if (duplicateRuleHeader) {
createOptions.DuplicateRuleHeader = duplicateRuleHeader;
}
// Allow Field Truncation - permits string field truncation
if (allowFieldTruncation) {
createOptions.AllowFieldTruncationHeader = { allowFieldTruncation: true };
}
// All or None - for bulk operations (if creating multiple records)
if (allOrNone) {
createOptions.allOrNone = true;
}
// Use JSforce to create the case with options
const result = await conn.sobject('Case').create(caseRecord, createOptions);
if (result.success) {
console.log('New case created with ID: ' + result.id);
return result.id;
} else {
console.error('Error creating case:', result.errors);
throw new Error('Failed to create case');
}
} catch (error) {
console.error('An error occurred:', error);
throw error;
}
}
Usage Examples
// Basic usage - just suppress emails
await createCaseWithEmailControl({ Subject: 'Basic Issue' }, { suppressEmails: true });
// Use assignment rules to auto-assign the case
await createCaseWithEmailControl(
{ Subject: 'Auto-assign Issue' },
{
suppressEmails: false,
assignmentRuleHeader: { useDefaultRule: true },
},
);
// Use specific assignment rule by ID
await createCaseWithEmailControl(
{ Subject: 'Specific Assignment' },
{
assignmentRuleHeader: { assignmentRuleId: '01Q000000000001' },
},
);
// Allow duplicate creation and field truncation
await createCaseWithEmailControl(
{
Subject: 'Duplicate Allowed',
Description: 'Very long description that might get truncated...',
},
{
suppressEmails: true,
duplicateRuleHeader: { allowSave: true, includeRecordDetails: false },
allowFieldTruncation: true,
},
);
// Comprehensive example with multiple options
await createCaseWithEmailControl(
{
Subject: 'Complex Case Creation',
Description: 'This case uses multiple API options',
Priority: 'High',
},
{
suppressEmails: false,
assignmentRuleHeader: { useDefaultRule: true },
duplicateRuleHeader: { allowSave: false, includeRecordDetails: true },
allowFieldTruncation: false,
allOrNone: true,
},
);
Available Options Explained
Assignment Rule Header
Controls how Salesforce assignment rules are applied:
useDefaultRule: true- Uses the default active assignment ruleassignmentRuleId: 'ruleId'- Uses a specific assignment rule by ID
Duplicate Rule Header
Controls duplicate detection behavior:
allowSave: true/false- Whether to allow saving duplicatesincludeRecordDetails: true/false- Whether to include duplicate record details in responserunAsCurrentUser: true/false- Run duplicate rules as current user
Allow Field Truncation Header
allowFieldTruncation: true- Allows Salesforce to truncate string fields that exceed maximum length
All or None
allOrNone: true- For bulk operations, either all records succeed or all fail (transactional behavior)
Advanced Options Object Structure
const advancedOptions = {
suppressEmails: true,
assignmentRuleHeader: {
useDefaultRule: true,
// OR assignmentRuleId: '01Q000000000001'
},
duplicateRuleHeader: {
allowSave: false,
includeRecordDetails: true,
runAsCurrentUser: true,
},
allowFieldTruncation: true,
allOrNone: false,
// Additional custom options your API might support
customValidation: true,
auditTrail: true,
};
This approach gives your API callers maximum flexibility while maintaining a clean, options-based interface. Each option serves a specific business need and can be used independently or in combination with others.