Platform Salesforce Connect Adapter Generate

Salesforce Connect — Custom Apex Adapter

Route the user through building a complete custom Salesforce Connect Apex adapter: two Apex classes, metadata deployment, and registration. Do not guess at the user's API shape — ask before generating.

Scope

In scope: Generating DataSource.Connection and DataSource.Provider Apex classes, Named Credential metadata, deployment via sf CLI, and step-by-step Setup registration guidance for any REST API.

Out of scope: Configuring standard adapters (OData, Snowflake, GraphQL — those have their own flows). Generating the External Data Source metadata file (not deployable via sf CLI — must be registered manually in Setup). Writing Apex that calls external APIs outside the Salesforce Connect framework (use the platform-apex-generate or integration-connectivity-generate skills).

Before starting

Confirm two things. If either is missing, ask before proceeding.

1. Is this actually a Salesforce Connect use case?

If the user has a standard adapter available, tell them — writing a custom adapter when a standard one fits is unnecessary work.

2. Do they have a Salesforce Connect license?

A custom adapter requires a Salesforce Connect license (one license per External Data Source). Without it, the External Data Source menu won't show the Apex option. If the user doesn't have one, tell them before going further.

Default org context (when running locally)

If the user does not specify an org alias, use demo-org. If the user does not specify an SFDX project path, use ~/salesforce-connect-apex-skill/sfconnect-demo/. These are the defaults for local testing — always override if the user specifies their own.

Collect inputs before generating

Never generate code without these. If any are missing, ask:

If the user provides an OpenAPI spec, extract:

• All GET endpoints returning arrays → each becomes a DataSource.Table
• Response object properties → DataSource.Column entries
• id / uuid / primary key → map to ExternalId
• Property types → use the field type mapping table below

What to build

Every custom Salesforce Connect adapter is exactly two Apex classes.

DataSource.Connection

Handles communication with the external API. Exact signatures:

override global DataSource.TableResult query(DataSource.QueryContext context)
override global List<DataSource.TableResult> search(DataSource.SearchContext context)

// Write support — only if API supports it:
global override List<DataSource.UpsertResult> upsertRows(DataSource.UpsertContext context)
global override List<DataSource.DeleteResult> deleteRows(DataSource.DeleteContext context)

Key distinction: query() always operates on one table (QueryContext has a single TableSelection). search() can operate on multiple tables simultaneously (SearchContext has multiple TableSelection instances) — handle each in a loop and return a result per table.

DataSource.Provider

Declares the adapter's capabilities and schema to Salesforce. Required methods:

• getAuthenticationMode() — return ANONYMOUS for public APIs; NAMED_PRINCIPAL or PER_USER for authenticated APIs
• getCapabilities() — declare QUERY, SEARCH; add ROW_CREATE, ROW_UPDATE, ROW_DELETE only if implementing writes
• getConnection(ConnectionParams params) — return new YourConnection(params)
• sync() — called when the user clicks "Validate and Sync" in Setup; returns List<DataSource.Table> defining the External Object schema and columns

The Provider class appears in Salesforce Setup as Custom-[ClassName] under the External Data Source type dropdown.

Critical: whenever you edit the Connection class, you must resave the Provider class too — even with no changes. Otherwise the adapter disappears from the Type picklist and existing External Object tabs break.

Field type mapping

Every DataSource.Table must include these columns:

DataSource.Column.text('ExternalId', 255)  // unique key from external system — REQUIRED
DataSource.Column.text('Name', 255)        // display label shown in Salesforce UI — REQUIRED
DataSource.Column.url('DisplayUrl')        // link to the record in the external system — recommended

Missing ExternalId is the most common reason an adapter deploys but records don't appear. DisplayUrl enables the clickable link icon in list views — populate it with the external record's URL.

Scenarios

Four scenarios: (1) public read-only, (2) authenticated API key/OAuth, (3) read-write with upsert/delete, (4) paginated API. Full code patterns for each are in references/scenarios.md.

Key differences by scenario:

How to verify the adapter is working

Option 1 — SOQL via sf CLI (fastest, no UI needed)

sf data query \
  --query "SELECT ExternalId, Name__c FROM [YourObject]__x LIMIT 5" \
  --target-org [org-alias]

If rows come back, the adapter is working. If 0 rows, check the troubleshooting steps below.

Option 2 — Visualforce page (best for demos, works on any org)

Deploy a Visualforce page + Apex controller that queries [Object]__x and renders rows in an apex:pageBlockTable. Open at [orgUrl]/apex/[PageName]. More reliable than list views for testing — bypasses tab requirements, deployment status, and filter issues. See references/scenarios.md for the standard template.

Option 3 — List view (standard UI, but requires extra steps)

For the list view to show records, all four of these must be true:

1. External Object Deployment Status = Deployed (Object Manager → Edit)
2. A tab exists for the External Object (Setup → Tabs → Custom Object Tabs → New)
3. List view filter is set to All (not "Recently Viewed")
4. Remote Site Setting exists for the external API URL

Troubleshooting: 0 records with no error

What the agent deploys vs. what the developer does manually

Agent deploys (one sf project deploy start command)

Do NOT generate externalDataSources/[API].externalDataSource-meta.xml. The External Data Source must be registered manually in Setup after deploying the Apex classes. The sf project deploy start command cannot deploy custom Apex External Data Sources — the sf CLI will error with "Could not infer a metadata type." Tell the user to go to Setup → External Data Sources → New after deployment.

Correct NamedCredential XML format (no <name> element — the API name comes from the filename):

<?xml version="1.0" encoding="UTF-8"?>
<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>My API</label>
    <endpoint>https://api.example.com</endpoint>
    <allowMergeFieldsInBody>false</allowMergeFieldsInBody>
    <allowMergeFieldsInHeader>false</allowMergeFieldsInHeader>
    <generateAuthorizationHeader>false</generateAuthorizationHeader>
    <principalType>Anonymous</principalType>
    <protocol>NoAuthentication</protocol>
</NamedCredential>

Deploy command:

sf project deploy start \
  --source-dir force-app/main/default/ \
  --target-org [org-alias]

Developer does manually (always — no metadata equivalent exists)

Validate and Sync triggers a live call to the external API to discover its schema and create External Object definitions. This cannot be scripted.

Setup → External Data Sources → [your data source] → Validate and Sync
Check the box next to each External Object → Sync
App Launcher → search [External Object name] → confirm records appear

Always end with: "Deployment complete. One step left: open the External Data Source in Salesforce Setup and click Validate and Sync."