Heroku Connect Diagnostics
Last updated 11 October 2018
Table of Contents
Heroku Connect interacts with your Salesforce org and your Postgres database in a variety of ways, which means there are a number of factors than can impact the performance, reliability and correctness of sync operations.
We provide a CLI plugin to inspect the current state of your connection and perform basic operations. One of those operations is the ability to run some simple diagnostics to identify common problems that may affect you, using the connect:diagnose command.
$ heroku connect:diagnose --verbose
Diagnosing connection... done
=== Connection: protected-ridge-4963
GREEN: Salesforce API Version
GREEN: Number of Mappings
GREEN: Database Plan
=== Account
GREEN: Calculated Fields
GREEN: Upsert Field
GREEN: Binary Fields
GREEN: Number of Fields
GREEN: Required Fields
Results can be either red, yellow or green. Red results indicate errors that are likely causing problems with the flow of data. Yellow results indicate warnings that may or may not be actual problems, depending on your application. Both red or yellow results will include additional details about the problem, as well as a link to more documentation, where applicable. Green results indicate no known problems, and therefore no additional detail is provided.
Connection Checks
Check: Salesforce API Version
Salesforce periodically upgrades the capabilities of its API, but Heroku Connect will not automatically use newer versions as they’re released, in order to ensure consistency in how your data is handled. If you’re using a very old API version, you should consider recreating your connection with a newer API version.
Check: Number of Mappings
Heroku Connect performance degrades as more mappings are added to your connection. This affects reading from and writing to Salesforce, as well as the responsiveness of your dashboard.
Check: Heroku Postgres
Normal operation and customer support of Heroku Connect rely on services only available on Heroku Postgres. Other database providers are not supported.
Check: Database Plan
Hobby tier Postgres databases are underpowered for typical Heroku Connect usage. If you’re using the paid enterprise or danketsu Heroku Connect plans, you should also be using a paid Heroku Postgres plan.
Check: Data Locality
Heroku Connect operates in multiple regions around the world, and it works best when your app and its database are located in the same region as the connection that syncs your data. Having your connection and database in different regions can introduce significant delay in transferring data.
Check: View/Modify All Permissions
Heroku Connect works best when the authorized Salesforce user has View All and, if necessary, Modify All permissions on each mapped object. Without these permissions, queries to Salesforce can take longer, and may return incomplete data.
Read more: Resolving read errors
Check: Configured Log Drain
You can monitor and analyze Heroku Connect’s logs if a log drain is configured for either your app or your Shield Private Space. We strongly recommend that you configure a log drain so that you can view historical logs.
Mapping Checks
Check: Binary Fields
Binary fields aren’t supported by Heroku Connect, and may not behave as you expect.
Read more: Base64 binary fields
Check: Calculated Fields
Calculated fields aren’t supported by Heroku Connect, and may not behave as you expect.
Read more: Cross-object formula and roll-up summary fields
Check: Number of Fields
When Heroku Connect pulls data from Salesforce, it reads in the entire record at once. When a lot of fields are mapped, this can severely degrade performance.
Check: Required Fields
There are a number of fields required for Heroku Connect to properly insert data from Postgres into Salesforce. If you have failed to map any of the required fields in Heroku Connect, you’ll need to ensure they’re being populated in Salesforce, for example by using a “before insert” trigger in Apex code.
Check: Unique Identifier
When writing from Postgres to Salesforce, a unique-identier is required to ensure that data can be matched correctly between the two systems. A unique identifier must be defined as a unique external ID field in Salesforce.
Read more: Unique identifier
Check: Number of Large Text Area Fields
When Heroku Connect pulls data from Salesforce, it reads in the entire record at once. When this includes multiple large text area fields (which can be Long Text Area fields or Rich Text Area fields), this can severely degrade performance.
Check: Synthetic Fields
Synthetic fields are created by Heroku Connect and used to reference objects when writing data to Salesforce. Synthetic fields are unnecessary for read-only mappings and typically shouldn’t be mapped. In cases where you need or expect to switch between read-only and read-write, they can be mapped.
Check: Salesforce Field Changes
When the definition of a mapped field is changed in Salesforce, a corresponding change needs to be made to your database. On the Edit Mapping screen, Heroku Connect will check for changed fields and will display warnings if there are changes. A change will be one of:
- An increase to the length of a text field – Heroku Connect will alter your database table to increase the length of the field.
- Any other change – these are considered to be unsafe and require you to:
- Remove the field from the mapping by editing the mapping, unselecting the field, and saving the mapping.
- Add the field to the mapping again by editing the mapping, selecting the field, and saving the mapping.
Check: Database Field Changes
Heroku Connect expects to manage the schema of the tables it syncs. Any fields that are added, removed, or altered by something other than Heroku Connect will need to be restored to the state that Heroku Connect expects. To correct the problem using the dashboard, go to the Edit Mapping screen. Heroku Connect will check for the following changes:
- Added or removed fields – upon saving the mapping, Heroku Connect will alter your database table automatically.
- Altered fields – you need to remove and then re-add the altered fields:
- Remove the altered fields from the mapping by editing the mapping, unselecting the fields, and saving the mapping.
- Add the fields to the mapping again by editing the mapping, selecting the fields, and saving the mapping.
Check: IsArchived Field
Task and Event objects have an IsArchived field that allows archiving of these objects, removing from view without fully deleting them from the system. But Salesforce doesn’t mark records as modified when this happens, so we have no way to reliably detect changes to the IsArchived field. We would only get updates to its value when something else on the record also changed, so it’s very easy for this field to contain different data between Salesforce and Heroku.
Check: Polymorphic External ID
Heroku Connect uses external IDs to uniquely identify records within Postgres, before Salesforce has issued its own IDs. In order to accurately reference records in a related object, Heroku Connect needs to know which object the ID will refer to. Therefore, polymorphic fields, like WhatId and WhoId, which can reference more than one type of object, cannot be used as external IDs with Heroku Connect.
Check: Maximum Record Size
When writing data to Salesforce, the APIs involved have a limit to how much data can be provided in a single record. If your data exceeds this limit, Heroku Connect may fail to write the record to Salesforce. Because the limit is based on actual data in the record, this check simply checks for a mapping that could conceivably contain enough to data to exceed the API limits.
Check: Query Size
When Heroku Connect retrieves data from Salesforce, it issues SOQL a query containing only the fields that you’ve mapped, to avoid transferring more data than necessary. For mappings with a large number of fields, or with very long field names, that SOQL query can exceed the limits imposed by the Salesforce API.
Check: Synthetic Field/Unique Identifier Agreement
When mapping a synthetic field, the field on the related object should also be configured as a unique-identifier on that object, if you have a unique-identifier configured. This helps ensure that you can populate multiple records in Postgres using that field as an external ID, and have all the records match up properly in Salesforce.