How to use App Connect with Salesforce

Supported product and API versions

To find out which product and API versions this connector supports, see Detailed System Requirements on the IBM Support page.

Supported editions

• If you don't have a Salesforce account, you can create a Developer account to try Salesforce for free.
  Important: If you want to create a free Salesforce account to test with App Connect, make sure that you create a Developer account rather than a Trial account. If you connect to App Connect with a Trial account, the Salesforce events do not work.
• Your edition of Salesforce needs to be enabled for API access (API enabled).

  A free trial of Salesforce isn't API enabled. Therefore, sign up to the Developer edition instead.

  By default, API access is only allowed on Enterprise, Developer, Unlimited, and Performance editions. The professional edition does not come with free API access, and you might need to pay to enable the API access or upgrade to a higher edition.

  Ask your Salesforce administrator if your edition of Salesforce is API enabled, and if necessary request API enablement or upgrade to a higher edition that has API access.

• To make sure that all the Salesforce events work properly, make sure that the streaming API access is enabled for your organization.

  Streaming APIs maintain a constant connection that transmits updated data to the user until the connection ends. When a user wants to take in a steady stream of rapidly changing live data, streaming APIs are ideal. The server repeatedly sends responses back with updated information until the user closes the connection.

  To enable a streaming API for your organization, complete the following steps.

  1. Log in to your Salesforce account.
     Note: You can choose to update these settings in lightning mode or classic mode.
  2. Click Setup (classic) or click the gear icon, then click Setup (lightning).
  3. Search for User Interface in the Quick Find box, then select User Interface.
  4. On the User Interface page, under the Setup section, make sure that the Enable Streaming API checkbox is checked.

     If not, click the checkbox and then click Save.

Connecting to Salesforce

To connect App Connect to a Salesforce account, see Connecting to Salesforce from App Connect.

Configuring Mutual TLS (mTLS) authentication

For enhanced security when you connect to Salesforce, you can configure mutual TLS authentication. Mutual TLS provides an extra layer of security by requiring both the client and server to authenticate each other by using digital certificates.

Mutual TLS authentication is supported for the following authentication types in App Connect:

• OAuth 2.0 Password
• Basic OAuth
• Basic JWT

You can request mutual TLS for your organization by raising a request to Salesforce Support with basic information.

To use mutual TLS authentication, you must first upload your certificate to Salesforce. For detailed instructions about uploading mutual authentication certificates, see Upload a Mutual Authentication Certificate in the Salesforce documentation.

When you configure your connection in App Connect, you can provide the following mTLS credentials:

mTLS certificate

The client certificate in PEM format that is used to authenticate your application to Salesforce. This certificate must match the certificate that you uploaded to Salesforce.

mTLS private key

The private key in PEM format that corresponds to your mTLS certificate. This key is used to establish the secure connection.

For more information about mutual TLS authentication in Salesforce, see Mutual Authentication Certificate Requirements and Salesforce Platform: Enable Mutual Authentication for Enhanced Security on the Salesforce documentation page.

Considerations for connected apps in Salesforce

When connected, IBM® App Connect services are listed on the Salesforce Connected Apps OAuth Usage page:

Salesforce has a limit of 5 connected apps per user for your organization. After a fifth approval is made for a connected app, the oldest approval is revoked. In instances of App Connect, avoid creating more than 5 accounts across all Salesforce applications in the App Connect Connect > Applications and APIs page (previously the Catalog page). Other Salesforce connected applications, such as user-agent flows, can also reduce the maximum 5 accounts. For more information about this consideration, see Manage OAuth-Enabled Connected Apps Access to Your Data in the Salesforce documentation. (If such revoked access affects App Connect, when you try to use the associated Salesforce account in a flow you see a message like We can't connect to Salesforce with the account details that you provided..)

General considerations for using Salesforce in App Connect

• To avoid the 401 Unauthorized Access error due to discovery call failure, make sure that you set the Session Security Level at login value to 'None' instead of 'High Assurance'.
  To set the session security level to 'None', complete the following steps:

  1. Log in to your Salesforce account.
     Note: You can choose to update these settings in lightning mode or classic mode.
  2. Click Setup (classic), or click the gear icon, then click Setup (lightning).
  3. On the Administer section (classic) or Administration section (lightning), expand Manage users (classic) or Users (lightning), then click Users.
  4. On the All Users page, click the profile name that is associated with your account.
  5. On the profile page, click Edit.
  6. Under Session Settings, set the Session Security Level Required at Login value to None.
  7. Click Save.
     Note: You might be asked to verify your identity by using an authentication method.
• To connect to Salesforce sandboxes or subdomains, and use Salesforce as a source application to trigger events, the Salesforce Organization object must be enabled in your Salesforce environment. Ask your Salesforce administrator to enable the object.
• App Connect provides optimized event handling for Salesforce. For Salesforce events, you can use the following subset of standard objects that Salesforce PushTopic queries support: Account, Campaign, Case, Contact, Lead, Opportunity, and Task.
• When you specify dates, use the ISO standard format YYYY-MM-DD. For example, specify 19 September 2017 as 2017-09-19.
• A maximum of 15 flows can run concurrently with the same Salesforce account. If more than 15 flows try to run with the same Salesforce account, you see the error You've exceeded your organization's concurrent user limit for your Salesforce account. If you encounter a concurrent user limit error for Salesforce, wait for a few minutes then try again to trigger the event-driven flow or to call the API operation.
• (General consideration) You can see lists of the trigger events and actions that are available on the Applications and APIs page of the App Connect Designer.

  For some applications, the events and actions depend on the environment and whether the connector supports configurable events and dynamic discovery of actions. If the application supports configurable events, you see a Show more configurable events link under the events list. If the application supports dynamic discovery of actions, you see a Show more link under the actions list.

• (General consideration) If you are using multiple accounts for an application, the set of fields that is displayed when you select an action for that application can vary for different accounts. In the flow editor, some applications always provide a curated set of static fields for an action. Other applications use dynamic discovery to retrieve the set of fields that are configured on the instance that you are connected to. For example, if you have two accounts for two instances of an application, the first account might use settings that are ready for immediate use. However, the second account might be configured with extra custom fields.

Platform events

If platform events are defined in your Salesforce organization to deliver custom event notifications when something meaningful happens, you can add those platform events to your App Connect flows. You can add a platform event either as an event that uses an event notification (or event message) from Salesforce, or an action that publishes an event notification. To help you easily identify platform events in App Connect, the label (Platform event) is appended to each platform event in the Salesforce list of events and actions.

• To add a platform event as an App Connect event that triggers a flow, use the Configure more events link to display more Salesforce objects. Then select the platform event that you want to add to the flow.
  Tip: To quickly search for a platform event in the list of events or actions that are discovered, you can type (plat in the search field, as a filter.

  You can optionally map to the platform event fields in subsequent nodes in the flow to pull in data from the event notification. When the flow runs, the configured actions are processed whenever a new event notification (that is, an instance of the platform event) is published in your Salesforce organization.

  

  

• To add a platform event to a flow as an App Connect action, use the Show More link to display more Salesforce objects, then select the platform event for which you want to create (or publish) an event notification. In the resulting Create node, you can then complete the custom fields that were configured in the Salesforce platform event definition. When the flow runs, App Connect publishes the event notification, and any Salesforce after insert trigger on that event runs.

  

  

  

Updating required fields

When you use Salesforce as a target application, make sure that you identify the required fields for the record that you're creating and assign values to these fields.

• If you're creating a lead, you must provide values for the Last Name and Company fields.
• If you are creating an account, you must provide a value for the Account Name field.

Some Salesforce actions also have specific dependencies. For example, when you create an order, you must add that order to a contract or an account. Therefore, for the Create order action, in addition to the required fields (marked with an asterisk *), you must also complete the Contract ID or Account ID field. If this ID is missing, an error is generated to highlight such dependencies when you run the flow.

Specifying unique IDs

For some Salesforce actions, you must specify unique ID numbers. For example, for the Create order action, a Contract ID or Account ID value is needed. You can either enter a hardcoded value or map to a value from a previous node in the flow.

If needed, you can obtain a hardcoded ID from the URL of the relevant Salesforce record. In the following example, you can see that the contract number 00000101 has a Contract ID value of 8000Y000000lfvG. (And you can obtain the Account ID in a similar way from an open account record.)

Change Data Capture

The Change Data Capture feature in Salesforce notifies you when any changes occur in the objects that you are interested in. Specific information about state changes is captured and provided in a notification. If you enabled Change Data Capture on objects in Salesforce, you can access those objects in App Connect so that you can capture all the times an object was modified. For instance, you might use a Salesforce Update lead node as an event trigger in one of your flows to be notified whenever a lead is updated. If you enabled Change Data Capture on the Leads object in Salesforce, you can now be notified whenever a change is made to a lead with information that wasn’t available before. This information might include who modified the object, when the object was modified, and what fields were changed.

Flows that use Salesforce objects with Change Data Capture keep you informed about incremental updates that occur in your App Connect integrations.

We can't retrieve the Change Data Capture events for the Salesforce Contact object because 
your Salesforce account doesn't have the required permission on the object to subscribe to subscribe
to Change Data Capture. 
Ensure that your Salesforce account has the required permission to subscribe to Change Data Capture.

We can't retrieve the Change Data Capture events for the Salesforce Contact object because
the object isn't configured for Change Data Capture.
Ensure that you selected a valid Salesforce object and the object is configured for Change Data Capture.

After you enable Change Data Capture in Salesforce, you can add a Change Data Capture object to your App Connect flows as an event that uses an event notification from Salesforce. To help you easily identify Change Data Capture events in App Connect, the label (Change Data Capture) is appended to each Change Data Capture event in the Salesforce list of events.

To add a Change Data Capture object as an App Connect event that triggers a flow, use the Configure more events link to display more Salesforce objects. Then select the Change Data Capture event that you want to add to the flow.

Note: To quickly search for a Change Data Capture event in the list of events that are discovered, type Change Data Capture in the search field as a filter.

The following code example displays the message structure of the fields that are available for you to map to. The fields in the Change Event header capture the additional information that you now have access to with Change Data Capture objects.

  {
    "schema": "<schema_ID>",
    "ChangeEventHeader": {
         "entityName" : "...",
         "recordIds" : "...",
         "changeType" : "...",
         "changedFields": [...],
         "changeOrigin" : "...",
         "transactionKey" : "...",
         "sequenceNumber" : "...",
         "commitTimestamp" : "...",
         "commitUser" : "...",
         "commitNumber" : "..."
      },
     "field1":"...",
     "field2":"...",
     . . .
    "event": {
      "replayId": <replayID>
    }
  },
  

You can optionally map to any of these Change Data Capture event fields in subsequent nodes in the flow to pull in data from the change notification. The mapping also includes any fields that belong to the object (such as middle name or postcode), as demonstrated by field1 and field2 in the code example. Standard fields, for example, created date and last modified date are always included. When the flow runs, the configured actions are processed whenever a new change notification (that is, an instance of the Change Data Capture event) is published in your Salesforce organization.

Post connection considerations

Replay ID

Salesforce provides queues for recording platform events and each event notification has a unique replay ID. Salesforce retains platform events for 72 hours and a user can store a replay ID value to use on resubscription to retrieve events in the retention window. App Connect supports the replay ID with Salesforce platform events. Therefore, if you stop a flow that uses a platform event, you don't lose any events that are received while the flow was stopped. To use this feature, add a platform event to a flow as an App Connect action and enter one of the following options in the Replay ID field as displayed in Figure 9. If a replay ID is not provided, the field defaults to -1. For more information, see Message Durability in the Salesforce Developers documentation.

Replay ID

Enter the replay ID to receive all the retained events after the ID of the event notification specified in this field. This option is useful to catch up with missed events after a connection failure or whenever you need to stop a flow (for instance to reauthenticate your connection).

-1

Enter -1 to receive new event notifications after the flow is triggered.

-2

Enter -2 to receive all events, including past events that are within the retention window and new events after the flow is triggered.

Events and actions

Salesforce events

These events are for changes in this application that trigger a flow to start completing the actions in the flow.

Events that are shown by default are preconfigured by using optimized connectivity. To see more events, click Show configurable events to poll Salesforce for new or updated objects.

Your flow completes these actions on this application.

More items are available after you connect App Connect to Salesforce.