Salesforce Connect OData Setup Guide (Step-by-Step)

Salesforce Connect is one of the most powerful features in the Salesforce platform, yet it remains underused. The reason is not that it is hard to understand conceptually. Querying external data in real time instead of copying it makes obvious sense. The reason is that the setup process involves multiple moving parts across multiple systems, and the documentation tends to assume you already know what you are doing.

This guide walks through the complete setup process, from prerequisites through to working External Objects in your Salesforce org, using an OData 4.0 endpoint as the connection method.

Prerequisites

Before you begin, make sure you have the following in place.

Salesforce Edition and Licensing. Salesforce Connect is available in Enterprise, Performance, Unlimited, and Developer editions. You need at least one Salesforce Connect license assigned to your org (each license provides a set number of External Data Sources and External Objects). Check your org's license allocation under Setup > Company Information.

An OData 4.0 Endpoint. Salesforce Connect supports OData 2.0 and 4.0. OData 4.0 is the current standard and the one you should use for new integrations. You need a live, HTTPS-accessible OData endpoint that Salesforce can reach over the public internet. This endpoint must serve a valid OData service document and metadata document.

If you do not have an OData endpoint yet, this is where a tool like ForceCnx fits in. ForceCnx connects to your external database (PostgreSQL, Cloud SQL, or RDS) and generates an OData 4.0 endpoint automatically, handling schema introspection, query translation, and authentication. You can have a working endpoint in minutes without writing any server code.

Admin Access. You need Salesforce administrator permissions to create External Data Sources and sync External Objects. Specifically, you need the "Customize Application" permission.

Step 1: Prepare Your OData Endpoint

Your OData endpoint needs to serve three things correctly for Salesforce Connect to work.

The Service Document is available at the root URL of your endpoint (for example, https://your-endpoint.example.com/odata). It lists all available entity sets (tables) that Salesforce can access. Salesforce reads this document during the initial configuration to discover what data is available.

The Metadata Document is available at $metadata (for example, https://your-endpoint.example.com/odata/$metadata). It describes the schema of each entity set, including field names, data types, and key properties. Salesforce uses this to create External Object definitions.

Entity Set Queries respond to standard OData query operations like $filter, $orderby, $top, and $skip. Salesforce issues these when users view records, run reports, or execute SOQL against External Objects.

Before proceeding, verify your endpoint is working by opening the service document URL in a browser. You should see a JSON or XML document listing your entity sets. If you are using ForceCnx, the dashboard shows you the endpoint URL and lets you test the connection directly.

Step 2: Create the External Data Source in Salesforce

Log in to Salesforce and navigate to Setup. In the Quick Find box, search for External Data Sources and click it.

Click New External Data Source and fill in the following fields:

• External Data Source: Give it a descriptive label, such as "Production Database" or "Order Management System." This name appears in the Salesforce UI when administrators manage the connection.
• Name: The API name, auto-generated from the label. You can customize it but keep it concise.
• Type: Select Salesforce Connect: OData 4.0. This is critical. Do not select OData 2.0 unless your endpoint specifically requires it.
• URL: Enter the root URL of your OData endpoint. This is the service document URL (for example, https://your-endpoint.example.com/odata). Do not include $metadata or any entity set path.

Step 3: Configure Authentication

Scroll down to the Authentication section. Salesforce Connect supports several authentication methods for OData endpoints.

Per-User Authentication requires each Salesforce user to provide their own credentials for the external system. This is more secure but requires additional setup for each user.

Named Principal with Password Authentication uses a single set of credentials (username and password) shared across all users. This is simpler for read-only integrations.

OAuth 2.0 is the recommended method for production deployments. You configure an Auth Provider in Salesforce and provide the OAuth client credentials. ForceCnx supports OAuth 2.1, so you can generate client credentials directly from the ForceCnx dashboard under Settings and configure them in Salesforce.

For an initial test, Password Authentication is the fastest path. Select Identity Type: Named Principal and Authentication Protocol: Password Authentication, then enter the credentials for your OData endpoint.

Step 4: Validate and Save

Click Save. Salesforce will attempt to connect to your OData endpoint and fetch the service document. If the connection succeeds, you will see the data source listed in your External Data Sources.

If the connection fails, check the following common issues:

• URL format: Make sure there is no trailing slash and no extra path segments. The URL should point to the OData service root.
• HTTPS required: Salesforce requires HTTPS for external connections. Your endpoint must have a valid SSL certificate.
• Network accessibility: Salesforce needs to reach your endpoint over the public internet. If your database is behind a firewall, you need a service like ForceCnx that exposes a secure, public OData endpoint without opening your database to the internet directly.
• Authentication: Verify that your credentials are correct and that the authentication method matches what the endpoint expects.

Step 5: Sync the External Objects

After the External Data Source is saved, click the Validate and Sync button. Salesforce fetches the metadata document from your OData endpoint and displays a list of available entity sets (tables).

Select the tables you want to expose as External Objects in Salesforce. You do not have to sync all of them. Choose the ones that are relevant to your users.

Click Sync and Salesforce will create an External Object for each selected entity set. Each External Object will have fields corresponding to the columns in the source table, with data types mapped automatically from the OData metadata.

Step 6: Review and Customize External Objects

Navigate to Setup > External Objects to see the newly created objects. For each External Object, you may want to:

• Rename fields to match your organization's terminology. Salesforce creates field labels from the OData property names, which may not be user-friendly.
• Set up page layouts to control which fields appear when users view records.
• Add to related lists on standard objects. For example, if your External Object has an Account ID field, you can create an External Lookup relationship so the external records appear as a related list on Account records.
• Create list views to let users browse and filter external records directly.
• Add to reports and dashboards for cross-system reporting.

Step 7: Assign User Permissions

External Objects require specific permissions. In the relevant Profile or Permission Set:

• Enable Read access on the External Object under Object Permissions.
• Ensure field-level security is configured for the fields users need to see.
• If using per-user authentication, each user needs to configure their external system credentials under My Settings > Authentication Settings for External Systems.

Testing Your Integration

Once permissions are in place, navigate to the External Object's tab (you may need to add it to your app's navigation). You should see records fetched in real time from your external database.

Try these tests to verify everything works:

• List view: Do records load? Can you sort and filter?
• Detail page: Click into a record. Do all fields display correctly?
• SOQL query: In the Developer Console, run a simple SOQL query against the External Object (for example, SELECT Id, Name__c FROM OrderHistory__x LIMIT 10). Note that External Object API names end in __x, not __c.
• Related list: If you set up a lookup relationship, verify that external records appear on the parent record's related list.
• Reports: Create a simple report using the External Object to confirm reporting works.

Common Pitfalls and How to Avoid Them

Timeout errors. Salesforce imposes timeout limits on external callouts. If your OData endpoint is slow to respond (because of large queries or an unoptimized database), users will see timeout errors. Make sure your source database has appropriate indexes on columns used for filtering and sorting.

Field type mismatches. OData and Salesforce have different type systems. Most mappings are straightforward, but some edge cases (like large decimals or timezone-aware timestamps) can cause issues. Review the field types after syncing and adjust if needed.

Row limits. Salesforce Connect imposes row limits on External Object queries (typically 2,000 rows per request). This is by design since External Objects are meant for targeted queries, not bulk data pulls. Design your page layouts and reports accordingly.

Schema changes. If you add or remove columns in your source database, you need to re-sync the External Object in Salesforce. ForceCnx handles this gracefully by reflecting schema changes in the OData metadata automatically; you just need to click Validate and Sync again in Salesforce.

Where ForceCnx Fits

The hardest part of this entire setup is Step 1: having a working OData endpoint. Building one from scratch means implementing the OData specification, handling SQL translation, managing authentication, and keeping the schema in sync with your database. That can take weeks or months of development.

ForceCnx eliminates Step 1 entirely. You connect your PostgreSQL, Cloud SQL, or RDS database, choose which tables to expose, configure field mappings, and get a production-ready OData 4.0 endpoint. The free tier includes one connection and five entities, enough to complete this entire guide and have a working integration.

The rest of the steps in this guide stay exactly the same regardless of how you create your OData endpoint. Salesforce Connect does not care whether the endpoint is a custom server, an enterprise middleware platform, or ForceCnx. It just needs a compliant OData service.

Start with ForceCnx's free tier, walk through these steps, and see your external data appear in Salesforce in real time. Once you see it working, you will wonder why you ever considered copying data.