Creating and Managing Standard Solace Applications

Standard Solace applications in Event Portal represent any client application that connects to a Solace event broker to publish or subscribe to events.

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 a standard Solace application, 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
  • connection details for the client application

After configuring the application, you may want to:

  • promote the application to one or more environments
  • download an AsyncAPI document for the application

This section includes the following sections:

Creating a Standard Solace Application

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.

To create a standard Solace application 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. Click New Standard Application and then click the graph where you want to position the application.
  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 application.

  8. (Optional) If you want the application to publish an event version that shows in the graph, hover over the application and drag the arrow that appears to the event.

    Screenshot showing the action described in the previous step.

  9. (Optional) If you want the application to subscribe to an event version that shows in the graph, hover over the event and drag the arrow that appears to the application 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.

  10. (Optional) If you want to show a link between two applications without specifying an event flow, hover over the application you want to designate as a source and drag the arrow that appears to the application that you want to specify as a destination.

    Screenshot showing the action described in the previous step.

  11. Click the application to display its information in the Details panel.
  12. To update the application name, version, or description:
    1. In the Details panel, click . 
    2. Update the attributes as necessary.
    3. Click Save.
  13. 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.
  14. 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 Standard Solace Applications in the Component View.
    4. Click Save & Close.

Updating Standard Solace Applications in the Component View

The component view allows you to create and edit applications and allows you to manage event flows involving older versions of events.

These instructions use the new interface that we have introduced for configuring applications. if necessary, you can turn off the Use updated interface toggle in the graph view to revert to the old interface. This toggle is available temporarily to help current users transition to the improved workflow. Kafka applications still use the previous interface. For more information about updating applications using the previous workflow, see Updating a Kafka Application in the Component View.

To update an application 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 publishes or 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 publish or 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. To publish the event, select Pub for the event version that you want the application to publish.
    8. When you are finished selecting events, click Save.
    9. 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 consumer, perform these steps:
    1. Select the Advanced Subscription Setup tab.
    2. Click Create Consumer.
    3. Enter a name.
    4. Select a consumer type:
      • Event Queue—Represents a queue endpoint on an event broker that attracts Guaranteed messages with topic subscriptions. If you have runtime configuration enabled, you can configure a queue consumer in an application in Event Portal, and the queue can be created or updated on the event broker.
      • Direct Client—Represents a direct connection to an event broker that attracts Direct messages with topic subscriptions. If you have runtime configuration enabled, direct client consumers can update topic subscription ACLs on the event broker.
    5. 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 a Standard Application.

Adding Runtime Configuration to a Standard Application

Before you add runtime configurations to your application, Solace recommends that you first complete the steps to create a standard application, 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.

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. The Use Defaults option is available only if you have not configured event flows.
    • 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. Click Next: Define Access Control. If you need to leave the dialog, for example to get the access requirements for the event broker, you can click Save & Close and return later.
  10. Enter the client credentials for the application. These credentials allow the client application in the runtime to connect to the event broker. To enter the credential information:
    1. Select the Access Type. You can select Basic, Authorization Group, Client Certificate, or Reference Existing Client Username.
    2. If you selected Basic, specify a Client Username and Password.
      • The Client Username can be a maximum of 189 characters and can't include the following characters: ? *.
      • The Password can be a maximum of 128 characters and can't include the following characters: : ( ) " ; ' < > , ` \ & |
    3. If you selected Authorization Group, specify the Authorization Group Name and Client Username.

      The Authorization Group Name is the name for the LDAP or OAuth authorization group configured on the event broker.

    4. If you selected Client Certificate authentication, specify the Client Username.

      The Client Username must match the certificate Common Name for the application's certificate. You must upload certificates to the event broker directly. For more information, see Configuring Client Certificate Authentication.

    5. If you selected Reference Existing Client Username, specify the Existing Client Username.

      The Existing Client Username must match a client username that has been configured on the event broker. This application uses the authentication method and credentials already configured for that client username.

  11. Click Next Review.
  12. Perform one of the following steps:
    1. If you're ready to promote the application to an environment, click Start Promotion.
    2. If you're not ready to promote the application, click Save & Promote Later. You can start promotion later from the Guidance panel or the component view.

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

  13. 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 a Standard Application 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 Application 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.

Downloading an AsyncAPI Document for an Application

An AsyncAPI document is a JSON or YAML file generated according to the AsyncAPI Specification. For more information, see the AsyncAPI Initiative. You can give the AsyncAPI document to application developers to help them create the actual applications that are part of your event-driven architecture (EDA).

You can download an AsyncAPI document for an application with or without server details and operation bindings for an event broker that the application is associated with.

To download an AsyncAPI document for an application, perform these steps:

  1. On the Application Domains page, click the name of the application domain that contains the application.
  2. In the graph view, click the application that you want to download the AsyncAPI document for.
  3. In the Details panel, click Open Full Application Details.
  4. In the Version list, select the version that you want to download the AsyncAPI document for.

  5. Click Download Async API.

    Alternatively, select Promotions and click More Actions for an associated event broker and then select Download Async API.

  6. If you opened the Download Async API dialog from the left panel and want to include server details and operation bindings for an event broker that you have added the application to, select the event broker from the Event Broker Context list.

    If you opened the Download Async API dialog from the Promotions panel, you have already selected the event broker.

  7. (Optional) To specify the details to include in the AsyncAPI document, click Advanced Options and select one or more of the following options:

    Option Description

    Declared subscribed events

    Events that the application has a declared intent to subscribe to in the application event flow.

    This option is selected by default if you do not select an event broker.

    This option is not selected by default if you select an event broker.

    Operation bindings on declared subscribed events

    Protocol-specific information for the declared subscribed events. For more information about bindings, see the AsyncAPI Documentation.

    This option is selected by default if you do not select an event broker.

    This option is available only if Declared subscribed events is selected.

    Attracted events

    Events attracted to the application by a consumer topic subscription.

    This option is selected by default if you select an event broker.

    This option is not available if you do not select an event broker.

    Operation bindings on attracted events

    Protocol-specific information for attracted events.

    This option is selected by default if you select an event broker.

    This option is available only if Attracted events is selected.

    Servers

    Connection information for the event broker.

    This option is selected by default if you select an event broker.

    This option is not available if you don't select an event broker.

    Server bindings

    Protocol-specific information related to the event broker connection.

    This option is selected by default if you select an event broker.

    This option is available only if Servers is selected.
  8. Select JSON or YAML file format.
  9. If you want to exclude any Event Portal extensions from the AsyncAPI document, in the Document Extensions list, select the extensions that you want to exclude. You can exclude:
    • Event Portal version ID extensions for all objects
    • Event Portal parent ID extensions for all objects
    • all Event Portal extensions
  10. (Optional) Select at least one naming strategy to apply to prevent naming conflicts. All objects are renamed with the chosen naming strategy to ensure objects with the same name can be differentiated in the file:
    • Prepend application domain names—use this option when the file contains events or schemas with the same name.
    • Append major version number—use this option when the file contains more than one object version of the same name.

    Applying a naming strategy does not update the names of referenced schemas within the schema content. If a schema is renamed, you need to update the references to that schema name in any other schemas that reference it. You can update the reference in Designer and regenerate the AsyncAPI document or update the references in the API document each time you generate it.

  11. Click Download.

    If any naming conflicts exist that are not resolved by a selected naming strategy, a dialog describes the conflict to help you resolve it.

Publishing and Subscribing Application Demonstration Videos

These video demonstrations should you how to create applications that publish and subscribe to events.

Publishing Application Demonstration

For a demonstration of customizing icons, watch this video:

Video illustrating the the features described in the preceding text.

Subscribing Application Demonstration

For a demonstration of customizing icons, watch this video:

Video illustrating the the features described in the preceding text.