Salesforce Sync

Sync Keva customer profiles with Salesforce contacts automatically. When customers submit tickets, their information stays synchronized across both systems.

Prerequisites

Before setting up Salesforce sync:

1. Salesforce account with API access (Enterprise, Unlimited, or Developer edition)
2. Keva Salesforce connector connected via OAuth
3. Admin permissions in both Salesforce and Keva

Connect Salesforce

Step 1: Authorize OAuth

1. Go to Settings then Integrations then Salesforce
2. Click Connect
3. Sign in to Salesforce
4. Authorize Keva to access your Salesforce data
5. You'll be redirected back to Keva

Step 2: Verify Connection

After connecting, you should see:

• Connection status: Connected
• Instance URL (e.g., https://yourcompany.salesforce.com)
• Last sync timestamp

What Gets Synced

Contacts (Primary)

Customer profiles sync to Salesforce Contacts:

Accounts (Optional)

Link customers to Salesforce Accounts for B2B scenarios:

Custom Fields

Map any Keva custom field to Salesforce:

1. Create the custom field in Salesforce (e.g., Keva_Ticket_Count__c)
2. Add mapping in Keva: totalTickets to Keva_Ticket_Count__c
3. Set sync direction

Configure Field Mappings

Access Field Mapping

1. Go to Settings then CRM Sync then Salesforce
2. Click Field Mappings
3. Select object type (Contact, Account)

Add a Mapping

1. Click Add Mapping
2. Select Keva field from dropdown
3. Select Salesforce field from dropdown
4. Choose sync direction:
   • Bidirectional: Syncs both ways
   • To CRM: Keva to Salesforce only
   • From CRM: Salesforce to Keva only
5. Optionally add transformation
6. Click Save

Auto-Mapping (AI-Assisted)

Keva can suggest mappings automatically:

1. Click Auto-Map Fields
2. Review AI suggestions (shown with confidence score)
3. Accept or reject each suggestion
4. Save accepted mappings

Name Splitting

Salesforce uses separate FirstName and LastName fields. Keva handles this automatically:

• To Salesforce: "John Doe" splits to FirstName="John", LastName="Doe"
• From Salesforce: FirstName + LastName combines to "John Doe"

For custom name handling, use the split_name transformation.

Sync Triggers

Automatic (Event-Driven)

Sync happens automatically when:

Manual Sync

Sync a single customer:

1. Go to the ticket or customer profile
2. Click the Salesforce icon in the sidebar
3. Click Sync Now

Batch Sync

Sync all customers:

1. Go to Settings then CRM Sync then Salesforce
2. Click Run Batch Sync
3. Monitor progress (100 customers per batch)

Webhook Setup (Inbound Sync)

To receive updates from Salesforce, configure Outbound Messages:

Step 1: Create Outbound Message

In Salesforce Setup:

1. Go to Workflow Rules then Outbound Messages
2. Click New Outbound Message
3. Select object: Contact
4. Configure:
   • Name: Keva Contact Sync
   • Endpoint URL: https://app.keva.support/api/webhooks/salesforce
   • User: Your integration user
   • Fields: Select all fields to sync

Step 2: Create Workflow Rule

1. Go to Workflow Rules
2. Create new rule for Contact object
3. Evaluation criteria: Created, and any time it's edited
4. Add Workflow Action: Select your Outbound Message
5. Activate the rule

Step 3: Verify in Keva

1. Go to Settings then CRM Sync then Salesforce then Webhooks
2. Verify webhook is registered
3. Test by updating a contact in Salesforce

Troubleshooting

"Contact not found" Error

Cause: Email mismatch between Keva and Salesforce.

Solution:

1. Check the customer's email in both systems
2. Manually link via customer profile if needed
3. Ensure email is the primary identifier

"DUPLICATE_VALUE" Error

Cause: Contact already exists in Salesforce with same email.

Solution:

1. Keva automatically searches by email before creating
2. If still failing, check for duplicate rules in Salesforce
3. Consider enabling "Allow duplicates" for initial sync

"FIELD_CUSTOM_VALIDATION_EXCEPTION" Error

Cause: Salesforce validation rule blocking update.

Solution:

1. Check Salesforce validation rules on Contact
2. Ensure mapped values meet validation requirements
3. Add default transformation to provide fallback values

"INVALID_FIELD" Error

Cause: Mapped field doesn't exist in Salesforce.

Solution:

1. Verify field API name (not label)
2. Check field exists on correct object
3. Ensure field is accessible to integration user

Sync Stuck at "Pending"

Cause: Inngest function not processing.

Solution:

1. Check Inngest dashboard for errors
2. Verify Salesforce OAuth token is valid
3. Reconnect Salesforce if token expired

Webhook Not Receiving Updates

Cause: Salesforce Outbound Message not configured correctly.

Solution:

1. Verify endpoint URL is correct
2. Check Salesforce Outbound Message queue for failures
3. Ensure workflow rule is active
4. Test with Salesforce's "Test Connection" feature

Best Practices

Initial Setup

1. Start with default mappings - Add custom mappings later
2. Test with one customer - Verify sync works before batch
3. Use sandbox first - Test in Salesforce sandbox environment

Field Mapping

1. Use bidirectional sparingly - Reduces conflict potential
2. Set reasonable defaults - Prevent validation errors
3. Document custom mappings - Track what syncs where

Performance

1. Batch sync during off-hours - Avoid API limit issues
2. Monitor sync history - Catch errors early
3. Review failed syncs weekly - Fix mapping issues

API Reference

Trigger Sync Programmatically

POST /api/crm/salesforce/sync
Authorization: Bearer keva_live_xxx
Content-Type: application/json
 
{
  "customerId": "uuid-of-customer",
  "connectorId": "uuid-of-salesforce-connector"
}

Get Sync Status

GET /api/crm/sync-logs?customerId={id}&platform=salesforce
Authorization: Bearer keva_live_xxx

Response

{
  "logs": [
    {
      "id": "uuid",
      "operation": "update",
      "direction": "to_crm",
      "status": "success",
      "crmRecordId": "003xxx",
      "changes": { "Phone": "+1234567890" },
      "createdAt": "2024-03-20T10:30:00Z"
    }
  ]
}