Apex Connector Framework
The Apex Connector Framework is the Salesforce extension point for Salesforce Connect that lets developers build custom data sources, exposing external systems as External Objects in Salesforce.
Definition
The Apex Connector Framework is the Salesforce extension point for Salesforce Connect that lets developers build custom data sources, exposing external systems as External Objects in Salesforce. When the built-in Salesforce Connect adapters (OData 2.0, OData 4.0, Cross-Org) do not fit, the framework lets a developer write Apex classes that respond to query, search, and DML callbacks from the platform. The result is an External Object that looks like any other Salesforce object but reads from (and optionally writes to) an arbitrary backend: a REST API, a SOAP service, a custom queue, a third-party database, anywhere the developer's Apex code can reach.
The framework consists of two main base classes plus a set of provider interfaces. DataSource.Connection is the per-request connection that handles query, search, and DML operations. DataSource.Provider declares the connector's capabilities (whether it supports search, sync, write operations, OAuth refresh, and so on). The developer registers a Custom Adapter type in Setup pointing at the custom Apex provider, configures a Named Credential for authentication, creates an External Data Source referencing the custom type, then syncs External Objects from the data source. From that point on, External Objects appear in reports, lookups, and SOQL like any other Salesforce object.
How the Apex Connector Framework actually adapts a custom backend
When to use the framework vs. built-in adapters
Choose the built-in OData 4.0 adapter whenever the external source already speaks OData. Choose the Cross-Org adapter when the source is another Salesforce org. Reach for the Apex Connector Framework only when neither fits: a REST API with proprietary auth, a database that needs a custom protocol, a service that returns JSON shaped differently than OData expects. The framework is the most flexible option but also the most code-heavy; do not write Apex when standard adapters will do.
The Connection, Provider, and Capability hierarchy
DataSource.Provider is the top-level class. It declares the connector's name, advertises its capabilities (search, query, queryMore, sync, write), and returns a DataSource.Connection instance. The Connection handles the actual operations: sync, query, search, upsertRows, deleteRows. Capabilities are how the framework tells the platform what the connector supports, so unsupported operations error out cleanly rather than failing mid-query.
Sync, the schema discovery operation
The sync operation runs when an admin clicks Validate and Sync on the External Data Source. The Connection's sync method returns a list of DataSource.Table objects describing each external table, plus DataSource.Column objects for each field. The platform creates one External Object per Table, with matching custom fields. Subsequent sync calls reconcile schema changes (new columns, removed columns) into the existing External Objects.
Query, where SOQL meets external data
When a SOQL query touches an External Object, the platform translates it into a DataSource.QueryContext and calls the Connection's query method. The QueryContext carries the requested columns, filters, ordering, and pagination. The connector turns that into a backend API call and returns DataSource.TableSelection with rows. Anything the connector cannot push down to the backend (a complex filter the API does not support) must be filtered on the Apex side before returning.
Search support
External Objects can participate in Global Search if the connector implements search. The Connection's search method receives the user's query string and returns matching rows. Search results appear in the Salesforce search dropdown and on the Search Results page alongside Salesforce-native records. Implementing search is optional; connectors that skip it return queryable but un-searchable External Objects.
DML for writable External Objects
Writable External Objects need the connector to implement upsertRows and deleteRows. The platform packages user edits as DataSource.UpsertContext and calls the connector. The connector translates the writes into backend API calls and returns success/failure per row. Writes against External Objects are subject to additional governor limits and require the External Data Source to be flagged Writable.
Authentication via Named Credentials
Custom adapters never store credentials in code. Named Credentials hold the URL, auth profile (OAuth, JWT, password, API key), and certificate. The connector references the Named Credential by name when making the backend call, and Salesforce injects the right auth header at runtime. This is the same pattern as any Apex callout and keeps secrets out of metadata.
Limits and performance
Custom adapters share governor limits with the calling transaction. A SOQL query that triggers an Apex Connector callout uses CPU time, HTTP callout budget, and heap. Salesforce caps external object queries at 100 callouts per transaction by default. Performance depends entirely on the backend; a slow REST API turns into a slow record page in Salesforce. Caching strategies (storing materialised results in Custom Objects, or fronting the backend with a CDN) are common for high-traffic External Objects.
How to build an Apex Connector Framework adapter
Building a working custom adapter is a few hundred lines of Apex plus standard Setup configuration. The hard work is mapping the backend semantics onto the framework's Table, Column, and Filter abstractions.
- Set up the Named Credential
Setup, Named Credentials. Create a Named Credential with the backend URL and auth profile. The custom adapter references this credential by name for every callout.
- Write the DataSource.Provider class
Extend DataSource.Provider. Declare capabilities, return a DataSource.Connection instance, and implement getAuthenticationCapabilities and getCapabilities.
- Write the DataSource.Connection class
Extend DataSource.Connection. Implement sync, query, search, upsertRows, deleteRows as needed. Translate framework callbacks into REST or SOAP calls to the backend.
- Register the custom adapter in Setup
Setup, External Data Sources. Click New, choose Type Custom Adapter, and select the Provider class. Save and click Validate and Sync.
- Sync External Objects and test
After sync, External Objects appear in Object Manager. Run a SOQL query against one, verify the backend call fires, and confirm the returned data matches expectations.
Top-level Apex class declaring capabilities and returning a Connection.
Implements sync, query, search, and optional DML operations.
Holds backend URL and auth profile referenced by the connector.
Setup record that ties the Custom Adapter type to the Provider class.
Salesforce objects auto-generated by sync from the backend schema.
- Anything the connector cannot push down to the backend (a filter the API does not support) must be applied on the Apex side. Forgetting this returns wrong results.
- Writes need the External Data Source flagged Writable plus upsertRows and deleteRows implementations. Read-only adapters cannot accept DML.
- External Object queries share governor limits with the calling transaction. A heavy Lightning page that loads three External Objects can exhaust CPU time.
- Schema changes on the backend require a re-sync. Adding a column to the backend without re-syncing leaves the External Object's schema stale.
Trust & references
Cross-checked against the following references.
- Apex Connector Framework ExamplesApex Developer Guide
- Salesforce Connect OverviewSalesforce Help
Straight from the source - Salesforce's reference material on Apex Connector Framework.
- DataSource.Provider ReferenceApex Developer Guide
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the Apex Connector Framework used for?
Q2. Which Apex interfaces do you implement when building a custom adapter?
Q3. When should you build a custom adapter instead of using a built-in one?
Discussion
Loading discussion…