Salesforce Listeners

To create a listener for a project, you need to have an admin, developer, or a custom role that includes write and execute permissions for that project. Without these required permissions, you would not be able to create listeners. For more information about role and permissions, see Roles.

1. Go to the project in which you want to create a listener.
2. Click Events > Listeners.

3. Click New Listener. The Add Listener screen appears.

4. Enter the following details in the Add Listener screen:

   • Type of listener - Select the name of the connector from the drop-down list for which you want to create a listener.
   • Select version - Select the connector version for which you want to create a listener.
5. Enter the following details in the Add Listener configuration screen:
   • Name - Provide a display name for the listener. It can contain alphanumeric characters, underscores (_) and hyphens (-).
   • Description - Provide a description for the listener.
   • Streaming API endpoint URL - Specify the endpoint of the streaming provider. For configuring a Salesforce streaming endpoint, specify the URL in the following format: https://<Salesforce_Instance>/cometd/<Salesforce API version>, for example, https://ap5.salesforce.com/cometd/44.0.
   • Select replay option - The IBM webMethods Integration listener for Salesforce can subscribe and listen to Salesforce events. This allows the IBM webMethods Integration listener to establish a persistent connection with Salesforce. This connection remains open while transmitting the events until either side closes the connection. Through this established connection, events are streamed to the listener. If the connection is lost due to a network failure or any other reason, you can retrieve the standard-volume events that are within the 24-hour retention window in Salesforce. You can retrieve Salesforce events only if you are using Salesforce v37.0 or later versions.

     Each Salesforce event is assigned a unique opaque ID for each event. This ID is contained in the *replayId* field of the event object. The *replayId* field value, which is populated by Salesforce when the event is delivered to subscribers, refers to the position of the event in the event stream. For consecutive events, the replayId values may not be sequential. For example, an event with ID 110 may follow an event with ID 101.

     To replay events, Salesforce provides a way to configure the replayId while subscribing to a particular channel. You can replay the events by specifying the replay option, and use it during resubscription to retrieve events that are within the retention window.

     • Last Received - Receive all events that occurred after the most recently saved replay ID. The IBM webMethods Integration server by default saves the replay ID of your most recently received event. When you select this option, you will receive all events that occured after the most recently saved replay ID each time the listener re-connects.
     • New - Receive new events that are broadcast after the client subscribes and replay only the new events from the time the listener is enabled.
     • All - Receive all events including past events that are within the retention window and the new events. Due to the possibility of exceeding daily streaming consumption limits, IBM does not recommend using this option.
   • Select Account - Select an account to connect to the application. The streaming functionality will leverage the existing authentication, timeouts, truststore, keystore, and host name verification configurations from the referenced account selected in the Select Account drop-down list field.
   • Select subscription - Select a channel from the list of available subscription channels you want the listener to connect.
     Currently, we are supporting the following subscription events:

     • Salesforce Push Topic Event - Select this subscription event if you want to receive notifications for changes to Salesforce data that match a SOQL query you define.
     • Salesforce Platform Event - Select this subscription event if you want to receive notifications about event messages published by publishers in real time.
     • Salesforce Change Data Capture Event - Select this subscription event if you want to receive notifications about changes pertaining to CRUD operations on Salesforce records.
     • Salesforce Generic Event - Select this subscription event if you want to receive notifications about events that are external to Salesforce.

     Note: For more information about these events, see Salesforce documentation.
6. Click Next. You will be redirected to the Parameters and Headers screen.
7. Review and configure the Parameters.
   • Review the pre-configured parameters such as name and description, the data type used to represent the kind of information the parameter can hold, and the parameterization type for the subscription request, for the selected subscription.
   • Provide a value for the Default value parameter.

     The supported default value formats for each Salesforce subscription event is listed in the following table:

     Salesforce Event	Supported Default Value Format(s)
     Push Topic Event	PushTopic name
     Platform Event	API name
     Change Data Capture Event	The following formats are supported: ChangeEvent name ObjectNameChangeEvent CustomObjectName_ChangeEvent
     Generic Event	GenericStreamingChannel name

8. Click Add Header to add necessary headers and provide the following details:
   • Header name - Provide a valid header name.
   • Header value - Provide a default value for the header.
   • Status - Toggle on the status switch to Active to include the header as a part of the subscription request.
   • Actions - Click Delete to delete the header.

9. Click Next and specify the following details in the Event screen:

   • Select Flow service name - Select the Flow service you want to run when the subscribed event occurs.
   • Select a user to run Flow service - Select a project user you want to use to run the selected Flow service. If the selected user does not have necessary permissions to run the specified Flow service, the Flow service execution will not complete when the subscribed event occurs.
   • Select ErrorCallBackFlowService name - Select any existing Flow service that you want to invoke when an error occurs (that cannot be automatically recovered by the listener and requires manual intervention). Flow services that are created with Error Callback Service Spec specification are only listed in the list.
   Note:

   • You can also create a new Flow service by clicking the Add button and providing the name.

   • By default, the Error Callback Service Spec specification is selected for the Flow services created from this page. In case, while configuring the Flow service, if you have cleared the Error Callback Service Spec option, then the Flow service is not listed in the Select ErrorCallBackFlowService name field. >

10. Click Save. The Summary tab appears.

11. Review the listener summary.

    Note: You can click the Flow service name to view and configure the details about the Flow service. From this method, the Error Callback Service Spec option is selected and the Specification reference field is in disabled state.
12. Click Save. The listener is created and is in disabled state. To enable the listener, follow the instructions mentioned in Enabling Listeners.
    Note:

    • Listeners created in one tenant cannot be published to another tenant.
    • The Salesforce listener receives events in the same order in which Salesforce sends them. As the Salesforce listener processes the messages asynchronously, there is no guarantee of the order of event processing.

Listeners may encounter errors while listening to events due to reasons such as incorrect account configurations, exceeding transaction limits, or errors on the Salesforce system. When an error occurs, listeners are suspended abruptly. Following are some disadvantages of not using error management:

• You do not get any alerts about the errors.

• The events occurred during the listener downtime are not captured and cannot be retrieved.

• There is a loss of information, and you must manually verify the logs and track the errors which is a time-consuming activity.

For Salesforce listeners you can manage errors by configuring an Error Callback Service Spec specification flow service that defines the actions that the listener must perform when a non-recoverable error occurs and the listener is suspended. Few examples are submitting a ticket to the Ticketing System or sending an SMS to the operations team. These alerts allow you to be aware of issues and rectify them as soon as possible with very minimal loss of information.

You can configure the flow service using the Select ErrorCallBackFlowService name option in the Add listener wizard. The behavior of the listener is as follows when you configure the error management option:

1. The listener is enabled and listening to events from Salesforce. When an error occurs:
2. Listener retries the action up to 5 times by default. If the listener:
   • Succeeds - The listener continues to listen to the events.
   • Fails - The configured callback Flow service is invoked, and the runtime status of the listener is changed to suspended state. The error information is sent to the callbackService and the details can be viewed in the Status column of the Listeners page.

   For example, you can configure the callback Flow service to show the log messages for the events that have been retried and failed. A sample message is as follows:

   

3. Enable the suspended listeners after rectifying the errors manually. Or, the listener is automatically enabled after a package reload.

   Note:

   • For some errors, enabling the listener alone does not work. The listener and the underlying account must be disabled followed by re-enablement of the listener with re-enablement of the underlying account too. For more information on errors, see Handling Errors.
   • For non-recoverable errors, the listener is in a suspended state after a package reload. For example, if an organization limit exceeds on number of events.

The events occurred during the listener downtime are based on the Select replay option provided during listener configuration. By default, Select replay option is set to Last Received. For more information on available replay options, see step 3 in the Creating Listeners section.

The execution details for the callback Flow services configured for listeners can be viewed from the Monitor page and are listed under the Streaming source.