Last updated February 28, 2025

A Heroku Connect mapping determines how a Salesforce object and its fields are persisted in Heroku Postgres and Salesforce. Mappings can be read-only from Salesforce, or read-write. Each mapping has its own polling method and frequency. This article is a reference of the configuration options available for mappings.

Supported Salesforce Objects

The Supported Salesforce Standard Objects page lists the objects that can be mapped for the version of the Salesforce API being used by your connection.

Missing Objects and Fields

The most common reason for Heroku Connect not showing specific objects or fields upon creating or editing a mapping is insufficient permissions. Check the permissions for the Salesforce user used to authorize the connection and modify those permissions. Heroku Connect requires View All permissions for optimal operation. If an object doesn’t have that option, use View All Data instead.

Unsupported Objects

Heroku Connect supports most standard and custom objects that are retrievable via the SOAP and Bulk APIs. Greyed-out objects have caveats due to Salesforce API limitations. Exceptions are objects that require the use of object-specific filter criteria or aren’t fully supported by Bulk API. For example, these objects can’t be mapped with Heroku Connect:

• KnowledgeArticleVersion and objects that end with __kav require the use of additional query criteria (PublishStatus=Online).
• LeadHistory doesn’t support Bulk Paging and can’t be retrieved when there are more than 20,000 changed records to sync.
• The Base64 type of Attachment is unsupported by Bulk API and can’t be retrieved when there are more than 20,000 changed records to sync. This means that images or other types of binary data are unsupported. An alternative approach is to store images in Amazon S3 and sync a simple text field containing a URI for the image between Salesforce and your database.
• Archiving Event and Task objects in Salesforce results in the IsArchived flag being set. Since the Salesforce Bulk API can’t retrieve archived Events and Tasks, Heroku Connect can’t synchronize them. Only unarchived Events and Tasks are synced.

Other exceptions and warnings apply. See Heroku Connect Database Tables for more info.

Read Mode: Salesforce to Heroku Postgres Sync

Mappings are read-only by default: Heroku Connect polls your Salesforce org for changes and synchronizes them to your database. Changes made in your Heroku Postgres database don’t synchronize back to Salesforce unless you enable write mode.

You can select a sync method and frequency when creating or editing a mapping: standard polling or accelerated polling.

Standard Polling of Salesforce

By default, Heroku Connect polls your Salesforce org for changes every ten minutes. The interval can range from two minutes (ten minutes in the demo plan) to 60 minutes. You can change the polling interval in one-minute increments.

A shorter polling interval is suitable for mappings where data changes frequently. A longer polling interval is best for mappings that change less often as it reduces API usage and processing overhead.

Accelerated Polling of Salesforce

Accelerated polling is ‘polling on demand’ versus the standard ‘polling at a fixed interval’.

Accelerated polling uses Salesforce’s Streaming API to notify Heroku Connect when data changes in your mapped objects in Salesforce. Heroku Connect uses these notifications to trigger polling in addition to standard polling.

Accelerated polling is available for all custom objects and some standard objects. For those objects that don’t support streaming, you can’t select this option when creating or editing a mapping.

If multiple notifications are received within a ten-second period, Connect triggers a single poll to reduce Salesforce API utilization.

Enable Write Mode: Heroku Postgres to Salesforce Sync

To enable sync between Postgres back to your Salesforce org, check the Write database updates box in the Database > Salesforce section of the create/edit mapping page. See Writing to Salesforce for more details about how Connect writes to Salesforce.

All read-write mappings are synced using the same write algorithm chosen for the entire Heroku Connect instance.

Unique Identifier

Because Heroku Connect uses separate threads for reading and writing, use unique identifiers to prevent duplicate records. You can set a unique identifier (external ID) for each read-write mapping.

Salesforce provides a mechanism to define a custom field with the External ID and Unique attributes. These attributes help uniquely identify records coming from an external source, such as Heroku Postgres. You must enable both attributes on a field in Salesforce before you can select it as the unique identifier for a mapping.

When writing changes from Salesforce to Heroku Postgres, Heroku Connect matches records coming from Salesforce by the Salesforce ID (sfid) or by the unique identifier if the Salesforce ID is NULL.

If there’s no sfid or unique identifier match, Connect creates a new, duplicate record in Postgres. The duplicate has the sfid retrieved from Salesforce while the original record is left without a sfid. Using a unique identifier ensures that no matter which process attempts to write the record first, there are no integrity errors and the record is always matched. You can also reference the newly inserted row from a foreign table by this external id. See Simple Relationships Between Two Objects and Relationship External IDs for more info.

There are several considerations to keep in mind while using unique identifiers with Heroku Connect: Treat unique external IDs as aliases for a Salesforce ID. Don’t manually change these IDs. Choose a unique mechanism for generating external IDs, such as uuid_generate_v4() or gen_random_uuid() for generating random UUIDs. Postgres integer sequences aren’t recommended as they’re not guaranteed to be unique. Don’t use the ID field in the Heroku Connect database as the unique external ID. These ID numbers reset when importing your configuration into a new database or when reloading a table.

Re-inserted Records

Even when using unique identifiers, it’s possible to create duplicate records if you delete records in Salesforce shortly after syncing them via Heroku Connect.

See Re-inserted Records for more info.

Heroku Postgres Polling

Heroku Connect polls your Heroku Postgres database for updates every two minutes. This interval isn’t configurable. If updates are detected, Heroku Connect begins to write those changes back to Salesforce. Heroku Connect doesn’t poll for additional database updates while the write operation to Salesforce is underway. Write operations are executed across all mappings in chronological order. When a given write operation completes, the poll cycle begins again every two minutes.

In addition to the two-minute poll, your database attempts to detect new or updated records and notify Connect to initiate a poll using pg_notify. This notification happens at most every 10 seconds. These intervals aren’t configurable.

Troubleshooting Mapping Configurations (BAD_CONFIG)

Connect performs the following validations to ensure that your configuration is correct:

• The object isn’t a Big Object or a Platform Event.
• The object doesn’t require a filter to query (e.g., CollaborationGroupRecord, ContentDocumentLink, ContentFolderItem, ContentFolderMember, FeedPollVote, IdeaComment, KnowledgeArticleVersion, Vote, etc.)
• The object is listed as “queryable” by the Salesforce API
• The object doesn’t have implementation restrictions (e.g., KnowledgeArticleVersion objects)
• The object has a timestamp field that can be used for synchronization (e.g., SystemModstamp)
• The object has an Id field
• If the mapping is set to read-write, the object must be updateable
• The fields of the mapping have known types that can be mapped into Postgres types

If your mapping is in the BAD_CONFIG state, go through this list and edit your mapping accordingly. Heroku Connect attempts to recover from this error after you save your mapping changes.