Creating and Managing RDPs (Webhooks)

A REST Delivery Point (RDP) is an object provisioned on a Solace event broker that functions as a webhook. It binds to a queue and provides a connection between the event broker and one or more REST endpoints to enable the REST endpoint to consume Guaranteed messages from the queue. For more information about how RDPs function to send messages to REST endpoints, see REST Consumers.

In Event Portal, RDPs are represented as a type of application. For general information about working with applications, see Applications.

You can create applications in any application domain where you have Editor or Manager level access. When you create an RDP, you can specify several attributes:

  • name
  • version display name, and number for the first version
  • any application or version custom attributes
  • event flows and consumer subscriptions

You can also specify runtime configuration for event brokers, including:

  • the client profile
  • queue configuration properties
  • queue bindings and connection details for the destination REST consumer

After configuring the application, you may want to:

  • promote the application to one or more environments

This section includes the following tasks:

For a demonstration of configuring an RDP in Event Portal, watch this video:

Video illustrating the the features described in the preceding text.

For a demonstration of a more advanced configuration, see: RDP Configuration and Promotion Demonstration Video.

Creating an RDP

You can create and update applications using the graph view or the component view. Solace recommends starting in the graph view and using the component view for updates and more advanced configuration. The graph view lets you work with the latest non-retired version of all events and applications in the application domain. For more information about working in the graph view, see Using the Graph View.

When you add an RDP in the graph view, Event Portal automatically adds a linked standard application that represents the destination REST endpoint that the RDP sends events to. This application is added for modeling purposes but is not required to properly configure your RDP; you can keep it for the visual representation in the graph or you can delete it.

To create an RDP in the graph view, perform these steps:

  1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
  2. On the navigation bar, select Designer .
  3. On the Application Domains page, click the application domain that you want to add the application to.
  4. In the graph view, click Add Objects and select the Solace tab.
  5. Under Integration Applications, click the REST Delivery Point (Webhook) that matches the destination REST endpoint type, and then click the graph where you want to position the applications. You can select from these options:
    • Generic Destination
    • AWS S3
    • AWS API Gateway
    • Azure Data Lake Storage Gen2
    • Azure Event Hubs
    • Azure Functions
    • Azure Service Bus
    • Google Cloud Functions
    • Google Cloud Run
    • Google Cloud Storage
  6. (Optional) If you want to change the appearance of the icon, click below the application name and select a color and an icon or logo, then click Apply. For more information see Customizing Object Appearance.
  7. Enter a name for the RDP application. The destination application name is set automatically. You can change the names later.

  8. Specify one or more events that the RDP application intends to subscribe to. Hover over the event and drag the arrow that appears to the RDP version.

    Screenshot showing the action described in the previous step.

    If you want to associate the application with a shared event from another application domain that does not appear in the graph, see Associating Shared Events in the Graph View.

    If you want to associate the application with an older version of an event, for example, if you want to link to the latest released version and there is a newer draft version, use the component view.

  9. Click the application to display its information in the Details panel.
  10. To update the application name, version, or description:
    1. In the Details panel, click . 
    2. Update the attributes as necessary.
    3. Click Save.
  11. To update any custom attributes:
    1. In the Custom Attributes panel, click . The Custom Attributes panel does not display if no custom attributes are available for the application.
    2. Select This Version or Application to display version or application custom attributes.
    3. Update the custom attributes as necessary.
    4. Click Save.
  12. To open the application in component view to add consumers and runtime configuration details:
    1. In the Details panel, click Open Full Application Details.
    2. Click Edit This Version.
    3. Update the application version as necessary. For more information, see Updating an RDP in the Component View.
    4. Click Save & Close.

Updating an RDP in the Component View

The component view includes options for applications that are not available in the graph view and allows you to manage event flows involving older versions of events.

For a demonstration of advanced configuration for an RDP in Event Portal, see RDP Configuration and Promotion Demonstration Video.

To update an RDP version in the component view, perform these steps:

  1. On the navigation bar, select Designer .
  2. On the Application Domains page, click the application domain that contains the application you want to update.
  3. Click Components  to switch to the component view.
  4. Select the Applications tab and then click the name of the application you want to update.
  5. Perform one of the following actions:
    • In the Versions list, select an application version in draft state to edit.
    • In the Versions list, select an application version that you want to base a new version on and click Duplicate Version . All properties of the selected version are copied into a new version. By default, the new version number is incremented by 0.0.1. You can change the version number to any number not already in use.
  6. (Optional) To update the application or version details
    1. Click Edit Details.
    2. Update the Name and Appearance on Graph as necessary.
    3. Select the Version Details tab and update the Version number, Version Name and Description as necessary.
    4. Select the Custom Attributes tab. The tab does not display if no custom attributes are available for the application.
    5. Select This Version or Application to display version or application custom attributes and update the custom attributes as necessary.
    6. Click Save.
  7. To select events that the application intends to subscribe to, perform these steps:
    1. In the Event Flows section, select Events.
    2. Click Add Events.
    3. In the Application Domain list, select the application domain that contains the event to subscribe to. By default, the list shows events in the current application domain. You can select a different application domain, or you can remove the filter to show shared events in all application domains that you have access to.
    4. (Optional) In the Modeled Event Mesh list, select a modeled event mesh and environment to list only event versions published in the selected modeled event mesh.
    5. Expand an event to see the list of event versions.
    6. Select Sub for the event version that you want the application to subscribe to.
    7. When you are finished selecting events, click Save.
    8. If a consumer for the subscription already exists, in the list of Subscribed Events, click Setup Subscription for an event to select the consumer to add the subscription to.
  8. To remove an event from those that the application intends to subscribe to, click for the event.
  9. To create a Solace event queue, perform these steps:
    1. Select the Advanced Subscription Setup tab.
    2. Click Create Consumer.
    3. Enter a name for the queue.
    4. Click Save.
  10. To add subscriptions to a consumer, perform these steps:
    1. On the Advanced Subscription Setup tab, click Add Subscription  for a consumer. Event Portal suggests subscriptions for any declared subscribed events that are not already attracted by a consumer.
    2. Modify any of the topic subscriptions as necessary. If the topic address uses variables you can subscribe to one or more of the options. You can use * and > as wildcard characters to subscribe to a group of related topics. For more information, see Topic Subscriptions.
    3. Click Duplicate  for a subscription to create a copy of it, for example if you want several subscriptions that are the same except for a variable.
    4. To see which events the subscription attracts, click Preview Attracted Events and select whether you want to see a preview for the designed event flow or a specific modeled event mesh.
  11. If your application references a shared event from another application domain that requires approval, send a request to use the event. All event access requests must be approved before the application can be promoted to an environment. For more information, see Requesting Event Access.
  12. Add runtime configuration details for the application. For more information, see Adding Runtime Configuration to an RDP.

Adding Runtime Configuration to an RDP

Before you add runtime configurations to your application, Solace recommends that you complete the steps to create an RDP, including defining your event flows and creating consumers. You must also ensure that the model event broker you want to promote the application to has already been added to the appropriate modeled event mesh. For more information, see Adding an Event Broker to a Modeled Event Mesh.

If you have the Show Guidance option enabled in the graph view, the Guidance panel displays the next steps required to complete the runtime configuration and promote the application to an event broker. You can also complete the configuration by opening the full application details.

Designer steps you through configuring your application. If you make any changes to the configuration you can click Save & Close at any time to save your updates and return later.

To add runtime configuration to an application, perform these steps:

  1. On the Application Domains page, click the application domain that contains the application.
  2. In the graph view, click the application.
  3. Perform one of the following steps:
    • If you want to configure the version displayed in the graph view and the Guidance panel shows the Configure button, click Configure.
    • In the Details panel, click Open Full Application Details, and perform these steps.
      1. In the Version list, select the application version you want to configure.
      2. Select Configurations.
      3. Click Create Configurations.
  4. In the Configure Application dialog, in the Set Context step, click the environment containing the event broker you want to configure the application for, and then select the Event Broker from the list that appears.
  5. (Optional) If you have already added the application to another event broker and want to use the same settings, select the event broker you want to use the settings for from the Reuse Existing Configuration list.
  6. Click Next: Define Event Handling. The dialog displays the consumers that are part of the application and the events they attract. If you need to leave the dialog, for example to update create another consumer, you can click Save & Close and return later.
  7. (Optional) If you want to set a client profile name for the application, click Show Advanced Options and type or select a Client Profile Name. The default behavior is to use the default client profile on the event broker. The environment may require you to select a template.
  8. (Optional) If you want to customize the configuration of a Solace queue, with Show Advanced Options selected, customize the displayed Queue Configuration or click Switch to Template to select a queue configuration template. The environment may require you to select a template and set values required by the template. For more information about queue configuration, see Queue Configuration.
  9. In the Request Target field, enter the POST request target resource for message delivery on the REST endpoint. For more information, see REST Consumer and Queue Binding Configuration.
  10. (Optional) If the RDP does not send events to unique targets based on the message topic, metadata, or the current time, with Show Advance Options selected, select None in the Request Target Evaluation list. The default is Substitution Expressions, which is useful when forwarding messages into storage services such as Azure Storage, Amazon S3, or Google Cloud Storage. If you skip this step and don't require substitution expressions, the RDP will still function as expected. For more information about substitution expressions, see Substitution Expressions Overview.
  11. (Optional) If you want to include metadata in the request header:
    1. With Show Advance Options selected, click Add Request Header.
    2. In the Header Type list select whether the header is Standard or Protected. Protected request header values are masked from viewing on management interfaces and in logs. This helps protect sensitive information in the header but doesn't support substitution expressions.
    3. In the Header Name field, enter the name of an HTTP request header to associate with the queue binding. Request header names can contain up to 50 characters but cannot have the following values: Authorization, Connection, Content-Length, Expect, Transfer-Encoding, or Upgrade.
    4. In the Header Value field, enter the data you want to include in the message header. If the Header Type is Standard, you can use substitution expressions. The value can contain up to 2000 characters.
  12. Click Next: Define Destination.
  13. Set the appropriate connection details for the REST endpoint. For more information, see REST Consumer and Queue Binding Configuration. If you need to leave the dialog, for example to get the required connection details, you can click Save & Close and return later.
  14. Click Next Review.
  15. Perform one of the following steps:
    1. If you're ready to promote the application, click Start Promotion.
    2. If you're not ready to promote the application, click Save & Promote Later. You can click the Promote button in the Guidance panel to promote the application later.

    When you're ready, complete the promotion according to the steps for Promoting an RDP to an Environment.

  16. If you want to add the same application version to another event broker, in the Guidance panel click Configure for Another Event Broker to repeat this task and select a different event broker, or create additional configurations by repeating these steps from the Application Details page.

Promoting an RDP to an Environment

Environments in PubSub+ Cloud represent the operational environments within your organization. In Event Portal you create modeled event meshes within environments and add model event brokers to the modeled event meshes to represent event flows through one or more operational event brokers. For considerations related to promoting applications to event brokers, see Promoting Applications to Environments.

To promote an application, perform these steps:

  1. On the Application Domains page, click the application domain that contains the application.
  2. In the graph view, click the application.
  3. Perform one of the following steps:
    • If you want to promote the version displaying in the graph view and the Guidance panel shows the Promote button, click Promote.
    • In the Details Panel, click Open Full Application Details, and perform these steps.
      1. In the Version list, select the application version you want to promote.
      2. Select Promotions.
      3. Click Promote Version.
  4. Click the environment containing the event broker you want to promote the application to, and then select the Event Broker from the list that appears.

  5. If any errors exist, such as queue name or client username conflicts, correct them before promoting the application.

    If any Suggested Changes appear, you can make the changes before promoting the application, or you can promote the application and fix any issues later. The suggested changes can include fixing the following mismatches:

    Mismatch Description Resolutions

    Subscription Attracts a Different Event Version

    A consumer subscription in the application attracts a different version of an event than the declared event version that the application intends to subscribe to.

    Verify which version of the event the consumer needs to subscribe to and perform one of the following actions:

    • Update the consumer subscription.
    • Update the version of the declared event that the application version references.
    • Add an application that publishes the event version to the modeled event mesh.

    Event Not Published in Modeled Event Mesh

    The application has a declared event version that it intends to subscribe to but no application in the modeled event mesh publishes that event.

    Add an application that publishes the event version to the same modeled event mesh.

    Event Has No Matching Subscription

    The application has a declared event version that it intends to subscribe to, but does not have a consumer with a matching subscription to attract the event version.

    Perform any of the following actions:

    • Subscribe to the event version with an existing consumer.
    • Add a new consumer to the application that subscribes to the event version.
    • Remove the event version from the list of events the application intends to subscribe to.

    Subscription Attracts Additional Events

    The application has a consumer subscription that attracts an event that is not one of the declared event versions that the application intends to subscribe to.

    Perform one of the following actions:

    • Update the application version to declare the intent to subscribe to the additional event version
    • Update the consumer subscription if it is attracting an unintended event.

    When an application has one or more consumers that attract events without a declared intent, a list of the additional consumed events displays below the consumers on the application page.

    Event Has No Topic Address

    A declared event version that the application intends to subscribe to does not have a topic address.

    Add a topic address to the declared event version.

  6. Click Preview Promotion and review the details.

  7. Click Promote.

Removing an RDP From an Environment

You can remove an application version from a modeled event broker. If you want to change the version of an application, you can just promote the new version and the previously associated version is automatically removed.

To remove an application from a modeled event broker, perform these steps:

  1. On the Application Domains page, click the application domain that contains the application.
  2. In the graph view, click the application.
  3. In the Details Panel, click Open Full Application Details, and perform these steps.
  4. Select Promotions.
  5. In the list of event brokers that the application has been promoted to, click More Actions for the event broker you want to remove the application from.
  6. Click Remove Application.
  7. Click Force Promote to send the change to the event broker.

RDP Configuration and Promotion Demonstration Video

Video illustrating the the features described in the preceding text.