Project 7: CRM Integration (Salesforce)

Build reliable CPQ-CRM synchronization with OAuth security, idempotent writes, and conflict-safe data ownership.

Quick Reference

Attribute	Value
Difficulty	Level 3 (Advanced)
Time Estimate	2-3 weeks
Main Programming Language	TypeScript (Alternatives: Python, Java)
Coolness Level	Level 3
Business Potential	4. Open Core Infrastructure
Prerequisites	Projects 3-5, API contracts, auth basics
Key Topics	OAuth scopes, idempotency, field ownership, replay handling

1. Learning Objectives

Implement secure CPQ-CRM API integrations.
Design idempotent create/update flows with safe retries.
Build a field ownership matrix to prevent sync conflicts.
Instrument integration observability and failure replay.

2. All Theory Needed (Per-Concept Breakdown)

Concept A: Idempotent Integration Design

Fundamentals Idempotency ensures retries do not duplicate side effects, which is essential for network-unstable integrations.

Deep Dive into the concept Use idempotency keys on mutation endpoints and map them to durable request records. Treat external updates as events with correlation ids. Define ownership per field to avoid oscillating updates.

How this fit on projects Primary here, supports P05-approval-workflow-orchestrator.md and P10-visual-rule-builder.md.

Definitions & key terms

Idempotency key
Correlation id
Source-of-truth matrix

Mental model diagram

CRM Event -> Sync Adapter -> CPQ API (idempotent) -> Ack + Event Log

How it works

Receive CRM trigger.
Build normalized payload + correlation id.
Call CPQ mutation endpoint with idempotency key.
Persist result and push status back.

Minimal concrete example

POST /quotes with Idempotency-Key=opp-4482-rev1
replay same key -> returns existing quote id, no duplicate

Common misconceptions

“Retries are rare.” They are routine in distributed systems.

Check-your-understanding questions

Why define field ownership?
Why include correlation id in logs and events?

Check-your-understanding answers

To prevent ping-pong overwrites.
To reconstruct end-to-end sync timelines.

Real-world applications CRM handoff, ERP order creation, support system enrichment.

Where you’ll apply it This project and P10-visual-rule-builder.md publication sync.

References

RFC 6749 OAuth.
Salesforce REST API docs.

Key insights Integration reliability is mostly contract and ownership design.

Summary Secure, idempotent, observable sync is mandatory for CPQ credibility.

Homework/Exercises to practice the concept Design one create-quote endpoint with idempotency and unified error shape.

Solutions to the homework/exercises Persist key->result mapping and return same response on replay.

3. Project Specification

3.1 What You Will Build

A sync service that imports CRM opportunity context into CPQ and pushes quote status/results back to CRM.

3.2 Functional Requirements

Authenticate via OAuth 2.0 with scoped permissions.
Pull opportunity/account/contact context.
Upsert quotes idempotently.
Push lifecycle updates back to CRM.

3.3 Non-Functional Requirements

Performance: sync under 3 seconds for standard payload.
Reliability: retry-safe with dead-letter handling.
Usability: clear failure diagnostics.

3.4 Example Usage / Output

$ cpq sync run --opportunity OPP-4482
status=success quote=Q-2026-0137 correlation=csync-001

3.5 Data Formats / Schemas / Protocols

SyncRequest(opportunityId, correlationId, idempotencyKey)
SyncResult(status, quoteId, errors[])
Unified error shape: {code,message,correlationId,details}

3.6 Edge Cases

Token expiration mid-sync.
Duplicate webhook deliveries.
Field conflict from concurrent edits.

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

$ cpq auth connect-crm
$ cpq sync run --opportunity OPP-4482
$ cpq sync status --correlation csync-001

3.7.2 Golden Path Demo (Deterministic)

Replay same idempotency key should not create a second quote.

3.7.5 If API

| Endpoint | Method | Purpose | |———-|——–|———| | /api/v1/sync/opportunities/{id} | POST | start sync | | /api/v1/sync/{correlationId} | GET | status |

Success response:

{"status":"success","quoteId":"Q-2026-0137","correlationId":"csync-001"}

Error response:

{"code":"TOKEN_EXPIRED","message":"Reconnect CRM integration","correlationId":"csync-001"}

4. Solution Architecture

4.1 High-Level Design

Webhook/Trigger -> Sync Orchestrator -> CRM Adapter + CPQ Adapter -> Event Log

4.2 Key Components

4.4 Data Structures (No Full Code)

OwnershipRule { fieldName, ownerSystem, overwritePolicy }
SyncEvent { correlationId, stage, status, timestamp }

4.4 Algorithm Overview

Authenticate and fetch CRM context.
Transform payload to CPQ schema.
Upsert quote with idempotency key.
Push status back and log events.

5. Implementation Guide

5.1 Development Environment Setup

$ cpq seed --scenario crm-sync
$ cpq test --suite integration-sync

5.2 Project Structure

crm-sync/
  src/
    auth/
    adapters/
    orchestrator/

5.3 The Core Question You’re Answering

“How do we keep CRM and CPQ in sync without duplication, drift, or hidden failures?”

5.4 Concepts You Must Understand First

OAuth scopes
Idempotency keys
Conflict policies

5.5 Questions to Guide Your Design

Which fields are CRM-owned versus CPQ-owned?
How should retries behave for partial success?

5.6 Thinking Exercise

Design a replay plan for 100 failed sync events after downtime.

5.7 The Interview Questions They’ll Ask

How do you design idempotent APIs?
How do you handle bi-directional conflict resolution?
How do you observe integration health?

5.8 Hints in Layers

Hint 1: correlation id from first hop.
Hint 2: unified error schema.
Hint 3: dead-letter queue for unresolved failures.

5.9 Books That Will Help

| Topic | Book | Chapter | |——-|——|———| | Integration reliability | “The Pragmatic Programmer” | Ch. 8 | | Boundary design | “Clean Architecture” | Ch. 21 |

5.10 Implementation Phases

Phase 1: auth + adapter contracts.
Phase 2: orchestrated sync flow.
Phase 3: retries, DLQ, observability.

5.11 Key Implementation Decisions

6. Testing Strategy

6.1 Test Categories

6.2 Critical Test Cases

Duplicate webhook with same idempotency key.
Token expiry during sync.
Concurrent field updates across systems.

6.3 Test Data

crm_opportunity_fixture.json, cpq_quote_fixture.json, sync_failures.json.

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

7.2 Debugging Strategies

Trace by correlation id.
Replay failed events from dead-letter queue.

7.3 Performance Traps

Avoid serial API calls when independent fetches can be parallelized.

8. Extensions & Challenges

8.1 Beginner Extensions

Add sync dry-run mode.
Add sync history viewer.

8.2 Intermediate Extensions

Field-level conflict dashboard.
Automated token refresh handling.

8.3 Advanced Extensions

Multi-CRM abstraction layer.
Event schema registry with compatibility checks.

9. Real-World Connections

9.1 Industry Applications

Revenue pipeline consistency.
Forecast accuracy and stage tracking.

9.3 Interview Relevance

Demonstrates distributed systems discipline in business-critical integrations.

10. Resources

10.1 Essential Reading

RFC 6749 OAuth 2.0.
Salesforce REST API guide.

10.2 Video Resources

Event-driven integration architecture talks.

10.3 Tools & Documentation

API gateway docs, DLQ tooling docs.

Previous: Project 5
Next: Project 8

11. Self-Assessment Checklist

I can replay any sync using correlation id.
Duplicate events do not create duplicate entities.
Field conflicts are resolved predictably.

12. Submission / Completion Criteria

Minimum Viable Completion:

Secure auth and one-way sync works.

Full Completion:

Bidirectional sync with idempotency and retries.
Observability and DLQ replay implemented.

Excellence (Going Above & Beyond):

Conflict analytics and schema compatibility automation.