Sf Integration

sf-integration: Salesforce Integration Patterns Expert

Expert integration architect specializing in secure callout patterns, event-driven architecture, and external service registration for Salesforce.

Core Responsibilities

1. Named Credential Generation: Create Named Credentials with OAuth 2.0, JWT Bearer, Certificate, or Custom authentication
2. External Credential Generation: Create modern External Credentials (API 61+) with Named Principals
3. External Service Registration: Generate ExternalServiceRegistration metadata from OpenAPI/Swagger specs
4. REST Callout Patterns: Synchronous and asynchronous HTTP callout implementations (details)
5. SOAP Callout Patterns: WSDL2Apex guidance and WebServiceCallout patterns (details)
6. Platform Events: Event definitions, publishers, and subscriber triggers (details)
7. Change Data Capture: CDC enablement and subscriber patterns (details)
8. Validation & Scoring: Score integrations against 6 categories (0-120 points)

Key Insights

⚠️ CRITICAL: Named Credential Architecture (API 61+)

Legacy Named Credentials vs External Credentials

Decision Matrix

┌─────────────────────────────────────────────────────────────────────────────┐
│  WHEN TO USE WHICH CREDENTIAL TYPE                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│  Use LEGACY Named Credential if:                                            │
│  • Org API version < 61                                                     │
│  • Migrating existing integrations (maintain compatibility)                 │
│  • Simple API key / Basic Auth (quick setup)                               │
│                                                                             │
│  Use EXTERNAL Credential (API 61+) if:                                      │
│  • New development (recommended)                                            │
│  • OAuth 2.0 with PKCE required                                            │
│  • Per-user authentication needed                                           │
│  • Fine-grained permission control required                                 │
│  • JWT Bearer flow for server-to-server                                    │
└─────────────────────────────────────────────────────────────────────────────┘

Workflow (5-Phase Pattern)

Phase 1: Requirements Gathering

Use AskUserQuestion to gather:

1. Integration Type: Outbound REST/SOAP, Inbound REST, Event-driven (Platform Events, CDC)
2. Authentication Method: OAuth 2.0 (Client Credentials, JWT Bearer, Authorization Code), Certificate-based, API Key/Basic Auth
3. External System Details: Base endpoint URL, API version, rate limits, required headers
4. Sync vs Async Requirements: Real-time response needed → Sync | Fire-and-forget or DML-triggered → Async (Queueable)

Phase 2: Template Selection

Phase 3: Generation & Validation

File Locations:

force-app/main/default/
├── namedCredentials/          # Legacy Named Credentials
├── externalCredentials/       # External Credentials (API 61+)
├── externalServiceRegistrations/
├── classes/                   # Callout services, handlers
├── objects/{{EventName}}__e/  # Platform Events
└── triggers/                  # Event/CDC subscribers

Validate using scoring system (see Scoring System below)

Phase 4: Deployment

Deployment Order (CRITICAL):

1. Named Credentials / External Credentials FIRST
2. External Service Registrations (depends on Named Credentials)
3. Apex classes (callout services, handlers)
4. Platform Events / CDC configuration
5. Triggers (depends on events being deployed)

Use sf-deploy skill: Skill(skill="sf-deploy")

CLI Commands: See CLI Commands Reference

Phase 5: Testing & Verification

1. Test Named Credential: Setup → Named Credentials → Test Connection
2. Test External Service: Invoke generated Apex methods
3. Test Callout: Anonymous Apex or test class with Test.setMock()
4. Test Events: Publish and verify subscriber execution

Named Credentials

Templates in templates/named-credentials/. ⚠️ NEVER hardcode credentials - always use Named Credentials!

External Credentials (API 61+)

Use Case: Modern OAuth 2.0 with per-user or named principal authentication

Template: templates/external-credentials/oauth-external-credential.externalCredential-meta.xml

Key Features:

• Named Principal vs Per-User Principal support
• OAuth 2.0 with PKCE
• JWT Bearer flow
• Permission Set-based access control

Quick Start:

<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>{{CredentialLabel}}</label>
    <authenticationProtocol>Oauth</authenticationProtocol>
    <principals>
        <principalName>{{PrincipalName}}</principalName>
        <principalType>NamedPrincipal</principalType>
    </principals>
</ExternalCredential>

External Services (OpenAPI/Swagger)

Process:

1. Obtain OpenAPI 2.0 (Swagger) or 3.0 spec from external API
2. Create Named Credential for authentication
3. Register External Service in Salesforce (Setup → External Services OR via metadata)
4. Salesforce auto-generates Apex classes: ExternalService.{{ServiceName}}

Template: templates/external-services/openapi-registration.externalServiceRegistration-meta.xml

CLI Alternative:

sf api request rest /services/data/v62.0/externalServiceRegistrations \
  --method POST \
  --body '{"label":"{{Label}}","namedCredential":"{{NC}}","schemaUrl":"{{URL}}"}'

Usage Example:

ExternalService.Stripe stripe = new ExternalService.Stripe();
ExternalService.Stripe_createCustomer_Request req = new ExternalService.Stripe_createCustomer_Request();
req.email = 'customer@example.com';
ExternalService.Stripe_createCustomer_Response resp = stripe.createCustomer(req);

Callout Patterns

REST Callouts

For detailed REST callout patterns, see resources/callout-patterns.md

Quick Reference

Key Points:

• Use Named Credentials: req.setEndpoint('callout:{{NamedCredentialName}}/{{path}}')
• Set timeout: req.setTimeout(120000) (120s max)
• Handle status codes: 2xx success, 4xx client error (don't retry), 5xx server error (retry)

Detailed Examples:

• Synchronous REST Callout
• Asynchronous Queueable Callout
• Retry Handler with Exponential Backoff

SOAP Callouts

For detailed SOAP callout patterns, see resources/callout-patterns.md#soap-callout-patterns

Quick Reference

WSDL2Apex Process:

1. Setup → Apex Classes → Generate from WSDL
2. Upload WSDL file
3. Salesforce generates stub classes

Usage:

{{WsdlGeneratedClass}}.{{PortType}} stub = new {{WsdlGeneratedClass}}.{{PortType}}();
stub.endpoint_x = 'callout:{{NamedCredentialName}}';
stub.timeout_x = 120000;
return stub.{{OperationName}}(request);

Detailed Examples:

• WSDL2Apex Process
• SOAP Service Implementation

Event-Driven Patterns

Platform Events

For detailed Platform Event patterns, see resources/event-patterns.md#platform-events

Quick Reference

Event Types:

• Standard Volume: ~2,000 events/hour, 3-day retention
• High Volume: Millions/day, 24-hour retention, at-least-once delivery

Templates:

• Event Definition: templates/platform-events/platform-event-definition.object-meta.xml
• Publisher: templates/platform-events/event-publisher.cls
• Subscriber: templates/platform-events/event-subscriber-trigger.trigger

Publishing:

List<Database.SaveResult> results = EventBus.publish(events);

Subscribing:

trigger {{EventName}}Subscriber on {{EventName}}__e (after insert) {
    for ({{EventName}}__e event : Trigger.new) {
        {{EventName}}Handler.processEvent(event);
    }
}

Detailed Examples:

• Platform Event Definition
• Event Publisher
• Event Subscriber Trigger

Change Data Capture (CDC)

For detailed CDC patterns, see resources/event-patterns.md#change-data-capture-cdc

Quick Reference

Enablement: Setup → Integrations → Change Data Capture

Channel Naming: {{ObjectAPIName}}ChangeEvent (e.g., AccountChangeEvent)

Subscriber Template:

trigger {{ObjectName}}CDCSubscriber on {{ObjectName}}ChangeEvent (after insert) {
    for ({{ObjectName}}ChangeEvent event : Trigger.new) {
        EventBus.ChangeEventHeader header = event.ChangeEventHeader;
        String changeType = header.getChangeType(); // CREATE, UPDATE, DELETE, UNDELETE
        List<String> changedFields = header.getChangedFields();
        String recordId = header.getRecordIds()[0];

        switch on changeType {
            when 'CREATE' { {{ObjectName}}CDCHandler.handleCreate(event); }
            when 'UPDATE' { {{ObjectName}}CDCHandler.handleUpdate(event, changedFields); }
            when 'DELETE' { {{ObjectName}}CDCHandler.handleDelete(recordId); }
            when 'UNDELETE' { {{ObjectName}}CDCHandler.handleUndelete(event); }
        }
    }
}

Detailed Examples:

• CDC Enablement
• CDC Subscriber Trigger
• CDC Handler Service

Scoring System (120 Points)

Category Breakdown

Scoring Thresholds

Score: XX/120 Rating
├─ ⭐⭐⭐⭐⭐ Excellent (108-120): Production-ready, follows all best practices
├─ ⭐⭐⭐⭐ Very Good (90-107): Minor improvements suggested
├─ ⭐⭐⭐ Good (72-89): Acceptable with noted improvements
├─ ⭐⭐ Needs Work (54-71): Address issues before deployment
└─ ⭐ Block (<54): CRITICAL issues, do not deploy

Scoring Output Format

📊 INTEGRATION SCORE: XX/120 ⭐⭐⭐⭐ Rating
════════════════════════════════════════════════════

🔐 Security           XX/30  ████████░░ XX%
├─ Named Credentials used: ✅
├─ No hardcoded secrets: ✅
└─ OAuth scopes minimal: ✅

⚠️ Error Handling     XX/25  ████████░░ XX%
├─ Retry logic: ✅
├─ Timeout handling: ✅
└─ Logging: ✅

📦 Bulkification      XX/20  ████████░░ XX%
├─ Batch callouts: ✅
└─ Event batching: ✅

🏗️ Architecture       XX/20  ████████░░ XX%
├─ Async patterns: ✅
└─ Service separation: ✅

✅ Best Practices     XX/15  ████████░░ XX%
├─ Governor limits: ✅
└─ Idempotency: ✅

📝 Documentation      XX/10  ████████░░ XX%
├─ Clear intent: ✅
└─ API versioning: ✅

════════════════════════════════════════════════════

Cross-Skill Integration

Agentforce Integration Flow

sf-integration → Named Credential + External Service → sf-flow → HTTP Callout wrapper → sf-ai-agentscript → Agent with flow:// target → sf-deploy → Deploy all

CLI Commands Reference

Named Credentials

# List Named Credentials
sf org list metadata --metadata-type NamedCredential --target-org {{alias}}

# Deploy Named Credential
sf project deploy start --metadata NamedCredential:{{Name}} --target-org {{alias}}

# Retrieve Named Credential
sf project retrieve start --metadata NamedCredential:{{Name}} --target-org {{alias}}

External Services

# List External Service Registrations
sf org list metadata --metadata-type ExternalServiceRegistration --target-org {{alias}}

# Deploy External Service
sf project deploy start --metadata ExternalServiceRegistration:{{Name}} --target-org {{alias}}

Platform Events

# List Platform Events
sf org list metadata --metadata-type CustomObject --target-org {{alias}} | grep "__e"

# Deploy Platform Event
sf project deploy start --metadata CustomObject:{{EventName}}__e --target-org {{alias}}

API Requests (Beta)

Execute REST and GraphQL API calls directly via sf CLI, without curl:

# REST API request
sf api request rest /services/data/v62.0/sobjects/Account/describe --target-org {{alias}}

# REST with POST body
sf api request rest /services/data/v62.0/sobjects/Account --method POST \
  --body '{"Name":"Test Account"}' --target-org {{alias}}

# GraphQL query
sf api request graphql --body '{"query":"{ uiapi { query { Account { edges { node { Name { value } } } } } } }"}' --target-org {{alias}}

[Beta] These commands simplify API exploration. For production integration code, use Named Credentials and Apex callouts.

🔧 Helper Scripts

sf-integration includes automation scripts to configure credentials without manual UI steps.

Available Scripts

Auto-Run Behavior

When you create credential metadata files, Claude automatically suggests running the appropriate script:

Example Workflow

# 1. Claude generates credential metadata files
# 2. Hook detects and suggests next steps
# 3. Deploy metadata first
sf project deploy start --metadata ExternalCredential:WeatherAPI \
  --metadata NamedCredential:WeatherAPI \
  --target-org MyOrg

# 4. Run automation script
./scripts/configure-named-credential.sh MyOrg
# Enter API key when prompted (secure, hidden input)

Prerequisites

• Salesforce CLI v2+: sf command available
• Authenticated org: sf org login web -a <alias>
• Deployed metadata: External Credential and Named Credential deployed

📚 Documentation: See docs/named-credentials-automation.md for complete guide.

Anti-Patterns

Additional Resources

📚 Detailed Documentation:

• Callout Patterns - REST and SOAP callout implementations
• Event Patterns - Platform Events and Change Data Capture
• Messaging API v2 - NEW: MIAW custom client architecture (Agentforce external chat)

📁 Templates:

• templates/named-credentials/ - Authentication templates
• templates/external-credentials/ - External Credential templates (API 61+)
• templates/external-services/ - OpenAPI registration templates
• templates/callouts/ - REST/SOAP callout patterns
• templates/platform-events/ - Event definitions and publishers
• templates/cdc/ - Change Data Capture triggers

Notes & Dependencies

• API Version: 62.0+ (Winter '25) recommended for External Credentials
• Required Permissions: API Enabled, External Services access
• Optional Skills: sf-connected-apps (OAuth setup), sf-apex (custom callout code), sf-deploy (deployment)
• Scoring Mode: Strict (block deployment if score < 54)

License

MIT License - See LICENSE file for details.