How to use IBM 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 an 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").

  If you're using a free trial of Salesforce, it won't be API enabled; sign up to the Developer edition instead.

  By default, API access is only allowed on Enterprise, Developer, Unlimited, and Performance editions. 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 connection is finally closed by the user.

  To enable 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

Considerations for connected apps in Salesforce

When connected, IBM App Connect services, like "IBM App Connect Prod UK", 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 an App Connect service, avoid creating more than 5 accounts across all Salesforce applications in the App Connect catalog. The maximum 5 accounts might also be reduced by other Salesforce connected apps, such as user-agent flows. For more information about this consideration, see the Salesforce docs "Manage OAuth-Enabled Connected Apps Access to Your Data" at https://help.salesforce.com/articleView?id=remoteaccess_request_manage.htm. (If such revoked access affects IBM App Connect, when you try to use the associated Salesforce account in a flow you'll 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 on the profile name 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.
• If you want 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. You can ask your Salesforce administrator whether the “Organization” object is enabled in your Salesforce edition, and if necessary request that the object be enabled.
• App Connect performs optimized event handling for Salesforce. For Salesforce events, you can use the following subset of standard objects that are supported by Salesforce PushTopic queries: Account, Campaign, Case, Contact, Lead, Opportunity, and Task.
• When specifying 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 using the same Salesforce account. If more than 15 flows try to run using the same Salesforce account, you'll 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, there are several things you can do to recover; for example, wait 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 Catalog page of the App Connect Designer.

  For some applications, the events and actions in the catalog 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 org to deliver custom event notifications when something meaningful happens, you can add those platform events to your App Connect flows either as an event that consumes 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, we've appended the label (Platform event) 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, you'll need to use the Configure more events link to display additional Salesforce objects, and then locate and 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, in order to pull in data from the event notification. When the flow runs, the configured actions will be processed whenever a new event notification (that is, an instance of the platform event) is published in your Salesforce org.

  

  

• To add a platform event to a flow as an App Connect action, you'll need to use the Show More link to display additional Salesforce objects, and then locate and 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 will publish the event notification, and any Salesforce after insert trigger on that event will fire.

  

  

  

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 has enabled support for the replay ID with Salesforce platform events. This means that if for any reason you had to stop a flow that uses a platform event, any events that are received during the time the flow was stopped are not lost. 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 7. If a replay ID is not provided, it defaults to -1. For more information, see Message Durability on the Salesforce Developers page.

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 when you need to catch up with missed events after a connection failure or for any reason that requires you to stop a flow, for instance, to re-authenticate your connection.

-1

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

Updating required fields

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

• If you are 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 creating an order, you must add that order to a contract or an account. So for the "Create order" action, in addition to the required fields (marked with *), you'll need to also complete the Contract ID or Account ID field. If missing, an error is generated to highlight such dependencies when you run the flow.

Specifying unique IDs

For some Salesforce actions, you'll need to 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 an 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 via a notification. If you have 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 has been modified. For instance, you might have used a Salesforce Update lead node as an event trigger in one of your flows to be notified whenever a lead is updated. If you have 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, such as who modified the object, when the object was modified, and what fields have been changed.

Flows by using Salesforce objects with Change Data Capture will keep you informed about incremental updates occurring in your App Connect integrations.

Permissions

You must have the required permissions set up in Salesforce to use Change Data Capture objects in App Connect.

To update permissions in Salesforce, go to Setup > Users > Profiles > <profile name> > Edit. Scroll to the Standard Object Permissions section and find the object you want to update. Ensure that Basic Data Administration is set to View All. By default, Read is also selected. The following screen shot shows the permissions on a Leads object being updated for a support user profile.

If you do not have the correct permissions set up, you will see the following message in the error log.

Note: Standard Platform users do not have the required permissions to subscribe to the change events channels. For this reason, Change Data Capture cannot be supported for this user role.

Configuring objects for Change Data Capture in Salesforce

All custom objects and a subset of standard objects are supported for use of Change Data Capture in Salesforce. For the full list, see Change Event Object Support.

You need to select the objects for which you want to receive change notifications. To do this, in Salesforce, go to Setup, type Change Data Capture in the Quick Find box then select Change Data Capture. Select the entities that you want to receive change notifications for, then click Save.

For more information, see Select Objects for Change Notifications.

If the object has been removed from entities, you will see the following message in the error log.

How to use Change Data Capture objects in App Connect

When you have enabled Change Data Capture in Salesforce, you can add those Change Data Capture objects to your App Connect flows as an event that consumes an event notification from Salesforce. To help you easily identify Change Data Capture events in App Connect, we've appended the label (Change Data Capture) 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, you'll need to use the Configure more events link to display additional Salesforce objects, and then locate and 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, you can 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 within the Change Event Header captures 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 will also include any fields that belong to the object, for instance middle name, postcode etc, as demonstrated by field1 and field2 in the code example above. Standard fields, for example, created date and last modified date are always included. When the flow runs, the configured actions will be processed whenever a new change notification (that is, an instance of the Change Data Capture event) is published in your Salesforce org.

There is a limit of 20 flows using Change Data Capture events. If you exceed this limit, you will be asked to stop flows using Change Data Capture event nodes.

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.

Accounts

New account

Updated account

Campaigns

New campaign

Updated campaign

Cases

New case

Updated case

Contacts

New contact

Updated contact

Leads

New lead

Updated lead

Opportunities

New opportunity

Updated opportunity

Show configurable events... Events shown by default are pre-configured using optimized connectivity. More items are available when you have configured more events that can trigger a flow by polling Salesforce for new or updated objects. For more information about configurable events, see Configuring polled events to trigger flows.

Salesforce actions

Your flow completes these actions on this application.

Accounts

Create account

Retrieve accounts

Delete account

Update account

Update or create account

Attachments

Retrieve contents of attachment

Campaigns

Create campaign

Retrieve campaigns

Delete campaign

Update campaign

Update or create campaign

Cases

Create case

Retrieve cases

Delete case

Update case

Update or create case

Contacts

Create contact

Retrieve contacts

Delete contact

Update contact

Update or create contact

Content documents

Retrieve contents of content document

Custom SOQL

Execute custom SOQL

Restriction: The maximum allowed limit for a single batch is 2000 records. You get a catalog error if the limit exceeds 2000.

Tip: The Execute custom SOQL action allows you to fetch the data from an organization database for the respective objects specified in the query. For more information about SOQL, see Introduction to SOQL and SOSL on the Salesforce documentation page.

The following are examples of some scenarios and their SOQL queries:

Scenario	SOQL queries
To get the records for the selected fields from the Leads object with the title 'CFO' or City 'Tallahassee'	SELECT Id, Name, title FROM Lead WHERE Title='CFO' OR City='Tallahassee'
To get the records for the selected fields from the Leads object	SELECT Id, Name, title FROM Lead OFFSET 0
To get the 20 records for the selected fields (but not the first 5 records, that is, from the 6th through 20th records) from the Leads object	SELECT Id, Name, title FROM Lead LIMIT 15 OFFSET 5
To get the records for selected fields from the Opportunities object with the Amount field value greater than or equal to 100000	SELECT Id, Name, Amount FROM Opportunity WHERE Amount >= 100000
To get the records for selected fields from the Opportunities object with the Name field in ascending order	SELECT Name, Amount, Type FROM Opportunity ORDER BY Name ASC
To get the records for selected fields from the Accounts and Contacts objects	SELECT Name, Phone, Industry, (SELECT Name FROM Contacts) FROM Account
To get the sum of amount from Opportunities object for a calendar year	SELECT CALENDAR_YEAR(CreatedDate) CreatedDate, SUM(Amount) Amount FROM Opportunity GROUP BY CALENDAR_YEAR(CreatedDate)
To get the selected fields from the Accounts object for specified industry values only	SELECT Name, Type, Phone, Industry FROM Account WHERE Industry IN ('Energy','Consulting','Hospitality')
To get the selected fields from the Contacts object for the names that start with the letter 'A' and the Rating as 'Hot' with reference to the Accounts object (Child to Parent relationship query)	SELECT Id, Name, Phone, Email, Account.Name, Account.Rating, Account.Industry FROM Contact WHERE Account.Rating='Hot' AND Name LIKE 'A%'

Events

Create event

Retrieve events

Delete event

Update or create event

File shares

Retrieve file shares

Share file

Files

Create file

Retrieve files metadata

Update file metadata

Delete file

Download file content

Delete files

Upload new file version

Folders

Create folder

Retrieve folders

Delete folder

Update folder

Update or create folder

Leads

Create lead

Retrieve leads

Delete lead

Update lead

Update or create lead

Opportunities

Create opportunity

Retrieve opportunities

Delete opportunity

Update opportunity

Update or create opportunity

Orders

Create order

Retrieve orders

Delete order

Update order

Update or create order

Products

Create product

Retrieve products

Solutions

Create solution

Retrieve solutions

More items are available when you have connected App Connect to Salesforce.