Last updated February 24, 2023

A Heroku Connect mapping determines how a Salesforce object and its fields are persisted in Heroku Postgres and Salesforce. This article covers the operations used to manage your mappings from the Heroku Connect dashboard. To manage mappings via the API or CLI, see Heroku Connect API.

Create a Mapping

To create a mapping:

1. Click Create Mapping on the Mappings tab of the Heroku Connect dashboard.

2. Use the search box to filter the list of objects that can be mapped from your Salesforce org. Click the object that you want to map.

3. Choose the synchronization options, including choosing between a read-only or a read-write mapping.

4. Select the fields that you want to map. Some fields in the list are pre-selected and can’t be removed from the mapping as they’re required for Heroku Connect to perform synchronization.

   It’s recommended that certain fields, such as CreatedDate and Name, are mapped to ensure you get the best experience from Heroku Connect. These fields are selected by default when creating a mapping but can be deselected.

5. To help optimize common queries, configure one or more simple indexes for a mapping. Check the checkbox in the Indexed column, for each field you wish to be indexed. Alternatively, you can create complex indexes via PostgreSQL manually. Indexes created via Connect are preserved when importing your configuration into another connection, while indexes created via PostgreSQL are not.

6. Click Save and Heroku Connect creates a table in your database corresponding to the Salesforce object. It queries for all records from Salesforce and inserts them into the mapped table.

Edit a Mapping

Editing an existing mapping modifies the existing database table using the ALTER TABLE SQL command. Heroku Connect populates newly mapped fields with data from Salesforce.

To edit an existing mapping:

1. Click the Mappings tab of the Heroku Connect dashboard.
2. On the mapping detail page, click the icon with arrows and select Edit from the menu.
3. Edit the synchronization options and add or remove fields from the mapping.
4. Click Save. Heroku Connect updates the mapped database table to add and remove columns. It also queries Salesforce for data for any new fields to update existing records in the database.

Delete a Mapping

To delete an existing mapping:

1. If the mapping is in one of the data loading states, then Abort before proceeding.
2. Click the Mappings tab of the Heroku Connect dashboard.
3. On the mapping detail page, click the icon with arrows and select Delete from the menu.

When you delete a mapping from Connect, the underlying data table in Postgres is removed. Connect also attempts to remove any pending writes for the mapping from your trigger log.

Reload a Mapping

Reloading a mapping removes all existing rows in your mapped Postgres table. Pending writes in your trigger log are also destroyed so any Postgres data that isn’t written to Salesforce is lost. All records are reloaded from Salesforce using the SOAP or Bulk API, depending on the number of records. This operation assigns new values for the ‘ID’ column.

For mappings with a large number of records, consider putting your application into maintenance mode for the reload process.

To reload a mapping:

1. Click the Mappings tab of the Heroku Connect dashboard.
2. On the mapping detail page, click the icon with arrows and select Reload from the menu.
3. On the confirmation window, click Yes.

Import and Export of Mappings

You can export your existing mapping configuration to a JSON file. You can make bulk changes to mappings by editing and importing the JSON file.

You can also import the configuration into multiple Heroku Connect instances with the same mappings, such as for multi-org setups.

To export your current configuration to a JSON file:

1. Click the Settings tab in the Heroku Connect dashboard.
2. Click Import/Export Configuration.
3. Click Export.
4. Click Export in the confirmation window to download the file.

To import a JSON configuration file:

1. Click the Settings tab in the Heroku Connect dashboard.
2. Click Import/Export Configuration.
3. Click Import.
4. Click Choose file and select the file to upload.
5. Click Upload to begin the import.

On successful completion of the import, Heroku Connect starts syncing data from your Salesforce org into the database.

Abort a Mapping

Aborting a mapping cancels all operations running on that mapping, allowing for other actions to take place. Aborting a mapping is useful if an operation is running longer than expected, was started accidentally, or if a mapping that is currently loading data must be deleted.

To abort a mapping:

1. Click the Mappings tab of the Heroku Connect dashboard.
2. On the mapping detail page, click the icon with arrows and select Abort from the menu.

See States and Aborted Mapping Operations for more info about recovering from the ABORTED state.

Manage Orphaned Mappings

Orphaned mappings are objects removed or renamed in your Salesforce org that still have mappings in Heroku Connect. To view and remove these mappings:

1. Open the Heroku Connect dashboard.
2. Click the Settings tab.
3. Click Manage Connection.
4. Scroll to the Orphaned Mappings section and click Remove Orphaned Mappings to delete them from your configuration.

Manage Changed Field Definitions in Salesforce

After changing a field in Salesforce, you must edit the object’s mapping in Heroku Connect to trigger an update to the Heroku Postgres table schema.

In most cases, such as changes that extend the length of a field, you can click Edit for the mapping and then click Save.

In more complex cases, such as changing field types, you must edit the mapping twice. First, edit the mapping to deselect the field and save so that Connect drops the column. Then, edit the mapping again to re-add the field and save. Connect re-adds and loads the data back into the column.