Salesforce

• CRM
• Account Engagement (formerly Pardot)

​

What’s supported

​

Supported actions

• Proxy Actions, using the base URL https://{{.workspace}}.my.salesforce.com.
• Read Actions, including full historic backfill and incremental read.
• Subscribe Actions.
• Write Actions, including Bulk Write and Delete.

• Proxy Actions, using the base URL https://{{.workspace}}.my.salesforce.com.
• Read Actions, including full historic backfill and incremental read.
• Write Actions.

​

Supported CRM objects

• Standard fields
• Custom fields

​

Supported Account Engagement objects

​

Example integration

• Salesforce CRM example
• Salesforce Account Engagement example

​

Before you get started

​

Salesforce orgs needed

1. Dev Hub Org: A Salesforce org with Dev Hub enabled. You will create the External Client App inside this org.
2. Namespace Org: A Developer Edition Salesforce org that is only used to register a namespace. You will link this namespace to the Dev Hub Org.

​

1. Enable Dev Hub

• You can sign up for a trial Salesforce Partner Business Org, which is essentially a trial of a regular Salesforce org (typically 12 months long). Once you become an official partner, Salesforce will grant you two free Sales Cloud licenses. You can request an extension of the trial or purchase more licenses.
• Alternatively, if you are already a Salesforce customer, then you can use your existing Salesforce org, and Salesforce will add these free licenses to your existing org when you are accepted as a partner. Please see Salesforce documentation for more information.

• You can sign up for a free Developer Edition Salesforce org and use it as your Dev Hub Org. Please note that even though Developer Edition orgs are subject to deletion when there is inactivity, this does not apply if you have an External Client App in the org, so it is safe to use a free Developer Edition org as your Dev Hub Org.

1. Log in to your Salesforce org.
2. From Setup, enter Dev Hub in the Quick Find box and select Dev Hub.
3. Select Enable Dev Hub.
4. Select Enable Unlocked Packages and Second-Generation Managed Packages.

​

2. Register a namespace

1. Sign up for a free Developer Edition org.
2. Navigate to the gear icon in the top right corner and select Setup.
3. In the quick search box at the top, type in Package Manager in the Quick Find box and select Package Manager. In Namespace Settings, click Edit.
4. Enter a namespace and select Check Availability. We recommend picking a namespace that is your product name or a shortened version of your product name.
5. When prompted to select a package to associate with this namespace, select None, then click Review.
6. Review your selections and click Save.

​

3. Link namespace to Dev Hub Org

• Log in to the Dev Hub Org from Step 1.
• Open App Launcher (9 dots at the top left), and search for Namespace Registries.
• Click Link Namespace on the top right.
• When prompted to authenticate, log into the Namespace Org from Step 2. If you are having trouble with this step, try again in an incognito window.
• After linking, select All Namespace Registries filter to view the namespace.

​

4. Create External Client App

1. Log in to your Dev Hub Org that you created above.
2. Navigate to the gear icon in the top right corner and select Setup.
3. Search for External Client App Manager.
4. Click New External Client App.

• Enter a name for the External Client App. This should match your product name.
• Specify a contact email; this should be your support email address.
• Set Distribution State to “Packaged”.
• Enable OAuth settings.
• In callback URL put https://api.withampersand.com/callbacks/v1/oauth.
• Add the following OAuth scopes at the minimum:
  • Perform requests at any time (refresh_token, offline_access)
  • Manage user data via APIs (api)

✅ For more details on which OAuth scopes to include, refer to the OAuth Tokens and Scopes guide.

• Uncheck the box for Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows
• Check the box for Enable Authorization Code and Credentials Flow

5. Go to the Policies tab, expand “OAuth Policies”, and click the edit button. In the “App Authorization” box, make the following modifications:

• In “Refresh Token Policy”, select “Refresh token is valid until revoked”
• In “IP Relaxation”, select “Relax IP restrictions”

6. Go to the Settings tab, expand “OAuth Settings”. Click on “Consumer Key and Secret”.

​

5. Create Provider App in Ampersand

1. Log in to your Ampersand Dashboard.
2. Select the project where you want to create a Salesforce integration.
3. Select Provider apps.
4. Select Salesforce from the Provider list.
5. Enter the previously obtained Consumer Key in the Client ID field and the Consumer Secret in the Client Secret field.
   

​

6. Package the External Client App

1. Install the Salesforce CLI using npm or another supported method:

npm install -g @salesforce/cli

2. Create a Salesforce DX project. From a new directory, generate a project:

sf project generate --name MySalesforcePackage

3. Authenticate with your Dev Hub Org. From the project directory you just created, log in to your Dev Hub Org (the org where you created the External Client App):

sf org login web --set-default-dev-hub --alias DevHubOrg

4. Set the namespace in the project. Edit sfdx-project.json in the project root. Set the namespace value to the namespace you registered and linked to your Dev Hub earlier:

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true
    }
  ],
  "namespace": "MY_NAMESPACE",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "59.0"
}

5. Create the managed package. Use the command below and replace these flags with actual values that are applicable to you:

• name: replace with your product name
• error-notification-username: this must match the email address of one of the users in the Dev Hub Org. For example, you can use your own email here. This is the email address that will receive notifications from Salesforce about errors in the package.

sf package create \
  --name "My Package" \
  --package-type Managed \
  --path force-app \
  --target-dev-hub DevHubOrg \
  --error-notification-username your-notification-email@company.com

6. Pull External Client App metadata into the project. Run this command to programmatically fetch the settings that you had just configured for your External Client App:

sf project retrieve start --metadata ExternalClientApplication ExtlClntAppOauthSettings --target-org DevHubOrg

• force-app/main/default/extlClntAppOauthSettings/
• force-app/main/default/externalClientApps/

7. Build and promote a package version. Create a new package version (this can take several minutes). Replace My Package with the name you supplied in the name flag of the sf package create command above.

sf package version create \
  --package "My Package" \
  --installation-key-bypass \
  --wait 20 \
  --code-coverage

8. Promote that version so it can be installed by customers:

sf package version promote --package SUBSCRIBER_PACKAGE_VERSION_ID --no-prompt

9. Get the package install URL. Use the Subscriber Package Version ID to build the install URL for your package.

https://login.salesforce.com/packaging/installPackage.apexp?p0=SUBSCRIBER_PACKAGE_VERSION_ID

https://test.salesforce.com/packaging/installPackage.apexp?p0=SUBSCRIBER_PACKAGE_VERSION_ID

10. Ask your customers to install the package. Instruct your customers to go to the package install URL and click “Install for All Users”. They must complete this step before connecting their Salesforce account using Ampersand’s prebuilt UI components. Otherwise OAuth will fail.

​

Migrating Connected App to External Client App

1. Open Salesforce Setup and search for Manage Connected Apps and select the Connected App that you want to convert. Click Migrate To External Client Application.

2. Check both required checkboxes to confirm migration.

3. Click Migrate.

4. Click OK.

5. A confirmation message will appear.

6. Open External Client App Manager.

7. Select your app, go to the Settings tab and set “Distribution State” to Packaged.

8. Go to the Policies tab, expand “OAuth Policies”, and click the edit button. In the “App Authorization” box, make the following modifications:

• In “Refresh Token Policy”, select “Refresh token is valid until revoked”
• In “IP Relaxation”, select “Relax IP restrictions”

9. Enable Dev Hub on your Salesforce org that is hosting the Connected App (which is now an External Client App).
10. Create a new Developer Edition Salesforce org and register a namespace, then link the namespace to the Dev Hub Org.
11. Package the External Client App by following these instructions.

​

Using the connector

• Create a manifest file like the example.
• Deploy it using the amp CLI.
• If you are using Read Actions or Subscribe Actions, create a destination.
• Embed the InstallIntegration UI component.
• Start using the connector!
  • If your integration has Read Actions or Subscribe Actions, you’ll start getting webhook messages.
  • If your integration has Write Actions, you can start making API calls to our Write API.
  • If your integration has Proxy Actions, you can start making Proxy API calls.

​

Customer guide