External Object
An External Object is a Salesforce object that represents data living in an external system rather than in the Salesforce database.
Definition
An External Object is a Salesforce object that represents data living in an external system rather than in the Salesforce database. The records appear and behave like normal Salesforce records in the UI (page layouts, list views, related lists, lookup pickers), but each request resolves through Salesforce Connect to the underlying source system. External Objects use the __x API suffix and are the Salesforce-side projection of an OData service, a cross-org connector, or a custom Apex adapter.
External Objects exist to give Salesforce users and Apex code a unified data model that spans Salesforce and external systems without copying data. A field-service team can see SAP work orders next to Salesforce Cases without an integration pipeline that moves rows between systems. A finance team can see ledger entries from Oracle alongside Opportunity records without ETL. The pattern preserves the source system as the single source of truth, with Salesforce acting as a read (and sometimes write) view. Salesforce Connect is the platform component that makes External Objects work, and it is licensed separately from base CRM.
How External Objects bring external data into Salesforce
The Salesforce Connect dependency
External Objects only exist with Salesforce Connect. The add-on enables three connector types: OData 2.0/4.0 for standards-compliant external services, Cross-Org for connecting two Salesforce orgs, and the Apex Connector Framework for custom protocols. Without Salesforce Connect, the External Object type does not appear in Object Manager. Connect is licensed per external table and per user, so cost scales with the breadth of integration. Confirm licensing before designing around External Objects.
Auto-generated metadata from the external schema
External Objects are generated automatically from the external data source schema. Setup > External Data Sources > Validate and Sync pulls the schema from the connected service and creates one External Object per table or entity. Salesforce maps field types (Date, Decimal, String) to their nearest Salesforce equivalent. Manual schema edits afterward are limited; the source system controls the structure. Plan field-name renames and type changes on the source side, then re-sync to propagate to Salesforce.
Read versus write behavior
Most External Objects are read-only by default. Writeable External Objects require the underlying connector to support write operations (OData services with insert/update/delete endpoints, Apex adapters with the WritableConnection class). When writable, normal DML on the External Object propagates the change to the source system in the same transaction. Cross-Org External Objects support writes when the target org allows it. Read-only is the typical pattern because most external systems are systems of record that Salesforce should not mutate.
Relationships: external lookup and indirect lookup
External Objects participate in three relationship types beyond the standard lookup and master-detail. External Lookup goes from any Salesforce object to an External Object, keyed on the external system primary ID. Indirect Lookup goes from an External Object to a Salesforce object, keyed on a unique External ID field on the Salesforce side. Hierarchical Relationship is supported for self-referencing structures. Picking the right relationship type depends on the direction of the join, which is the most common design mistake in External Object architecture.
Reporting and analytics through External Objects
External Objects appear in standard reports and dashboards through External Lookup. The report engine pushes filters and aggregations to the source system on every run. There is no Salesforce-side cache by default; each report run consumes API capacity on the external system. The Salesforce Connect Cache option (paid add-on) lets External Object data cache for a configurable TTL, which helps performance but introduces staleness. Plan reporting load carefully because dashboards built on External Objects can starve the source system during business hours.
SOQL behavior and pushdown limits
SOQL queries against External Objects translate to the underlying protocol query. OData translates SOQL WHERE clauses into OData filters. The connector framework respects pushdown rules that determine which filters run on the external side versus the Salesforce side. Complex SOQL (joins, subqueries, aggregate functions) may not push down efficiently, forcing Salesforce to fetch broad result sets and filter locally. Test SOQL with realistic data volumes; pushdown behavior is the largest factor in External Object query performance.
Common patterns and licensing trade-offs
Field service: bring SAP work orders into Salesforce alongside Cases, with External Lookup connecting Case to Order. Finance: surface ledger entries from Oracle alongside Account records. Cross-org: join two Salesforce orgs through cross-org External Objects for federated reporting. Each pattern needs Salesforce Connect licensing per table, and the cost calculation is part of the architecture decision. For very high-frequency access, sometimes a periodic ETL into custom objects beats Salesforce Connect on total cost.
How to set up an External Object
Setting up an External Object has two layers: getting Salesforce Connect configured (data source, named credential, connector type) and exposing the external schema as External Objects (validate and sync, field mapping, relationship design). Both layers need careful design because the source system constrains what is possible.
- Confirm Salesforce Connect licensing
Check Setup > Company Information for the Salesforce Connect add-on entitlement. Without it, External Data Sources cannot be registered and External Objects do not appear. Talk to the account executive if licensing is missing because Connect is sold per external table and per user.
- Register the external data source
Setup > External Data Sources > New. Pick the connector type: OData 2.0, OData 4.0, Cross-Org, or a custom Apex adapter. Provide the service URL, named credential for authentication, and any required certificates. Click Validate to confirm Salesforce can reach the endpoint.
- Validate and sync the external schema
From the data source detail page > Validate and Sync. The platform fetches the schema and shows the tables available for synchronization. Select the tables to expose as External Objects. Each selected table becomes an External Object with the __x suffix and a default external ID field.
- Review the generated External Objects
Setup > External Objects shows the synced objects. Review the auto-generated field mappings. Field types map to nearest Salesforce equivalents; review for correctness, especially for date and numeric precision conversions that the source system may handle differently.
- Add relationship fields between Salesforce and External Objects
External Lookup from a standard or custom object points to an External Object. Indirect Lookup on the External Object points to a Salesforce object using a unique external ID. Plan the direction of the join carefully before creating the field.
- Configure page layouts and FLS
Add the External Object fields to page layouts where the data should appear. Set field-level security per profile. Add the External Object as a related list on parent Salesforce objects so users see external rows in context.
- Test with users across profiles
Log in as users with different profile and permission set combinations. Confirm external rows resolve correctly. If rows render as blank, check the named credential, the external user permissions on the source system, and the connector authentication chain.
- Add monitoring for the external connection
Build a periodic health-check Apex job that queries one external record. Alert if response time exceeds the threshold the business can tolerate. Build a dashboard that surfaces failed connector calls. External system slowness directly degrades Salesforce UX.
The registered service that exposes external tables. Configured with endpoint, named credential, and connector type.
The unique identifier from the source system. Auto-generated per External Object during schema sync.
External Lookup (Salesforce to external) or Indirect Lookup (external to Salesforce). Drives the direction of the join.
- External Objects require Salesforce Connect, which is licensed separately from base CRM and per external table. Without the add-on, the object type does not appear in Object Manager.
- External Object queries push down to the source system on every read. Reporting workloads can starve the external system during business hours unless the Salesforce Connect cache is enabled.
- External Object schema is controlled by the source system. Field-name changes or type changes on the source side require re-syncing the External Object metadata in Salesforce.
- Read-only is the default. Writable External Objects require connector-side support and careful coordination with the source system owner because writes propagate immediately.
- Complex SOQL (joins, subqueries) does not always push down to the external system, forcing Salesforce to fetch broad result sets and filter locally. Test query performance with realistic volumes.
Trust & references
Cross-checked against the following references.
- Salesforce Connect OverviewSalesforce Help
- External ObjectsSalesforce Help
- Salesforce Connect ConsiderationsSalesforce Help
Straight from the source - Salesforce's reference material on External Object.
- External Data SourcesSalesforce Help
- Relationship Fields on External ObjectsSalesforce Help
- Apex Connector FrameworkSalesforce Developer
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 an External Object?
Q2. What suffix do External Object API names have?
Q3. What technology powers External Object data access?
Discussion
Loading discussion…