Listeners

webMethods.io Integration allows you to integrate with streaming APIs and process streaming API events using listeners. You can subscribe to any supported streaming API event and specify the FlowService that should be invoked when the subscribed event occurs.

Creating Listeners

To create a listener, perform the following steps:

Note: Currently, this feature is enabled only for Salesforce connector.

  1. Go to the project in which you want to create a listener, click the Configurations tab, and then select FlowService > Triggers > Listeners.

    Note: You must have an admin, developer, or a custom role with write and execute permissions for the project in which you are trying to create a listener. If you do not have the necessary permissions, you will not be able to create listeners. Know more about project roles.

  2. Click New Listener and enter the following details in the Add Listener screen that appears:

    • Type of listener: Select the name of the connector from the drop down list for which you want to create a listener. Currently, listener support is enabled only for the Salesforce connector, so this field is auto-populated.
    • Select version: Select the connector version for which you want to create a listener.
  3. Enter the following details in the Add Listener configuration screen that appears:

    • 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:///cometd/

      Example: https://ap5.salesforce.com/cometd/44.0

    • Select replay option: The webMethods.io Integration listener for Salesforce can subscribe and listen to Salesforce events. This allows the webMethods.io 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 an opaque ID which is unique 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, replayId values may have a break between them, for example, the event with ID 110 may follow the 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 can use it on a resubscription, to retrieve events that are within the retention window.

      • 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 including new events. Replay all the events for the last 24 hours.
    • 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.
  4. Click Next.

    You will be redirected to the Parameters and Headers screen.

  5. 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 format(s) 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 Three formats are supported:
      • ChangeEvent name
      • ObjectNameChangeEvent
      • CustomObjectName_ChangeEvent
      Generic Event GenericStreamingChannel name

  6. Click the Add Header button 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 the Delete button to delete the header.
  7. Click Next and specify the following details in the Event screen:

    • Select FlowService name: Select the FlowService you want to run when the subscribed event occurs.
    • Select a user to run FlowService: Select a project user you want to use to run the selected FlowService. If the selected user does not have necessary permissions to run the specified FlowService, the FlowService execution will not complete when the subscribed event occurs.
  8. Click Next, review the listener summary, and click Save to create the listener.

    With this, the listener is created.

    Note: Listeners created in one tenant cannot be published to another tenant.

Example

Let’s now understand how to set up a Salesforce listener and run a FlowService associated with the listener with the help of an example.

Let’s say, you want to set up a listener for a Salesforce platform event and invoke a FlowService whenever the platform event updates occur. To do so, perform the following steps:

  1. Login to webMethods.io Integration tenant, select a project, and create the FlowService you want to invoke when the subscribed listener event occurs.
  2. In the same project, navigate to Configurations > FlowService > Triggers > Listeners.
  3. Click the New Listener button.
  4. In the Add Listener screen that appears, select the version for which you want to set up a listener.

    As soon as you select a version, you will be redirected to Configure the Listener screen.

  5. Provide the following details to configure the listener:

    • Name: Provide a display name for the listener. It can contain alphanumeric characters, underscores (_) and hyphens (-).
    • Description (optional): Provide a description for the listener.
    • Streaming API endpoint URL: Specify the Salesforce streaming API endpoint URL associated with the Salesforce account for which you want to set up a listener. For example, https://ap5.salesforce.com/cometd/48.0
    • Select Account:Select an existing Salesforce CRM account or create a new one.
    • Select replay option:
      • Select NEW if you want to receive new events that are broadcast after the client subscribes and replay only the new events from the time the listener is enabled.
      • Select ALL if you want to receive all events including past events that are within the retention window including new events and replay all the events for the last 24 hours.
    • Select subscription: Since you want to listen to a Salesforce platform event, select the Salesforce Platform Event option in the drop-down list.
  6. Provide a Default Value for the subscribed Salesforce event. Since you have subscribed to a Salesforce platform event, the default value is the API Name associated with the platform event you want to listen to. (Refer to the Salesforce event and their supported default value format table present under the step 5 of the previous section.)

    You can retrieve the API Name associated with the platform event from your Salesforce account.



  7. Click Next.
  8. Select the FlowService you want to invoke and the user through which you want to invoke the FlowService.
  9. Click Next.
  10. Review the listener configuration and then click Save.
  11. Enable the listener.

    With this, the listener starts listening for updates on the subscribed Salesforce platform event.

  12. 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.

  13. Create a new FlowService and select the Salesforce CRM connector with the version for which you have created the listener.
  14. In the Type to choose action drop-down, select Add Custom Operation option.
  15. Select the authentication type, select/create the account you want to use to execute the custom action, and provide a name for the custom action.
  16. Click Next.
  17. In the Operation screen that appears, select create operation and then click Next.
  18. In the Input Business Object screen, select the Salesforce platform event name for which you have created the listener and then click Next.
  19. In the Select the Data Fields screen, select the field(s) on which you want to perform update operation. The list of fields displayed on this screen will vary based on the selected Salesforce platform event.
  20. Click Next.
  21. Review the entered custom action details and then click Done.
  22. Click the Edit Mapping icon.
  23. Click the + icon beside the custom action input block.
  24. Double-click the field names to configure the input values. When you run this custom action, these values are updated to the corresponding Salesforce platform event fields.
  25. Click Save.
  26. Provide a display name for FlowService and click Save.

    With this, you have created a FlowService which when run, automatically updates the specified field of the Salesforce platform event and triggers the listener.

  27. Run the FlowService.

    On successful FlowService 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, webMethods.io Integration invokes the FlowService associated with it using the project user selected at the time of listener configuration.

  28. Navigate to Monitor > Execution results > FlowService execution to view the execution logs of the invoked FlowService.

Managing Listeners

Once the listeners are created, you can view, modify, and delete them by navigating to the project > Configurations > FlowService > Triggers > Listeners.

Enabling Listeners

All newly created listeners are disabled by default.

To enable a listener, toggle-on the Connectivity status switch. Listener enablement will take a few seconds, after which a connection with the streaming API will be established and incoming trigger events will be processed based on the selected subscription.

Note: Salesforce trial accounts have restrictions on the maximum number of concurrent subscribers. See PushTopic Streaming Allocations for more information. If you create multiple listeners using the same trial account details, due to the high availability nature of webMethods.io Integration, some active listeners may not work properly.

Editing Listeners

You can change certain configuration settings of your listener by either clicking the listener name or the Edit icon.

Notes:

  • You cannot edit a listener while it is enabled.
  • You cannot modify the channel you have subscribed to after you have created a listener.

Deleting Listeners

You can delete an existing listener by clicking the Delete icon.

Note: You cannot delete a listener while it is enabled.