Planning your Salesforce product integration: a guide for developers

If you’re building a Salesforce product integration for the first time, it can be frustrating to figure out where to start. Salesforce is a vast ecosystem of tools, concepts, and APIs to ramp up on, and their documentation doesn’t make it easy! To say there’s a ton of information is an understatement, and it can be tricky to make sense of it all.

As developers who spend our days (and nights!) thinking and breathing Salesforce integrations, we wanted to share this flow diagram to help you navigate the maze. It’s meant to be a high-level guide that highlights the important stuff and simplifies unnecessary detail. Our goal is to help you make practical decisions for your Salesforce integration use case.

Fetching Salesforce data from an external app

The first (and in our opinion, most important) decision point is whether your app will fetch data from your customers’ Salesforce accounts.

Examples of fetching data from an external app include:

• Syncing standard objects to your application database
• Creating new records or updating existing records in your customers’ Salesforce instance from your application
• Adding custom fields or custom objects that are specific to your application
• Fetching Salesforce metadata like schema information

If the answer is yes, you’ll want to authenticate your application through a Salesforce Connected App. A connected app is a framework that allows external applications to integrate with Salesforce using APIs and standard protocols (e.g. OAuth).

Most Salesforce integration use cases require a Connected App, but it’s worth highlighting a few examples that don’t:

• Apex code that triggers when records are updated in Salesforce. These run directly on the Salesforce platform and don’t require a Connected App for authentication.
• Setting up a Flow that posts data to a webhook that you host. Again this doesn’t require a Connected App, since code that runs directly on your customers’ Salesforce account already has access to the data.

Embedding custom UI in Salesforce

Another decision point is whether you need to embed UI elements within your customers’ Salesforce account. This is most common in products where the end users are sales reps who live inside Salesforce. Embedded UIs let you meet end users where they live and reduce friction to product adoption.

There are 2 high-level ways to embed UI components inside your customers’ Salesforce accounts:

1. Build your UI on Salesforce’s platform using a framework like VisualForce or Lightning.
2. Host your UI externally and embed it via a Canvas app.

If you go the VisualForce or Lightning route, your UI is hosted on Salesforce directly. Because these components run natively within Salesforce, you don’t need separate authentication. Salesforce also provides a suite of no-code tools for building the interfaces, so non-developers can customize the look-and-feel of the components. Your development happens in Salesforce.

Alternatively, Canvas is a set of tools and Javascript APIs that lets you embed UI that you host inside of your customers’ Salesforce accounts. Because canvas UI is hosted by you and embedded as an iFrame, canvas apps are technically connected apps that need to authenticate with your customers’ Salesforce.

In both options, you’ll need to package your app so it can be distributed to your customers’ Salesforce accounts with the proper permissions, components, and/or configurations. This is different than a pure data integration (e.g. via a standalone connected app) with an external application.

Packaging comes with tradeoffs. On one hand, it makes it easy for Salesforce admins to install and configure your application. On the other hand, it creates overhead since developers need to manage package versions and upgrades for all their customers.

Listing on AppExchange

Some companies building deeper Salesforce integrations will consider listing their application on AppExchange, Salesforce’s app store. Like many other app stores, there are pros and cons to this as well.

On one hand, you get increased distribution and access to the Salesforce partner ecosystem, which may also come with enhanced credibility. At the same time, there are fees and a security review that can takes 3-4 weeks or longer. Importantly, one of the requirements for listing on AppExchange is having a managed package, which itself is a significant ongoing investment.

In our experience, the vast majority of AppExchange listings take advantage of embedded UI components inside of their integrations and therefore are already investing in managed packages for their Salesforce integrations.

Which APIs to use?

Salesforce literally has several dozen APIs, and it can be overwhelming to figure out which ones to use. While every use case is different, here are the most common ones:

• REST API: The REST API lets you read and write standard and custom objects. It returns data in JSON and XML format and is the right choice for many common operations.
• Bulk API 2.0: The Bulk API 2.0 (and its predecessor Bulk API) is an asynchronous API that lets you query, load, and delete large sets of data. If you need to sync large amounts of records or make a copy of your customers’ CRM, the Bulk API 2.0 is the way to go. The Bulk API 2.0 returns data in CSV format.
• PubSub API: This is a real-time API (sometimes called a Platform Events or CDC API) that lets you publish and subscribe to business events related to record changes in Salesforce. It's ideal for scenarios where you need to listen to Salesforce record changes in external systems in real-time. The PubSub API is a gRPC API and is the successor to the Streaming API.
• Metadata API: The Metadata API gives you fine-grain control over permissions, schemas, and other metadata inside your customers’ Salesforce accounts. However, it is a SOAP API, which is not the most accessible. Unfortunately, it is the only choice for certain operations like fetching all the field names for a particular object type.

Depending on your integration use cases, you might use one or more of these APIs together. Keep in mind there are different API rate limits and other API-specific limitations (for example, some standard objects cannot be queried via the Bulk API 2.0), so be sure to do more testing and investigation for your use case.

Conclusion

At Supaglue, we work with startups building sales enablement, revenue intelligence, and workflow automation tools. In our experience, the most common Salesforce integration pattern is a connected app that integrates data with an external application:

• The integration is installed and distributed via an OAuth flow, and any customer configuration settings (e.g. field mappings) are managed inside the external application.
• All the business logic is centralized and there’s no security review or upgrade process for customers as the integration evolves.
• There is typically no embedded UI to start, to avoid the complexity and overhead of managed packages when a pure data integration often meets product requirements.

If you found this guide useful or have questions/feedback, please let us know! And if you have a Salesforce integration use case, check out our docs or join our Slack.