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

Note: Currently the Listeners feature is enabled only for the 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. For more information about role and permissions, see Roles.

  2. Click New Listener and 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. 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:

    • 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/, for 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.

      • Last Received - Receive all events that occurred after the most recently saved replay ID. The webMethods.io 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, Software AG 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.

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

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


  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 and is in disabled state. To enable the listener, follow the instructions mentioned in Enabling Listeners

    Notes:

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

Example - Setting up Salesforce Listener

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, go to Configurations > FlowService > Triggers > Listeners.

  3. Click the New Listener button.

  4. In the Add Listener screen, select the version for which you want to set up a listener.

    As soon as you select a version, you will be redirected to the 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 Last Received to receive all events that occurred after the most recently saved replay ID. The webMethods.io 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.
    • Select subscription: As you want to listen to a Salesforce platform event, select Salesforce Platform Event from the drop-down list.
  6. Provide a default value for the subscribed Salesforce event. As 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 available 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 run 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 menu, select Add Custom Operation.

  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 the 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 the 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 the 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 runs the FlowService associated with it using the project user selected at the time of listener configuration.

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

Managing Listeners

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

Enabling Listeners

All newly created listeners are disabled by default.

You can enable a disabled listener by using the Connectivity status button on the Listeners screen. After a listener is enabled, the connection with the configured streaming APIs is established. Events are received and processed based on the configured flow.

Notes:

  • At times, enabling or disabling a listener might take some time.

  • If the Select replay option is configured as Last Received, webMethods.io Integration system saves the replay ID of your most recently received event.

To enable a listener, perform the following steps:

  1. Go to Project > Configurations > FlowService > Triggers > Listeners. All created listeners are displayed.

  2. Move the slider on the Connectivity status button to enable the listener. The Configure listener screen appears.

  3. 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, you can enter -1.

    • For all events, you enter -2.

  4. Click Enable. The listener is enabled and receives the events based on the replay ID provided.

Notes:

  • Salesforce has different allocations for PushTopic, Generic, Change Data Capture, and Platform events based on your license. Ensure that you have carefully reviewed the allocations to understand your subscription and consumption limit for your configured solution.

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.