Listeners
Learn about various listeners supported in IBM webMethods Integration.
Learn about various listeners supported in IBM webMethods Integration.
In IBM webMethods Integration, listeners are components that allow you to receive data from external sources, such as HTTP requests, emails, or message queues, and then invoke integration workflows based on that incoming data. For example, alert the sales representative to the return and send a confirmation email to the customer.
Listeners play a key role in building event-driven integrations that respond to data events, making it easier to automate business processes and workflows based on external inputs. The choice of listener depends on the specific requirements of your integration project and the data sources you need to connect to.
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.
Go to the project in which you want to create a listener.
Click Events > Listeners.
Click New Listener. The Add Listener screen appears.
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.
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://
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. Learn more about Salesforce Push Topic events.
Salesforce Platform Event: Select this subscription event if you want to receive notifications about event messages published by publishers in real time. Learn more about Salesforce Platform Events.
Salesforce Change Data Capture Event: Select this subscription event if you want to receive notifications about changes pertaining to CRUD operations on Salesforce records. Learn more about Salesforce Change Data Capture Events.
Salesforce Generic Event: Select this subscription event if you want to receive notifications about events that are external to Salesforce. Learn more about Salesforce Generic Events.
Click Next. You will be redirected to the Parameters and Headers screen.
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:
|
Generic Event | GenericStreamingChannel name |
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.
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.
For more information, see this tutorial.
Click Save. The Summary tab appears.
Review the listener summary.
Click Save. The listener is created and is in disabled state. To enable the listener, follow the instructions mentioned in Enabling Listeners.
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 erros 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:
The listener is enabled and listening to events from Salesforce. When an error occurs:
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:
Enable the suspended listeners after rectifying the errors manually.
Or, the listener is automatically enabled after a package reload.
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.
You can create a Error Callback Service Spec Flow service in one of the following ways:
The Add listener wizard.
The Integrations page.
In this method, you can create a Error Callback Service Spec Flow service directly from the Events tab in the Add listener wizard. The Error Callback Service Spec specification is automatically selected for the Flow services created using this method.
Go to the Events tab in the Add listener wizard.
Click the + button adjacent to the Select ErrorCallbackFlowService field. The Create CallBackErrorFlowService dialog box appears.
Enter the Flow service name.
Click Save. The callback Flow service is created and saved under the Flow services tab in the Integrations page. By default, the Error Callback Service Spec specification is selected for the Flow services. You must define the Flow service steps as per your requirements before enabling the listener.
In this method, you must manually select the Error Callback Service Spec from the Choose Specification field in the Define input and output fields page.
Go to FlowServcies.
Create a Flow service and define the Flow service steps.
Select Error Callback Service Spec from the Choose Specification field in the Define input and output fields page.
Define the Flow service steps.
Save the Flow service. The callback Flow service is created and saved under the Flowservices tab in the Integrations page. The Flow services created in this manner are listed under the Select ErrorCallbackFlowService field in the Events tab of the Add listener wizard.
When a recoverable or non-recoverable error occurs, webMethods Integration Server moves the listener to the Suspended state. Users can check the error details of a listener by either hovering over or clicking the Suspended option in the Status column.
While recoverable errors are handled automatically by the error handler, non-recoverable errors require user intervention to bring the listener back to active status. When you hover over or click the Suspended option in the Status column, specific details about the error are displayed on the screen. You can identify the cause of the error and take necessary actions to resolve it.
The following table lists the most common error codes that users may encounter, explanation of the cause, and potential resolutions.
Error code | Error message | Explanation | Action |
---|---|---|---|
400 | API version in the URI is mandatory. URI format: '/cometd/55.0' | The API version is missing in the URI | Specify the API version at the end of the URI. For example, '/cometd/55.0'. See Creating Salesforce Listeners for more information. |
400 | Unsupported API version. Only API versions '23.0' and above are supported. URI format: '/cometd/55.0' | The specified API version is not supported. | Specify a valid API version. Supported API versions: ‘23.0’ and above. See Creating Salesforce Listeners for more information. |
400 | The channel you requested to subscribe to does not exist {channel_name} | The streaming channel requested to subscribe to does not exist. | Ensure that you have created a channel before subscribing. |
400 | Channel name not specified | The channel name is not specified. | Specify a valid channel name to subscribe to. |
400 | Channel subscriptions must start with a leading '/' | The specified channel name format is invalid. | Specify a valid channel name. Channel names must start with a leading slash (/). |
400 | Query fields {query_fields} do not exist on the topic entity | The supplied query fields do not exist on the Salesforce object specified in the PushTopic. | Specify valid query fields on the Salesforce object in the PushTopic. |
400 | The replayId {replay_id} you provided was invalid. Please provide a valid ID, -2 to replay all events, or -1 to replay only new events. | The specified replay ID is invalid. | Specify a valid replay ID. Specify -2 to replay all events or -1 to replay only new events. |
401 | Authentication invalid | The specified authentication token or session ID is invalid. |
Perform the following steps to resolve this issue:
|
401 | Request requires authentication | The authentication token or session ID was not provided in the request header. | Provide a valid authentication token or session ID in the request header. |
403 | Cannot create channel {channel_name} | The subscription channel cannot be created, which can be due to insufficient permissions. | Ensure that the required access permissions are provided. |
403 | Subscriber does not have access to the entity in this topic | The subscriber does not have access to the Salesforce object in the PushTopic. | Ensure that the subscriber has access to the Salesforce object in the PushTopic. |
403 | Subscriber does not have access to all fields referenced in the where clause of the PushTopic. | The subscriber does not have access to all fields referenced in the WHERE clause of the PushTopic. | Ensure that the subscriber has access to all fields referenced in the WHERE clause of the PushTopic. |
403 | Handshake denied | The handshake request was denied. |
Perform the following steps to resolve this issue:
|
403 | Client has not completed handshake | The client has not completed a handshake. |
Perform the following steps to resolve this issue:
|
403 | Organization concurrent user limit exceeded | The maximum number of concurrent clients across all channels has been exceeded. | |
403 | Organization total events daily limit exceeded | The maximum number of delivered event notifications within a 24-hour period to all CometD clients has been exceeded. | Try again after 24 hours. |
403 | Restricted channel | The user does not have the required permissions to subscribe to the streaming channel. | Ensure that you have the required permissions to subscribe to the streaming channel. |
403 | User not enabled for streaming | The user does not have the read permission on the PushTopic. | Ensure that you have the read permission on the PushTopic. |
403 | User not allowed to subscribe CDC without View All Data permissions | The user must have the View All Data permission to subscribe to Change Data Capture. | Ensure that you have the View All Data permission before subscribing to Change Data Capture. |
403 | Unknown client | The server deleted the client CometD session due to a timeout, which can be caused by a network failure. |
This error is recoverable and the error handler will automatically correct the error. After some time, on the Listeners screen, click the Refresh icon to see the updated status of the listener. |
403 | Subscription limit exceeded for this topic | The maximum number of concurrent clients per topic for PushTopic and generic events has been exceeded. | |
503 | Server is too busy. Please try your request again later. | The server cannot process the request because it is too busy. |
This error is recoverable and the error handler will automatically correct the error. After some time, on the Listeners screen, click the Refresh icon to see the updated status of the listener. |
The error “403: denied_by_security_policy: create_denied” indicates that the user you are connecting with does not have read or create permissions for the platform event you are trying to subscribe to. This error occurs when the security policies or access settings within Salesforce restrict the creation of platform events for that user. As a result, the subscription attempt fails because it is unable to create the event on behalf of the connecting user.
To view or modify permissions associated with the user, perform the following steps:
Log in to your Salesforce account and navigate to the Setup link in the top-right corner of the home page.
In the Setup page, search for “Users” in the quick find search bar or select Users under the Manage Users section on the left sidebar.
A list of users appears on the screen.
Click on the name of the specific user for whom you want to check the permissions.
On the User detail page, find the Profile field and click on the profile name.
On the Profile detail page, scroll down to find the Platform Event Permissions section and review the permissions assigned to that profile for the platform event. To update the permission set, click on the Edit button, select the checkboxes next to the required permissions, and click Save.
You can create RFCs on the SAP system that invoke services on Integration. This allows SAP users to access the information that is available using SAP® ERP. Before you can create an RFC that invokes a service, you must configure the SAP system to have an RFC destination for an RFC listener running at SAP® ERP. This enables the SAP system to send RFCs. You must also configure the SAP® ERP to have an RFC listener that listens for RFCs from the SAP system.
Complete the following fields to create a new SAP® ERP listener:
Field | Description |
---|---|
Add Listener | |
Type of listener | Type of listener. For example SAP® ERP. |
Select a version | Version of the listener type selected. |
Listener | |
Listener name | Name of the new listener. |
Program ID | Program ID specified when creating the corresponding RFC destination in the SAP system. This field is case sensitive. |
Retry limit | Number of times that the system must attempt to start the listener if the initial attempt fails. When the value is set to 0, the system makes a single attempt. |
Retry backoff timeout | Time in seconds that the system must wait between each attempt to start the listener. This field is irrelevant if the value of Retry limit is 0. |
Connection mode setting selection | |
Gateway host | Gateway Host for accessing the SAP system. This must be exactly the same parameter as you chose for the corresponding RFC destination in the SAP system. |
Gateway service | Gateway Service corresponding to the SAP system number. |
Repository server | Outbound connection alias used as a repository for function interfaces and structure definitions of inbound calls. This way it is possible to use RFCs even if they are not defined in the calling system. |
Logging | |
RFC trace | Enable RFC tracing. Default is disabled. |
Log transaction status | Enable logging of transaction status. Default is enabled. |
Store message body | Enable the message body of the incoming document to be stored, even when a transaction is created (or maintained), and can be monitored later in the transaction list. |
A listener notification works in conjunction with a listener to filter and process the RFC requests and IDocs in SAP® ERP. SAP® ERP uses the following listener notifications to process requests:
You can change the priority of the listener notification execution by dragging and changing the position of the notification in the list.
Complete the following fields to create a new listener notification for ALE Listener Notification(synchronous):
Field | Description |
---|---|
Account | |
Name | Listener Notification name. |
Description | Listener Notification description. |
Action | |
Name | Select the listener notification type as |
IDoc | |
IDoc Type | Identifies the type of IDoc expected by the listener notification. |
Cim Type | IDoc type extension (CIM type/customer extension type). |
SAP system release | IDoc release. |
Old IDoc type 2 IDoc version | |
Request Field Selection | |
Name | Name of the input parameter. |
Type | Java data type of the input parameter. |
Execution Mode | |
Service invoke | Name of the Flow service to invoke when the notification is received. |
Forward confirm event | Enable or disable the SAP ERP to forward the Confirm TID event triggered by the tRFC protocol to the same destination where the document is forwarded. |
Monitor iDocs | Enable or disable the SAP ERP to link the IDoc packet’s TID with the DOCNUMs of the IDocs in that packet. |
Complete the following fields to create a new listener for RFC Listener Notification (Synchronous) notification:
Field | Description |
---|---|
Account | |
Name | Listener Notification name. |
Description | Listener Notification description. |
Action | |
Name | Select the listener notification type as |
Function | |
Function pattern | Type all or part of the name of the function module for which you want to create a listener notification (SAP® ERP). Use pattern-matching characters if you are unsure of the complete name and want SAP® ERP to search for several RFCs with similar names. For example, enter RFC_FUNCTION_* in the field. |
Group pattern | Type all or part of the name of the group for which you want to create a listener notification (SAP® ERP). Use pattern-matching characters if you are unsure of the complete name and want SAP® ERP to search for several RFCs with similar names. |
Reset | Reset the search. |
Apply | Apply the pattern or exact search. |
Function name | Lists the function names matching the pattern. |
Group name | Group name to which the matching functions belong. |
Description | Description of the matching functions. |
Request Field Selection | |
Name | Name of the input parameter. |
Type | Java data type of the input parameter. |
Reply Field Selection | |
Name | Name of the output parameter. |
Type | Java data type of the output parameter. |
Execution Mode | |
Service invoke | Select the Flow service to invoke when the notification is received. |
You can view the runtime status of a listener in the Status column on the Events > Listeners section.
Go to the project in which you want to create a listener.
Click Events > Listeners. All configured listeners are listed.
The runtime status of the listeners is displayed in the Status column. The status of a configured connector listener can be one of the following:
Active: Listener is enabled and active.
Disabled: Listener is inactive.
Pending Enabled: Enabling listener is in progress.
Pending Disabled: Disabling listener is in progress.
Suspended: Listener is suspended when an error occurs during enabling or disabling of the listener.
Hover over the Suspended status in the Status column to check the runtime state of a suspended listener.
Click on the Suspended status in the Status column to get a detailed explanation of the error status.
For Salesforce listener, the suspension could be for one of the following reasons:
You can view, modify, and delete listeners using the options available in the Events > Listeners section.
All newly created listeners are disabled by default.
You can enable a disabled listener by using the Enabled/Disabled toggle button in the State column on the Events > Listeners section. After a listener is enabled, connection with the configured streaming APIs is established. Events are received and processed based on the configured flow.
At times, enabling or disabling a listener might take some time.
If the Select replay option is configured as Last Received, IBM webMethods Integration saves the replay ID of your most recently received event.
Listeners configured with the Select replay option as New and enabled with a specific replay id might miss some of the replay events. This is in accordance with the current feature design.
To enable a listener, do the following:
Go to the project in which you want to create a listener.
Click Events > Listeners. All created listeners appear.
Move the slider on the Enabled/Disabled toggle button in the State column to right. The Configure listener dialog box appears.
Enter the replay ID if you want the listener to receive events from a specific replay ID. For example, if you have events A, B, C, and D with replay IDs A1, B1, C1, D1 respectively, and you want to replay all events that occurred after event B, then enter the event B’s replay ID, that is, B1 in the Specify replay Id field.
If you do not enter any value, then the value configured in the Select replay option field during listener creation is considered.
For new events, enter -1.
For all events, enter -2.
Click Enable. The listener is enabled and receives the events based on the replay ID provided.
You cannot edit a listener while it is enabled. Additionally, the channel you have subscribed to cannot be modified after you have created a listener.
Click the Edit button available in the Actions column to update the listener changes.
The user interface is not dynamically updated based on the listener status.
For example, if a configured listener encounters an error, you may not receive events from Salesforce or the linked integration may not run as expected. During such scenarios, you must manually refresh the listener by clicking the Refresh icon to ensure that the latest status of the listener is reflected in the user interface. To know the current status of a listener, manually refresh the listener by clicking the Refresh icon in the Actions column.
You can delete an existing listener by clicking the Delete button available in the Actions column
However, an enabled listener cannot be deleted.
Let us now understand how to set up a Salesforce listener and run a flow service associated with the listener with the help of an example.
We’ll set up a listener for a Salesforce platform event, and invoke a flow service whenever the platform event updates occur.
As soon as you select a version, you are redirected to the Configure the Listener screen.
You can retrieve the API Name associated with the platform event from your Salesforce account.
With this, the listener starts listening for updates on the subscribed Salesforce platform event.
Now, to test if the listener is working as expected, perform the trigger event in your Salesforce account. For the purpose of this example, let’s create a custom action that automatically updates a specific field of the Salesforce platform event, thereby triggering the listener. You can alternatively use any other method of your choice to perform the trigger event.
With this, you have created a Flow service which when run, automatically updates the specified field of the Salesforce platform event and triggers the listener.
On successful Flow service execution, the output similar to the one shown in the following image is displayed on the right-hand side of the screen.
This updates the corresponding field value(s) in the specified Salesforce platform event.
As soon as the Salesforce platform event is updated, IBM webMethods Integration runs the Flow service associated with it using the project user selected at the time of listener configuration.
Scenario
Let us create a flow service that sends an email for the listener failure events where the ErrorCallBackFlowService has been invoked. The following event logs are captured by the listener from the Salesforce application and the logs are in the document Reference format.
Solution
Go to Flow Editor and provide a name for the flow service, say, ListenerCallbackService.
In the flow step, select the function JSON DocumentToJSONString to convert errorDetails that are in document format to jsonString format.
In the next flow step, select the function JSON DocumentToJSONString to convert results that are in document format to jsonString format.
Both the logs are converted to JSON string format.
In the next flow step, select the function Concat to concatenate the logs converted to jsonString format in steps 2 and 3.
In the next flow step, select Flow LogCustomMessage to log the concatenated message.
In the next flow step, select the Send Email action from the Simple Mail Transfer Protocol (SMTP) connector to send the logged message in step 5 as an email.
Till now, the flow service has the following steps:
Save and run the flow service. You will receive an email listing the failure details.
Also, the logged message can be viewed under Flow service executions on the Monitor page.
Let’s understand how to use the SAP® ERP RFC Listener Notification with the help of an example.
Let’s say you have a project Test_SAP_ERP. You want to create a SAP® ERP Listener.
To create a SAP® ERP Listener follow the steps given below:
Click New listener, select SAP® ERP for Type of listener and SAP® ERP_v1.0 for Select version from the dropdown list.
This will redirect you to the Add listener configuration screen.
Provide the following details:
Click Next.
Select Standard (Default) action.
Click Next.
Provide the following details in the Connection mode:
Click Next.
Enable/Disable the logging details.
Click Next.
Verify the connection details.
Click Save and Next.
Click Add listener notification.
This will redirect you to the Add Listener Notifications screen.
Provide the following details:
Click Next.
Select RFC Listener Notification (synchronous) action.
Click Next.
Search and select the RFC function to invoke:
a. You can perform search with different combinations as shown:
Click Apply.
b. Select the function from the list of function names available on the screen. In the example, select the Z_RFC_ADD function.
Click Next.
In the Request Field Selection screen, select the input fields to add.
In the example, select IP_VALUE1 and IP_VALUE2 input fields.
Click Next.
In the Reply Field Selection screen, select the output fields to add.
In the example, select EP_RESULT output field.
Click Next.
Select the service to be invoked from the dropdown list.
Click Next.
Verify the details.
Click Done. You will see the configured notification.
Invoke the Listener notification using the SAP GUI.
a. Provide the following details in Test Function Module screen:
b. Click to execute.
Let’s understand how to use the SAP® ERP for RFC invocation with the help of an example.
Let’s say you have a Flow service SAP_ERP_Test_FS inside Test_SAP_ERP project. The Flow service SAP_ERP_Test_FS used in the example is a simple Flow service that uses the RFC invocation action from SAP® ERP You want to invoke this Flow service.
To invoke and run SAP_ERP_Test_FS(Flow service), you must create an account to connect to SAP® ERP.
Start creating the Flow service. Select SAP® ERP from the dropdown list.
Select Add Custom Operation in the dropdown list next to SAP® ERP.
This will redirect you to the Action configuration screen.
Provide the following details:
Click Next.
Select RFC Invocation action.
Click Next.
Search and select the RFC function to invoke:
a. You can perform search with different combinations as shown:
Type the group pattern to which the function belongs in the Group pattern field. For example: *.
Click Apply.
In the example, search for Z_RFC*.
b. Select the function from the list of function names available on the screen.
In the example, select the Z_RFC_ADD function.
Click Next.
In the Request Field Selection screen, select the input fields to add.
In the example, select IP_VALUE1 and IP_VALUE2 input fields.
Click Next.
In the Reply Field Selection screen, select the output fields to add.
In the example, select EP_RESULT output field.
Click Next.
Verify the details.
Click Add.
Click Done. You will be redirected to the Flow services screen.
Run the Flow service.
a. Click the icon and add the values for the input parameters.
b. Click the icon. The resulting value is displayed.