Last updated March 05, 2025

Heroku AppLink (formerly Heroku Integration) is an add-on that exposes Heroku apps as API services in Salesforce. Heroku developers can build APIs on Heroku that Salesforce admins and developers can use to execute actions in flows, Apex, Data Cloud, and Agentforce. The add-on supports multiple user modes, and enforces Salesforce user permissions and rules when interacting with your data and using Heroku SDKs.

Heroku AppLink provides:

• Integration between Heroku, Salesforce, Data Cloud, and Agentforce: Have an easy and secure automated way of connecting and importing your apps to interact with Salesforce, Data Cloud, and Agentforce.
• Managed security: There are three interaction modes and the permissions defined in Salesforce are applied when performing operations using your Salesforce data.
• Flows and Apex-based invocation: Use Salesforce Flow and Apex to call your imported Heroku apps synchronously or asynchronously.
• SDK templates: Use our SDK templates to perform Data Manipulation Language (DML) operations on your Salesforce and Data Cloud orgs.

Use Cases

With Heroku AppLink, you can:

• Generate PDFs: Deploy a Puppeteer-based microserve on Heroku that generates PDFs from Salesforce. You can also maintain user context when querying Salesforce data.
• Perform bulk jobs: Perform data transformations by passing Salesforce data to Heroku’s compute services, such as adding complex calculations or making API calls to gather additional values. The results persist back to Salesforce or to Data Lake Objects (DLOs) in Data Cloud.
• Deploy custom Agentforce actions: Develop a custom action on Heroku written in the language of your choice for your Agentforce agent. Use your custom actions to interpret natural language requests from users and perform dynamic calculations on the data.

Setting Up Heroku AppLink

Heroku AppLink CLI Plugin

The Heroku AppLink CLI plugin allows you to set up and manage connections with the Heroku AppLink add-on. Before connecting your Heroku apps to your Salesforce orgs, you must install the plugin.

Heroku AppLink Project Templates

Project templates speed up development by using industry-standard frameworks to set up and define APIs to import. Project templates also generate sample code that uses the Salesforce SDK to call your APIs. See our Node.js Fastify template.

Heroku Integration Service Mesh Buildpack

The Heroku Buildpack for Heroku Integration Service Mesh installs the Heroku Integration Service Mesh to handle the authentication and authorization for your app. The service mesh is a proxy in front of your app that intercepts incoming requests for validation and capabilities. The buildpack:

• Starts your app.
• Verifies inbound requests to the app only from known clients. Only orgs connected with salesforce:connect can invoke the app.
• Provides scoped tokens for the app. Authorization tokens ensure that DMLs performed using the SDK adhere to the permissions defined in Salesforce. Developers can add defined permission sets to determine what data the app has access to.
• Provides a way for customers to check the current condition of the proxy and the app with the Health Check API.

Getting Started Guide

See our Getting Started with Heroku AppLink (Pilot) guide to provision the add-on and start using Heroku AppLink.

Connections on Your App

When you create a connection for the first time, Heroku establishes a trusted connection between the Heroku app and the Salesforce org. You must create a connection for every org that interacts with your app. This connection lets you import the app as an external service in Salesforce. You can connect multiple org environments to one app. With Heroku AppLink, you can connect to Salesforce and Data Cloud orgs in production, sandbox, and scratch org environments.

Connecting to a Salesforce org creates a default connection to the org that registers the app automatically as an external service. This connection is specific to the app and is a special user to connect two clouds in Salesforce. Creating a connection generates the metadata:

• A Heroku Integration permission set that grants the Heroku Integration add-on Metadata API deploy access to the org.
• A HerokuIntegrationAuthorization connected app used to generate access tokens for each app request. The target app’s API uses access tokens to access the org. A permission set created on app import defines org access.

When you connect to a Data Cloud org, Heroku creates a Data Cloud access token. Connections to Data Cloud are always in run-as-user mode.

integration:connections shows all the connections on the apps you own or are a collaborator on. If you’re an admin of a Heroku Team or Enterprise Team, you can see all the connections created on the apps on the team.

When you remove a connection, you can no longer import apps to that Salesforce org. If the connection has a user mode of run-as-user and you referenced this connection in your code, the code will fail when you remove the connection. Make sure no existing code references a connection before removing it.

Import Your App as an External Service

External Services lets you use declarative tools and OpenAPI specifications to connect your Salesforce org to an external API. When you import your Heroku app as an external service, you can invoke the app with Salesforce Flow, Apex, Data Cloud, and Agentforce. Only connected Salesforce orgs and Data Cloud orgs can invoke your imported apps.

Importing your app generates:

• A Heroku type external service that represents the imported APIs.
• Apex classes and methods for the external service that you can invoke in Apex and Salesforce Flow as custom actions. The Apex class is named ExternalService.<imported-app-name>. See Invoke Your Imported Apps for more information.
• A named credential and external credential to store the endpoint URL and to customize authentication for the Heroku external service callout. The named credential is named <imported-app-name>.
• A permission set to access to the external credential and allows users to invoke the external service. The permission set is named <imported-app-name>.
• (Optional) A HerokuAPIAuthorization session-based permission set that determines org access from your Heroku app.
• (Optional) A session-based permission set that’s automatically generated when the --generate-authorization-permission-set flag is set to true. The session-based permission set is named <imported-app-name>Authorization. You can modify this permission set to elevate the access for the users when running user-plus mode.

Invoke Your Imported Apps

After importing your app, you can invoke your external service in Salesforce with:

• Apex
• Salesforce Flow
• Data Action Targets
• Agentforce

Apex

Apex is a strongly typed, object-oriented programming language on the Salesforce platform. You can make synchronous and asynchronous invocations to the Apex classes and methods the external service generated when you imported your app. Invoking with Apex calls out to your Heroku app all from your Salesforce org.

Salesforce Flow

Salesforce Flow is a declarative tool for creating, managing, and running automations in your Salesforce org. You can add the external service action generated from importing your app to your flow. Using flows makes it easy to call your Heroku app without writing code.

Data Action Target

A Data Cloud data action enables different types of event-driven integrations and orchestrations in Salesforce and Data Cloud. You can create your Heroku app as a data action target to receive the data action in near real time.

Agentforce

Agentforce lets you build intelligent, customizable, and conversational AI agents in Salesforce for assisting employees and customers. You can import your app as a custom Agentforce action for your agent to perform specific tasks and perform dynamic calculations on your data.

Logging and Metrics

You can view logging and metrics with Heroku’s standard tail logs with the heroku logs command.

Security

Heroku AppLink authenticates and authorizes requests between your application and Salesforce with a service mesh. The service mesh is a proxy in front of your app that intercepts incoming requests for validation and capabilities.

User Modes

There are three user mode options that apply the permissions and roles defined in your Salesforce org when using our SDK: user, user-plus, and run-as-user. You can manage what Salesforce data your Heroku apps can access depending on the user mode.

User

user is the default user mode. In this mode, the context is sent as part of your request from Salesforce to Heroku. The SDK with this context uses the user permissions defined in Salesforce and applies the permissions when performing DML operations using the SDK.

User-Plus

In user-plus mode, the developer and admin can define an additional session-based permission set. The permission set is automatically created if you set the --generate-authorization-permission-set flag to true when importing your app.

For the pilot, when we create this permission set, we name it <imported-app-name>Authorization, for example HerokuAPIAuthorization. Don’t change this name, as we look up the permission set name at runtime during the pilot. Assign this permission set, along with the app’s standard permission set, to the users who need elevated permissions while the app is running. When the SDK is initialized, it combines the user’s Salesforce permissions with the permissions from this set, applying them to DML operations.

Run-As-User

In run-as-user mode, you can run as a specific user, such as an integration user. To use this mode, set the --store-as-run-as-user flag to true when connecting your Salesforce org. This mode allows the admin and developer to initialize the SDK with a specific user context. To store the user as a connection, use the --store-as-run-as-user flag when creating a connection.

Considerations and Limitations

Troubleshooting

You can run into these common errors:

This session is not valid for use with the REST API.

• The invoking user doesn’t have the permission to expose the HerokuIntegrationAuthorization connected app. To resolve the issue, assign the invoking user the Heroku Integration permission set.

024-09-26T22:41:00.809258+00:00 heroku[web.1]: State changed from crashed to starting
2024-09-26T22:41:05.003861+00:00 heroku[web.1]: Starting process with command `APP_PORT=3000 heroku-integration-service-mesh npm start`

• If git push heroku main fails with this error, run this command in your project directory: heroku buildpacks:add https://github.com/heroku/heroku-buildpack-heroku-integration-service-mesh

Support

Submit all Heroku AppLink support and runtime issues via one of the Heroku Support channels. To submit a ticket for the pilot, mention the pilot name Heroku AppLink in the ticket subject.