Salesforce trigger

The Salesforce trigger lets you listen to either Change Data Capture (CDC) or Enterprise Messaging Platform events. With this trigger, you can start your integration based on any of the CDC events (Create, Update, Delete, or Undelete) or the platform events in your Salesforce instance.

Before you begin

This section outlines the steps required to connect and configure a Salesforce instance to use Change Data Capture (CDC) or Platform events to stream changes to your Apigee Integration in a pub/sub manner. The following steps must be completed before configuring any Salesforce-related task or trigger in Apigee:

Set up an integration user

Set up an integration user with the following steps:

  1. Log in to your Salesforce instance with your sysadmin credentials.
  2. Click the Gear icon and then select Setup, as shown in the image below: image showing Setup pageimage showing Setup page
  3. Click Users > Users from the Administration menu.
  4. From the Users pane, select the New User button.
  5. In the User Edit dialog, fill in the following details:
    1. First Name: First name of the integration user.
    2. Last Name: Last name of the integration user.
    3. Email Address: Email for the integration user. Ideally, this should be a group email.
    4. Username: User name that complies with any org-level naming conventions.

      If you are creating a new integration user, use the following format: EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      If you have an existing integration user, confirm that the username is entered here.

    5. Role: Select from the dropdown of options.
    6. User License: Enter Salesforce or, if using a trial org, enter Salesforce Platform.
    7. Profile: Select the permissions profile for integration users from the dropdown.

      We recommend assigning a profile with no permissions, to protect your integration user Salesforce access from unauthorized usage.

    8. Click Save.
  6. To update the password for the new integration user, follow these steps:
    1. Click the Reset password(s) button on the Users pane. A password reset email is sent to the email address associated with the user.
    2. Follow the reset password flow from the email account. Take note of the new password, as you will need it for a later step.

Configure a Permission Set

If you have already have access to a Permission Set that is appropriate for an integration user, you can skip this step and proceed to Set up a security token. Otherwise, follow these steps to configure a Permission Set for the integration user and the Salesforce object.

To configure a Permission Set for the integration user:

  1. From the Setup menu, click Users > Permission Sets.
  2. In the Permission Sets pane, click the New button.
  3. In the Permission Sets dialog, enter the following details:
    • Label: Enter a name for the Permission Set.
    • License: Select Salesforce from the License dropdown.
    • Click Save.
  4. From the list of System setting options, scroll down and select System Permissions
  5. On the System Permissions page, click the Edit button.
  6. Scroll down the list of available permissions and select the API Enabled checkbox.

    The Api Only User permission is also required, but cannot be enabled until the required security token is reset. This permission is added in a later step.

  7. (Optional) Scroll and select Modify All Data and View All Data, if applicable. These permissions are not required, but can be helpful if you want to automatically give the integration user access to new objects. We recommend only enabling these permissions for testing in a sandbox.
  8. Scroll to the top of the permissions list and click Save.
  9. Confirm your settings and click Save.

To configure the Permission Set for the Salesforce object:

  1. Click Permission Set Overview to return to the main Permissions Set configuration page.
  2. Select Object Settings from the Apps section of the Permissions Set pane.
  3. Scroll down and select the Salesforce object(s) requiring a Permission Set. This example uses the Opportunity object.
  4. Click the Edit button on the object detail page.
  5. Select the checkboxes for record types If you know which record types are required select those. If you don't know which record types are required, select them all.
  6. Select the checkboxes for the Object Permissions to enable. Read and View All are recommended.
  7. Grant Read Access or Edit Access for each object field by selecting the corresponding checkbox.
  8. Scroll to the top of the page and click Save.

Set up a Security Token

If you have created a security token for the integration user previously, and reset the password, an email with a new security token is sent automatically. You can use the new token and skip to Create a connected app.

Otherwise, use the following steps to reset the security token for the integration user:

  1. Log in to Salesforce as the integration user, using the username and password set in a previous step.
  2. From the main menu, click the profile picture, then click Settings.
  3. From the Settings menu, select Reset My Security Token to open the Reset Security Token pane.
  4. Click the Reset Security Token button.
  5. Check the email account associated with the integration user for an email containing the new security token. Take note of the new security token, as you will need it for a later step.
  6. (Optional) Enable the Api User Only permission in System Permissions for your permission set, as described in Configure a permission set above.

Create a Connected App

System administration permission is required to set up a Connected App. If you are currently logged in as the integration users, make sure to log out and then log in again as sysadmin.

Follow these steps to set up a Connected App:

  1. Click the Gear icon and then select Setup.
  2. From the Setup menu, search for and select App Manager, as shown in the image below: image showing Setup pageimage showing Setup page
  3. Click New Connected App.
  4. In the configuration pane, provide the following details:
    • Connected App Name: Enter a name for your connected app.
    • API Name: Enter the name of the API.
    • Contact email: Enter an email for your connected app, ideally a group email alias.
    • API (Enable OAuth Settings): Select Enable OAuth Settings. Then, set the following:
      1. (Optional) Callback URL: This is only required if you want an external service to perform validation. If you do choose to provide a callback, make sure to include the http(s):// prefix.
      2. Selected OAuth Scopes: Select:
        • Access and manage your data (api)
        • Perform requests on your behalf at any time (refresh_token, offline_access)
  5. Click Save.
  6. Click Continue. You need to re-authorize with a verification code that is sent to your email address.
  7. After successfully verifying the code, a consumer secret and a consumer key are displayed on the next page. Make a note of these values, as they will be used when setting up the Auth Module for Apigee.
  8. Click the Manage button.
  9. Once on the Connected App Detail page, click the Edit Policies button.
  10. In the OAuth Policies section, change the value in the Permitted Users dropdown to Admin approved users are pre-authorized.
  11. Click Save.
  12. Scroll to the Profiles and Permission Sets section of the page to select the profile or Permission Set you want to apply to the connected app.
  13. Select the desired profile or Permission Set.
  14. Click Save.

Prerequisite steps to use CDC events

Before configuring your Apigee trigger to use CDC events, make sure to add a configured object to CDC in Salesforce:

  1. Log in to Salesforce as a sysadmin.
  2. Click the Gear icon, then click Setup.
  3. Using the left nav, search for and select Change Data Capture.
  4. On the Change Data Capture setup page, locate the Salesforce object you'd like to use in the Available Entities column and drag it to the Selected Entities column.
  5. Click Save.

Prerequisite steps to use Platform events

Before configuring your Apigee trigger to use Platform events, complete the following steps in Salesforce:

  • Create a Platform Event
  • Update permissions for the Platform Event

Create a Platform event

To create a Platform event, perform the following steps:

  1. Log in to your Salesforce instance with your sysadmin credentials.
  2. Click the Gear icon and then select Setup.
  3. In the navigation pane, search for Platform and then click Platform events.
  4. image showing a new platform eventimage showing a new platform event
  5. In the Platform events page, click New Platform Event and set the following properties:
  • Label
  • Plural Label
  • Object Name(This field is automatically populated)
  • Publish Behavior Select any one of the following values:
    • Publish After Commit: Reverts streaming of events if a condition isn't met.
    • Publish Immediately: Instantly triggers the event, without waiting for any validation.
    For more information about the publishing behavior, see Platform events and Transactions.
  • Deployment Status (Optional): Select Deployed if the event is ready for deployment.
  • Click Save.
  • image showing setting of labels and publish behavior for a platform eventimage showing setting of labels and publish behavior for a platform event
  • Create custom fields. To create the custom fields, click New in the Custom Fields and Relationships section and select the type of custom field. You can create as many custom fields as required.
  • After creating the custom fields, in the Platform events page, notice the value of the API Name field. The object name ends with _e, which means that the object is a Platform Event object. For a CDC object, the object name ends with _c.

    image showing details of a saved platform eventimage showing details of a saved platform event

    Update permissions for the Platform Event

    The permissions set must be updated to let the integration user access the newly created Platform Event.

    To update the permissions, perform the following steps:

    1. From the Setup menu, click Users > Permission Sets.
    2. In the Permission Sets page, click the previously created permission.
    3. Click Object Settings > Plural Label of the Platform Event.
    4. In the Object Permissions section, enable the Read and Create permissions.
    5. Click Save.
    6. image showing permissions of a platform eventimage showing permissions of a platform event

    Add a Salesforce trigger

    To add a Salesforce trigger to a new or existing integration, follow the steps below:
    1. In the Apigee UI, select your Apigee Organization.
    2. Click Develop > Integrations.
    3. Select an existing integration or create a new integration by clicking Create Integration.

      If you are creating a new integration:

      1. Enter a name and description in the Create Integration dialog.
      2. Select a Region for the integration from the list of supported regions.
      3. Click Create.

      This opens the integration in the integration designer.

    4. In the integration designer navigation bar, click +Add a task/trigger > Tasks to view the list of available tasks.
    5. Select an existing integration or click Create integration.
    6. In the integration editor, click + Add a task/trigger > Triggers to view the available triggers
    7. Click and place the Salesforce trigger element to the designer.

    Configure the Salesforce trigger

    To configure the Salesforce trigger, perform the following steps:

    1. Click Salesforce trigger in the integration editor to view the trigger configuration pane.
    2. Select a Salesforce instance from the Salesforce instance configuration drop-down.

      If you do not have a Salesforce instance, create a new instance. For more information, see Create a new Salesforce instance.

    3. Select a Salesforce channel from the Salesforce channel configuration drop-down.

      If you do not have a Salesforce channel, create a new channel. For more information, see Create a new Salesforce channel.

    4. If you have chosen the event type as CDC, select any one of the following operations:
      • Create
      • Update
      • Delete
      • Undelete

      The trigger runs only if the specific operation or gap operation occurs.

      The Salesforce trigger can be configured for only one operation. If you want to run the trigger for multiple operations, create a Salesforce trigger for each operation.

    Create a new Salesforce instance

    To configure a new Salesforce instance, perform the following steps:

    1. In the editable properties of the trigger, click Select a Salesforce instance configuration > + Add new Salesforce instance configuration.
    2. In the Add Salesforce instance configuration dialog, set the following properties:
      • Salesforce instance connection name: Enter a name for the instance.

        After configuration, you will use this name to refer to the Salesforce instance.

      • Salesforce domain: Enter a service authority for the instance. You can find the domain in your Salesforce account. For example, instance.my.salesforce.com. The following image shows the Salesforce domain:

        Get Salesforce domain in a Salesforce instance Get Salesforce domain in a Salesforce instance

      • Authentication profile: Select an authentication profile.

        If you don't have an authentication profile, create a new profile. For information, see Create a new authentication profile.

      • Salesforce Organization ID: Enter the org id of the salesforce instance. You can get the ID from your Salesforce administrator.
    3. Click Add.

    Create a new Salesforce channel

    To configure a new Salesforce channel, perform the following steps:

    1. In the editable properties of the trigger, click Select a Salesforce channel configuration > + Add new Salesforce channel configuration.
    2. In the Add Salesforce channel configuration dialog, enter the object name for the Salesforce object name property.

      If unsure of the object name, contact your Salesforce administrator.

    3. Click Add.

    Output variables

    The response from the Salesforce trigger is available to you in the output variables.

    The output variables for a CDC event are described in the following table:

    Variable Data type Description
    SalesforceTriggerCdcPayload JSON Details of the change event.
    SalesforceTriggerEvent JSON Contains replayId of the event.
    SalesforceTriggerSchema String Trigger schema.
    SalesforceTriggerCdcSnapshot JSON Snapshot of the object after the change event. This field is available only for Update and Create operations.
    SalesforceTriggerCdcRecordId String Contains the recordId of the updated or added record. The recordId is an identifier of the changed Salesforce object.

    The output variables for a Platform event are described in the following table:

    Variable Data type Description
    SalesforceTriggerPEPayload JSON Details of the change event.
    SalesforceTriggerEvent JSON Contains replayId of the event.
    SalesforceTriggerSchema String Trigger schema.
    The output parameter for this trigger is the CdcTriggerPayload JSON variable. The JSON variable contains updated record objects.

    Best practices

    Using the Salesforce trigger is recommended in cases where you want to use Salesforce notifications to trigger integrations without writing custom code to publish Salesforce events. Any small field change in your Salesforce case will trigger a Salesforce CDC event, and thus trigger an integration, which can result in significant integration noise. Consider using Change event filters to filter only the required CDC events that trigger the integration. Using Change event filters can help reduce integration noise and ensure compliance with your license limitations.

    Similarly, we recommend unpublishing any integration using this trigger when the integration is no longer needed. Until it is unpublished or deleted, the integration will continue to listen for Salesforce CDC and Platform events.

    Considerations

    Before using the Salesforce trigger to run your integration, consider the following:

    • Salesforce typically sends a maximum of 100k CDC and Platform events per day. Speak with your Salesforce administrator to understand your license restrictions before choosing CDC events for your integration trigger.
    • If you are planning bulk uploads to Salesforce, consider pausing CDC to reduce integration noise and ensure compliance with your license limitations.
    • The maximum event message size that Salesforce can publish is 1 MB. For more information, see Change Data Capture Allocations.
    • Apigee does not support Salesforce CDC events for the following minicluster regions:
      • asia-northeast1
      • asia-south1
      • australia-southeast1
      • europe-west2
      • europe-west3
      • europe-west6
      • northamerica-northeast1
      • southamerica-east1
      • us-east4
      • us-west2