---
name: conga-salesforce
description: Build a production-grade Conga to Salesforce integration covering architecture, the step-by-step build with Apex code, field mapping, API and governor limits, security, monitoring, and the pitfalls to design out. Use when connecting, building, or debugging a Conga and Salesforce integration.
---

# Conga to Salesforce integration

> Cloudsheer's delivery playbook for Conga on Salesforce, distilled from 5 client projects and 190 delivery tasks. Apply it as the reference approach when building this integration.

## Overview

Conga Composer and Grid for document generation and in-place data editing. We have shipped it across 5 client projects and 190 build tasks.

The value is that the action happens automatically from the record your team already works in, with the result tracked back in Salesforce.

We deploy the managed package the right way: sandbox first, licenses and permission sets assigned, templates and layouts configured, and automation wrapped around it so it fits your process.

Every Conga build is delivered by a senior Salesforce architect on a fixed price, tested end to end in a sandbox, deployed to your org, and backed by 30 days of hypercare. You own the result: documented, source-controlled, and free of black-box middleware lock-in.

## Integration facts

**Connects via:**
- Two AppExchange managed packages: Conga Composer (doc generation) and Conga Grid (native inline grid editing)
- Classic Composer solutions launched from a record via a URL button passing SessionId + Partner ServerUrl
- Lightning requires an OAuth-enabled Conga button (Connected App)
- Newer Conga Composer REST API for server-side generation

**Package:** Conga Composer and Conga Grid (separate packages)

**Authentication:** Classic URL button authenticates the callback with the running user SessionId + Partner ServerUrl; Lightning uses OAuth via a Connected App. The Composer REST API uses OAuth 2.0 client_credentials returning a Bearer token

**API type:** REST

**API base:** `Composer REST: https://coreapps-rlsprod.congacloud.com/api/ingress/v1/ (classic: https://composer.congamerge.com)`

**Key endpoints:**
- `POST /Merge (generate document)`
- `GET /status/{correlationId}`
- `download via presigned service`
- `classic URL button with SessionId, ServerUrl, Id, TemplateId`

**Official docs:** https://documentation.conga.com/composer

## Prerequisites

- A Salesforce edition with API access (Enterprise, Unlimited, or Developer)
- The managed package, installed in a sandbox first
- A dedicated sandbox to build and test in
- A Conga account on a plan with API access
- System Administrator access on both systems
- A dedicated integration user with a minimum-access permission set
- Agreement on the objects, fields, and sync direction for the Conga data

## Architecture

Data flows left to right through four lanes:

1. **Sources:** Salesforce record, Flow / Apex trigger
2. **Integration layer:** Payload build, Conga API call, Status write-back
3. **Salesforce:** document, Related records, Reports
4. **Outcomes:** Action done automatically, Status on the record, No app-switching

## How it works at runtime

1. **Trigger in Salesforce** `[In Salesforce]`: A record change or a button starts the Conga action.
   - Note: `A record-triggered flow or a Quick Action fires the process.`
2. **Payload is built** `[In Salesforce]`: A flow or Apex assembles the request and maps the Salesforce fields.
   - Note: `Serialized with JSON.serialize; the callout is queued to run asynchronously.`
3. **Call Conga** `[In transit]`: The request is sent to Conga.
   - Note: `HTTPS callout via callout:NamedCredential over Managed package, with no secrets in code.`
4. **Result written back** `[In Salesforce]`: Conga performs the action and the status is written back.
   - Note: `Response parsed; status and external ids stored on the record for audit.`

## Step-by-step build

### Step 1: Plan the integration and prerequisites

We line up licenses and access before installing anything.

- A Salesforce edition compatible with the package, and a sandbox to install into first
- A Conga account and admin rights on both systems
- The records, templates, and outcomes agreed up front

### Step 2: Install the managed package

We install Conga the safe way.

- Install from AppExchange into a sandbox first, choosing Install for All Users
- Approve the third-party access it requests, and note the API or remote endpoints it uses

> **Pro tip: sandbox first** Install the managed package in a sandbox first and choose Install for All Users, so you can configure and test safely before anything touches production.

### Step 3: Assign licenses and permission sets

We give the right users the right access.

- Assign the package licenses and its permission sets to the integration user and the end users who need it

### Step 4: Authenticate to Conga

We connect the package to your Conga account securely.

- Authenticate Conga via OAuth and configure the org-wide and per-user settings
- Confirm any Named Credential or Remote Site the package relies on is configured

### Step 5: Configure objects, templates, and layouts

We set Conga up around how you actually work.

- Configure the Conga-specific pieces such as templates, gateways, or components
- Add the Lightning components and actions to the right page layouts
- Map Salesforce fields into Conga so documents and records are accurate every time

### Step 6: Build automation around the package

We make Conga fire from the right place and write results back.

- Record-triggered flows or Quick Actions invoke the package's invocable methods
- Status and results are written back onto the Salesforce record automatically

Reference implementation (`snippets/GenerateDocument.cls`):

```apex
public class GenerateDocument {
  @InvocableMethod(label='Generate document via package')
  public static void run(List<Id> recordIds) {
    // a record-triggered flow calls this; it hands off to the managed package
    for (Id recId : recordIds) {
      pkg.DocumentService.createFromTemplate(recId, 'Order Form');
    }
  }
}
```

### Step 7: Test in a sandbox

We validate the full flow before go-live.

- Run real scenarios end to end and confirm the records, documents, and callbacks

### Step 8: Deploy and monitor

We ship it and support it.

- Deploy configuration via change sets and assign permission sets in production
- Monitor callbacks and errors, with 30 days of support

## Data model

| Object | Purpose | Key fields |
| --- | --- | --- |
| `document` | The primary Salesforce record Conga data maps onto. | `External_Id__c, Name, Status` |
| `Account` | Matched or created for the customer or company behind the record. | `Name, External_Id__c` |
| `Error_Log__c (custom)` | Captures every request, response, and failure so anything can be replayed. | `Payload__c, Status__c, Related_Id__c` |

Salesforce objects typically in play: `Any master object (Opportunity, Quote, Account, Contact, custom)`, `ContentVersion/Attachment for output`, `Conga Template / Conga Query objects`

## Field mapping (example)

| Conga | Salesforce | Notes |
| --- | --- | --- |
| Salesforce document | `Conga record` | Direction: Salesforce to Conga |
| Record id | `Conga external reference` | Stored back on the record |
| Key fields | `Conga fields` | Mapped per template |
| Status | `Conga status` | Written back on completion |
| Created / updated at | `LastModifiedDate` | Enables delta sync and audit |
| Owner or rep | `document.OwnerId` | Assignment rules or a default owner |

Tailor the full mapping to the org. Always upsert on an external-id field so retries are idempotent.

## API and rate limits

### Conga-specific

- Runs on the running user Salesforce session, consuming the org daily API allocation
- Classic buttons constrained by browser URL length (~2,000 chars); large field sets need a Conga Query
- If invoked from Apex: 100 callouts/transaction, 120s

### Salesforce platform

- The managed package uses its own API budget. We confirm the limits on your plan before go-live.
- Conga rate limits apply to bulk operations. We chunk batches to stay within them.

## Security checklist

- Secrets stored in Named Credentials and permission sets, never in code or metadata
- A least-privilege integration user, with field-level security and sharing scoped tight
- All traffic over TLS, with signature verification on inbound events
- Shield Platform Encryption available for sensitive fields
- A full audit trail: every request and response logged for traceability
- Every automation runs as a dedicated integration user, so actions are attributable and revocable
- Sandbox-first delivery and change-set deployment keep production changes reviewed and controlled

## Monitoring and reliability

- Every request and response is logged to a custom Error Log object, tagged with the related record id.
- Failed calls retry with exponential backoff; anything still failing lands in a dead-letter queue for review.
- Idempotency keys guarantee a retried or duplicate event never double-posts a record.
- A dashboard surfaces failures, latency, and volume so problems are caught before users notice.
- Optional email or Slack alerts fire on repeated failures or a stalled sync.

## Testing and deployment

- Apex unit tests with HttpCalloutMock cover the success path, failure handling, and a 200-record bulk case, at 75 percent or higher coverage.
- The full flow is validated in a sandbox against real sample data and the edge cases that matter.
- A parallel run reconciles the integration against your live system before cutover.
- Everything deploys through change sets or an SFDX and CI pipeline, under version control.
- Permission sets, sharing, and Named Credentials are configured in production, then we run 30 days of monitored hypercare.

## Pitfalls to design out

- **Config lost between orgs:** Deploy configuration via change sets and document the setup.
- **Users cannot see the feature:** Assign the package license and permission set to the right users.
- **Vendor limits hit unexpectedly:** Confirm the API and volume limits on your plan before go-live.
- **No visibility when it breaks:** We log every call and surface failures on a dashboard with alerts, so an issue never goes unnoticed.
- **Reporting drifts from reality:** External-id keys and a delta timestamp keep Salesforce and the source reconciled, so reports stay trustworthy.

### Conga-specific gotchas

- SessionId-based classic buttons fail in Lightning Experience; switch to OAuth-enabled Conga buttons
- SessionId is unavailable in async/scheduled/batch contexts, so background doc-gen needs the server-side product
- Conga Grid is a separate license; grid mass edits still fire triggers/validation and count against DML limits

## FAQ

**How do you authenticate Conga with Salesforce?**

We connect Conga using the managed package with OAuth and store every secret in Salesforce Named Credentials with a permission set, so nothing is hard-coded or shipped in metadata.

**Does the Conga integration handle bulk volume?**

Yes. All Apex is bulkified, volume moves to Queueable or Batch Apex, and we respect the Salesforce governor limits (SOQL, DML, and callout caps per transaction).

**How do you prevent duplicate records?**

We upsert on a unique external-id field, so a retried or duplicate payload is idempotent and never creates a second document.

**How is the integration tested and deployed?**

Apex tests with HttpCalloutMock cover the success, failure, and a 200-record bulk case (75 percent plus coverage). We deploy via change sets or an SFDX and CI pipeline.

**What happens if Conga or Salesforce is briefly down?**

Failed calls retry with backoff and land in an Error Log object with alerting, so nothing is lost and any event can be replayed.

**Do we still need custom code?**

Usually only a thin layer: record-triggered flows or a small invocable Apex method to fire the package and write results back. The heavy lifting is the managed package.

---

Maintained by [Cloudsheer](https://www.cloudsheer.com). Full illustrated guide: [Conga technical guide](https://www.cloudsheer.com/integrations/conga/technical-guide). Want it built for you at a fixed price? [Book a free 30-minute call](https://cal.com/cloudsheer-consulting/30min?overlayCalendar=true).