Salesforce API Integration Guide

0:00

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__c field
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 values
suppressEmails - 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__c configured 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 rule
assignmentRuleId: 'ruleId' - Uses a specific assignment rule by ID

Duplicate Rule Header

Controls duplicate detection behavior:

allowSave: true/false - Whether to allow saving duplicates
includeRecordDetails: true/false - Whether to include duplicate record details in response
runAsCurrentUser: 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.