Integrating Heroku and the Salesforce Platform

Last updated 09 October 2019

You can integrate Heroku and the Salesforce Platform in several ways, and choosing among them comes down to understanding your requirements and the capabilities of each integration type.

This article describes, at a fairly high level, each type of integration; outlines its pros and cons; and points to documentation that can help you implement the integration.

Overview

Heroku Connect

Heroku Connect is an add-on that synchronizes data between your Salesforce objects and a Heroku Postgres database that’s attached to your Heroku application. Using a simple declarative interface, you determine which Salesforce objects should sync with which Postgres tables, mapping object fields to table columns. Heroku Connect then continually monitors (depending on the sync directions) the org and the tables, ensuring that objects and rows are created as necessary.

When to use

Heroku Connect provides a pure data integration—only object and table data are synced. This architecture is useful in many scenarios where you want a Heroku application to store or manipulate the data. For example, you could have one or more Salesforce orgs syncing to the same Heroku Postgres database, and perform periodic actions such as analytics, invoice generation, lookups with other services, and so on. The output of these actions could modify existing database rows, or generate new ones in a different table that’s synced back to Salesforce, if needed.

To ensure that certain actions take place when your data is synced to Salesforce, you can create triggers on Salesforce. For example, a record synced from Heroku to Salesforce could trigger an action for an approval queue.

If you’re building a Heroku app or already have data in Heroku Postgres, then Heroku Connect is a good fit for your Heroku-Salesforce integration.

Limits & considerations

Heroku Connect data sync does not count against Salesforce API limits.

The Heroku Connect FAQ and Supported Objects documentation describe other limits, including not being able to sync a subset of an Object, or base64-encoded fields.

By default, Heroku Connect will poll your Salesforce org for changes to sync every ten minutes. It also offers accelerated polling for some objects.

Learn more

• Follow the Getting Started on Heroku with Heroku Connect to get started.
• Read the Heroku Connect documentation.

Salesforce Platform Events

You can architect apps using an event-driven approach with the Salesforce enterprise messaging platform. Platform Events provides a powerful technique for integrating internal components within a Salesforce app, or for integrating such components with external systems, such as Heroku apps. The architecture is suitable for large distributed systems because it decouples event producers from event consumers, simplifying the communication model in connected systems.

Heroku applications can behave as event producers, event consumers, or some combination of the two.

Publishing Platform Events from Heroku

Event publication is carried out by Calling the Salesforce REST API below—it’s a matter of having a Heroku application create an sObject representing the event and POSTing to the appropriate endpoint, with something like: /services/data/v43.0/sobjects/Event_Name__e/.

Using a Salesforce API client library, like JSforce for Node.js, write something like this to publish an event (in this case, a Flight_Approved event):

// Establish an authenticated Salesforce connection. (Details elided)
const conn = new jsforce.Connection({ … });

const eventData = {
  Flight_Id__c: id,
  Confirmation_Number__c: confirmationNumber
};

conn.sobject('Flight_Approved__e').create(eventData, (err, res) => {
  if (err) {
      console.error(err);
  } else {
      console.log("Event published");
  }
});

Subscribing to Platform Events

Heroku apps can subscribe to events with the CometD protocol. Salesforce sends platform events to CometD clients sequentially in the order that they’re received. The order of event notifications is based on the replay IDs of events.

In Node.js apps, for example, you can use the JSforce module to configure a subscription with replay:

// Establish an authenticated Salesforce connection. (Details elided)
const conn = new jsforce.Connection({ … });

const channel = "/event/Flight_Approved__e";
const replayId = -2; // -2 is all retained events

const replayExt = new jsforce.StreamingExtension.Replay(channel, replayId);

const fayeClient = conn.streaming.createClient([ replayExt ]);

const subscription = fayeClient.subscribe(channel, data => {
  console.log('Received Flight Approved Event', data);
});

When to use

You want to build a modern integration with the Salesforce enterprise messaging platform. The messaging platform lets you build modular integrations with clean integration boundaries using a messaging bus, instead of point-to-point integrations.

Limits & considerations

Read the Salesforce docs that describe what to consider when building with Platform Events, including avoiding infinite trigger loops, API limits, and more.

Security and Heroku/Salesforce integrations shows how to secure this integration.

Learn more

• Platform Events Developer Guide
• Publish Event Messages with Salesforce APIs
• Subscribe to Platform Event Notifications with CometD
• The Faye modules for Node.js and Ruby

Calling the Salesforce REST API

The Salesforce platform provides a comprehensive REST API that can be called from a Heroku application. The API provides OAuth 2.0 or session ID authentication, and allows you to query Object Metadata, create or modify records, execute SOQL/SOSL queries, and interact with approval processes.

Community libraries, such as nforce or JSForce for Node.js, can provide convenience wrappers for invoking the API. Such libraries are available for most languages. Once a client is authenticated, performing a SOQL query and updating an object looks something like this:

var q = 'SELECT Id, Name, CreatedDate, BillingCity FROM Account WHERE Name = "Spiffy Cleaners" LIMIT 1';

org.query({ query: q }, function(err, resp){

  if(!err && resp.records) {

    var acc = resp.records[0];
    acc.set('Name', 'Really Spiffy Cleaners');
    acc.set('Industry', 'Cleaners');

    org.update({ sobject: acc, oauth: oauth }, function(err, resp){
      if(!err) console.log('It worked!');
    });

  }
});

When to use

Use the REST API in scenarios where you need more than just a data integration. You must be prepared to build a reasonably low-level integration using the REST API, but after you do, the API does let you perform a considerable number of actions on Salesforce.

Limits & considerations

See the Implementation Considerations of the API documentation, which outline concurrent API request limits, API calls per license type, API calls per day, and so on.

Security and Heroku/Salesforce integrations shows how to secure this integration.

Learn more

• The REST API documentation.
• A Reference Guide to the various end points.
• Integration libraries for Node.js, Ruby

Apex and Workflow callouts

There are two primary methods for calling into a Heroku app with an API, based on an activity in Salesforce:

• Apex HTTP callouts for programmatically making REST calls.
• Workflow outbound messages for declaratively making SOAP calls.

Either way, the Heroku app receives a request with the event details payload, and then performs the action.

Apex HTTP callouts

With Apex callouts, you can tightly integrate your Apex with an external service, in this case, an app running on Heroku. Apex provides facilities for serialising objects into JSON and asynchronously calling HTTP endpoints. For example, here’s a helper class that can serialise an object and asynchronously POST the data to a Heroku endpoint:

public class Helper {
  public static String jsonContent(List<Object> triggerNew) {
    String newObjects = '[]';
    if (triggerNew != null) {
      newObjects = JSON.serialize(triggerNew);
    }
    String content = '{"new": ' + newObjects}';
    return content;
  }
  @future(callout=true) public static void callout(String url, String content) {
    Http h = new Http();
    HttpRequest req = new HttpRequest();
    req.setEndpoint(url);
    req.setMethod('POST');
    req.setHeader('Content-Type', 'application/json');
    req.setBody(content);
    h.send(req);
  }
}

You can then invoke that method as needed, perhaps attached to a trigger:

 trigger NewContactHerokuTrigger on Contact (after insert) {
  String endpoint = 'https://foo.herokuapp.com/api/action';
  String content = Helper.jsonContent(Trigger.new);
  Helper.callout(url, content);
}

Ensure that your Heroku application listens on the same API endpoint, and that it implements the appropriate action on receiving an HTTP POST. You can additionally send a session ID to allow the Heroku app to make calls back into Salesforce using the Salesforce REST API.

Outbound messaging

With outbound messaging, you can configure Salesforce to automatically send messages (together with field values) to a designated external application endpoint, such as a Heroku app, whenever a specified set of fields change. Outbound messaging is part of the workflow rule functionality in Salesforce. Workflow rules watch for specific kinds of field changes, and trigger automatic Salesforce actions, such as sending email alerts, creating task records, or sending an outbound message.

With workflow, you declaratively define a rule and a callout to an external system. The rule can be connected to any Salesforce object.

When to use

This method of calling into Heroku from Salesforce does make debugging a little more difficult, and tightly couples an endpoint on Heroku with Apex code in production. For more scalable and resilient integrations, we recommend using Salesforce Platform Events.

Limits & considerations

Pay attention to API limits, as many of the scenarios described here will impact a Salesforce limit (for example, Apex Triggers have CPU time limits, which will affect how often an integration can fire).

Security and Heroku/Salesforce integrations shows how to secure this integration.

Learn more

• See Invoking Callouts using Apex in the Apex Developer Guide.
• See Setting Up Outbound Messaging in the the SOAP API Developer Guide

Heroku External Objects and Salesforce Connect

Heroku External Objects is available as part of Heroku Connect. It provides an oData wrapper for a Heroku Postgres database that has been configured for use with Heroku Connect. This feature allows other web services to retrieve data from within the specified Heroku Postgres database using RESTful endpoints generated by the wrapper. Read/write support is available for tables only; writing to views is not currently supported.

Used in tandem with Salesforce Connect, the feature permits data in a Heroku Postgres database to be represented in a Salesforce deployment, where it can be viewed (including within Apex and Visualforce pages), searched, and related to other objects. It cannot be used in standard reports as the data is available by reference.

When to use

You want to contextually reference data residing in Heroku Postgres from a Salesforce org, without having to deal with the inefficiency and requisite latency of physically copying the data. This strategy is most useful when the data is read or written in small chunks, and when the data is fundamentally not appropriate to copy (for example, device logs into CRM).

Limits & considerations

Search and queries aren’t optimized, so for more complex use cases, you must manage your Postgres indexes for performance.

See OData Callout Limit Considerations and Heroku External Objects Rate Limits for details about limits and volume.

Learn more

Read Heroku External Objects with Salesforce Connect

MuleSoft

MuleSoft is an integration PaaS for creating complex, multi-system integrations and managing the full life cycle of APIs. MuleSoft abstracts away the complexity of backend systems and processes, front-ending them with scalable and governable APIs, which you can then invoke from within a Heroku app.

MuleSoft has:

• Pre-built connectors for rapid integration to hundreds of systems (including Salesforce, SAP, and on-premise databases)
• Integration templates and components for rapid workflow automation
• Full life cycle API management
• Integration analytics and governance tooling

It also lets you compose APIs, or produce APIs of your own, which can then be used from a Heroku application.

When to use

You’re building a Heroku application that needs to integrate with external systems, and you don’t want to build directly to the raw, underlying APIs themselves, or you want additional features such as a pre-built connector, life cycle management, or governance tooling.

If you’re building an integration with only Salesforce, we recommend using Heroku Connect (if you need only a data integration), or Salesforce Platform Events (if you need something more than that).

Limits & considerations

Be prepared to manage the MuleSoft platform. Note that MuleSoft integrations with Salesforce do count against API limits.

Learn more

• The MuleSoft Anypoint Platform documentation.
• A list of MuleSoft Connectors.
• The MuleSoft Salesforce Connector documentation.

Security and Heroku/Salesforce integrations

When using Heroku and Salesforce together, particularly in the Calling the Salesforce REST API, Salesforce Platform Events and Apex HTTP callouts scenarios, security posture may be improved with an exclusive trust relationship, preventing undesired traffic from the public internet.

In particular, if your Heroku application runs in a Private Space, you can:

• Ensure that the app is not available on the public internet, and only available from your Salesforce org (Salesforce → Heroku)
• Ensure that your Salesforce org has appropriate IP restrictions to prevent public access, and to prevent public OAuth endpoint access (Heroku → Salesforce)

See Establishing a Trusted Connection Between Private Spaces and Salesforce for more details.