Applications

An application in Event Portal represents a client application connecting to an event broker. A client application may be a program, process, microservice, IoT device, integration component, or other runnable consumer or producer of events that interacts with an event broker.

You can create new applications in Designer, or you can import Solace queues or Kafka consumer groups from operational event brokers to add applications to Designer. For more information about importing applications, see Importing Runtime Objects into Event Portal.

This section includes the following tasks:

• Creating Applications
• Updating Applications
• Changing the State of an Application Version
• Adding Consumers to Applications
• Adding Applications to Environments
• Downloading an AsyncAPI Document for an Application

You can move applications to other application domains. For more information, see Moving Objects Between Application Domains.

You can also create custom attributes for applications. For more information, see Using Custom Attributes.

Creating Applications

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

• name
• event broker type (Solace or Kafka)
• version display name, number, and state for each version
• any application or version custom attributes
• event flows

Considerations for Creating Applications

Event Flows

Event flows for an application specify events that are published and consumed (subscribed to) by the application. When you model event flows for applications you can use the following options:

• Specify events that the application publishes.

• Specify events that the application intends to subscribe to. Identifying the intent before configuring consumers is helpful in these ways:

  • It flags the event in the modeled event mesh if no application publishes it.
  • It flags the application in the modeled event mesh if no consumer is configured to attract the event.
  • It enables Event Portal to help you create the consumer and topic subscription.
  • It includes the application when calculating the event reuse index in KPI Dashboard.

• Specify the consumers that subscribe to the event in the runtime to attract the event to application. The type of consumer depends on the application type;

  • Event Queue—Represents an endpoint on a Solace event broker that attracts Guaranteed messages with topic subscriptions. The runtime applications binds to the queue to consume messages.
  • Direct Client—Represents a direct connection between an application and a Solace event broker that attracts Direct messages with topic subscriptions but does not store messages while the consumer is offline or reconnecting.
  • Consumer—Represents a consumer group in a Kafka cluster that subscribes to topics.

Solace Queue Configurations

If you intend to push applications and queue configurations from Event Portal to your operational event brokers you should be aware of the following considerations:

• To subscribe to events, you must configure Solace event queue consumers. Each Solace event queue consumer you create for the application configures a queue on the event broker.

• You can include the queue configuration in JSON format in the Solace event queue consumer. Users with the Event Portal Manager role can create Solace queue templates in Runtime Event Manager to help users quickly configure the appropriate settings.

• You can specify the name of the client profile on the event broker that applies to the client application when it authenticates with the event broker. Client profiles assign a common set of configuration properties to client applications. Users with the Event Portal Manager role can add Client Profile Name templates in Runtime Event Manager to specify the client profiles available on your event brokers and require users to select from a list of names when configuring the application. For more information about managing client profiles on event broker services, see Using Client Profiles and Client Usernames.

• You must provide the client username and the credentials for basic authentication or group authorization for the event broker when you add the application to the environment.

• For more information about setting up runtime configuration, see Configuring Event Brokers in Event Portal.

Shared Event Access and Approval

Applications can publish or subscribe to events in other application domains only if the events are allowed to be shared. The events may also require approval.

• If an application publishes or consumes an event that it does not have approval for, a banner appears at the top of the Application Details page. For an application to require event access approval the following conditions must be met:

  • The event's Access Approval is set to Requires Approval.
  • The application and the event that requires approval are located in different application domains.
  • The application publishes the event that requires approval or the application attracts the event through a consumer with an appropriate subscription.
• All event access requests must be approved before the application can be added to an environment. For more information about requesting event access, see Managing Event Data Access.
  

You can create applications using the graph view or the component view. The method you choose depends on your workflow:

• If you want to create several applications and events and specify their relationships quickly, and then add more details later, you may want to start in the graph view.
• If you want to specify the consumer details when you create the application, you may want to start in the component view.

Creating an Application in the Graph View

To create an 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 drag a new Solace or Kafka application onto the graph. Alternatively, you can right-click on the graph where you want to position the application.
5. Enter a name for the application.

6. (Optional) If you want to specify that the application version publishes an event version that shows in the graph, hover over the application and drag the arrow that appears to an event version of the same type (Solace or Kafka).

   

   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.

7. (Optional) If you want to specify that the application version intends to subscribe to an event version that shows in the graph, hover over the event and drag the arrow that appears to an application version of the same type (Solace or Kafka).

   

8. Click the application to display its information in the Details panel.
9. To update the application name, version, or description:
   1. In the Details panel click . 
   2. Update the attributes as necessary.
   3. Click Save.
10. 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.

Creating an Application in the Component View

To create an application in the component view, perform these steps:

1. Open Designer.
2. On the Application Domains page, click the application domain that you want to add the application to.
3. Click Components to switch to the component view.

4. Select the Applications tab and click Create Application.

   

5. Enter a Name for the application.
6. Select the Broker Type for the application.
7. (Optional) Add values for any application custom attributes that have been set up in your organization.
8. In the Version field, specify a semantic version value for the application in the format major.minor.patch. The default is 0.1.0.
9. (Optional) Enter a Version Name for the initial version of the application.
10. (Optional) Enter a Description for the application. The Description field supports Markdown. Click toggle preview to preview the rendered text.
11. 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 Manage 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. To declare an intent to subscribe to the event, select Sub for the version that you want the application to subscribe to.
    7. To publish the event, select Pub for the version of each event that you want the application to publish.
    8. When you are finished selecting events, click Close .
    9. If you want to create consumers for the subscribed events you selected, click Auto-Create. For more information about configuring the consumers, see Adding Consumers to Applications.
12. (Optional) If you intend to push the configuration to a Solace event broker, in the Event Flows section, select Events and click Manage Client Profile Name to set the client profile name for the application. If you don't set a client profile name, the application uses the default client profile on the event broker. Event Portal Managers can create client profile name templates that allow you to select from a list of client profile names.
13. (Optional) Add values for any application version custom attributes that have been set up in your organization.
14. Click Save Application.
15. 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 added to an environment. For more information, see Requesting Event Access.

Updating Applications

When you update an application, you can update an existing version or create a new version of the application. Versions allow you to work on updates and test new versions in development and staging environments while the stable version remains in the production environment. Each version also has a lifecycle state. For more information, see Object Versions and Lifecycle States.

The version number uses semantic versioning in the format major.minor.patch. When you update an object, you have three options:

• If the object version is in Draft state, you can update the version and retain the version number

• If the object version is in Released, Deprecated, or Retired state, you can duplicate a version and increment the version number to create a new Draft version.

• If the object version is in Released, Deprecated, or Retired state, you can create a new version of the object from scratch

If you want to update a version that is not in Draft state it is best practice to create a new version rather than returning the version to Draft state.

When you reference an object, for example, you specify the schema that an event uses or an event that an application publishes, you select the version of the object that you want to reference. If a new version of a referenced object is created, the reference does not update automatically. You can choose when to update references to the new version.

The graph view displays the most recent non-retired version of an application. If you create a new version, the new version takes the place of the previous version in the graph and the displayed event flows change if the new application version is not associated with the same event versions.

If allowed for objects in the application domain, the description of an application version can be edited at any lifecycle state. This option allows you to add information to the description at a later time, such as deprecation and retirement dates and notes about the object's functionality or runtime behavior.

Updating Applications in the Graph View

To update an application from the graph view, perform these steps:

1. On the Application Domains page, click the application domain that contains the application you want to update.
2. If you need to create a new draft version with the same properties as the existing version, right-click the application and select Duplicate.
3. To update the draft version displayed in the graph view:
1. Right-click on the application and select View Details.
2. Click Open Application.
3. Click Edit This Version.
4. Update the application version as necessary.
5. Click Save & Close.

Updating Applications in the Component View

To update an application version from the component view, perform these steps:

1. On the Application Domains page, click the application domain that contains the application you want to update.
2. Click Components to switch to the list view.
3. Select the Applications tab.
4. In the list of applications, click More Actions for the application that you want to update and select Open Application.
5. Perform one of the following actions:
• In the Versions list, click More Actions for the version that you want to update and select Edit. Any changes you make update that version of the application. You can edit an application version only if it is in Draft state.
• In the Versions list, click More Actions for the version that you want to update and select Duplicate. All properties of the existing 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.
• Above the Versions list, click Add to create a new version of the application without duplicating an existing version. By default, the new version number is the next unused major version. You can change the version number to any number not already in use.
6. Update the application version as necessary.
7. Click Save Version or Save & Close.

Changing the State of an Application Version

When you create a new version of an application, the version is in Draft state. When the version is ready, you can change the version state to Released. When you release a new version of an application, you may also want to change older versions of the application to Deprecated or Retired. You must have at least Manager level access to the application domain to change the version state of an object. For more information about version states, see Object Versions and Lifecycle States.

You can only change an application version from Draft to Released state if no event versions that the application references are in Draft state.

You can change the state of the most recent version in the graph view. If you change the state to Retired, the version disappears from the graph, and is replaced by the latest non-retired version if one exists.

To change the state of an application version from the graph view, perform these steps:

1. On the Application Domains page, click the application domain that contains the application you want to update.
2. Right-click the application and select Change State.
3. Select the new state and click Change State.

To change the state of an application version from the component view, perform these steps:

1. On the Application Domains page, click the application domain that contains the application you want to update.
2. Click Components to switch to the list view.
3. Select the Applications tab.
4. In the list of applications, click More Actions for the application that you want to update and select Open Application.
5. Select the version that you want to change the state of, then click Manage Lifecycle.
6. Select the new state.
7. (Optional) If you set the State to Deprecated or Retired, set the End of Life date. If you set a planned or actual End of Life date, the date displays in the version details.
8. Click Save.

Adding Consumers to Applications

When you create an application, you specify the events in Event Portal that the application intends to publish and subscribe to. For events that the application subscribes to, to fully configure the application in your modeled event mesh, you must also create a consumer in the application and specify the topic subscription. If you plan to use Event Portal to push consumer configurations to the runtime, you also need to specify configuration details for the consumer. For more information, see Adding a Queue to an Application in Designer.

To configure a consumer in an application, perform these steps:

1. On the Application Domains page, click the application domain that contains the application you want to update, then click Components to switch to the list view.
2. In the list of applications, click the name of the application you want to update.
3. Select the draft version you want to update and click Edit This Version. If you need to create a new draft version to edit with the same properties as the existing version, right-click the application and select Duplicate.
4. In the Event Flows section, select Events and verify that you have declared the intent to subscribe to the event you want to create a consumer for.

   

5. In the Event Flows section, select Runtime Configuration and perform one of the following steps:
   • If you have declared the events the application intends to subscribe to, but have not yet created any consumers, click Auto-Create. Event Portal creates consumers for all subscribed events. For Solace applications, the consumers are Solace Event Queues.
   • If you already used auto-create to create consumers, scroll to the consumer you want to update. The consumer name is based on the event name.
   • If you want to add a new consumer to the list of consumers, click Add Consumer.
6. For each consumer that you want to configure, perform the following steps:
1. Add or update a Name for the consumer.
2. Select the consumer Type. The options available depend on the selected Broker Type for the application.

3. To add a topic subscription to the consumer, click Add Subscriptions and enter the topic for the consumer to subscribe to. You can select a topic address for a declared subscribed event to create a subscription, or you can type a topic address. If the topic address includes an enumeration variable, you can use the wildcard to subscribe to all values, or you can select one or more values to subscribe to.

   You can use * and > as wildcard characters to subscribe to a group of related topics. You can add more than one subscription to a consumer. For more information, see Topic Addresses.

   When you enter a topic subscription, a Preview of Attracted Events shows all event versions with a matching topic address that are published by an application version that has been added to at least one modeled event mesh.

4. (Optional) If you set the Type to Solace Event Queue, click Manage Configuration to include configuration details for the queue. For more information, see Configuring Event Brokers in Event Portal.

Event Portal Managers can create Solace queue templates that help you set the queue configuration properties. Using a template may be required for applications in some environments.

If the application has one or more consumers that attract events that you have not declared an intent to subscribe to, a list of Additional Attracted Events by Consumer Subscriptions displays below the consumers. You may need to declare additional events, or you may have consumer subscriptions with wildcards that attract more events than you intended. Review your subscriptions to make sure they behave as expected.

Downloading a Consumer Queue Configuration

If you specified an event queue configuration for a consumer, you can download the configuration as a JSON file.

To download the queue configuration, perform these steps:

1. On the Application Domains page, click the application domain that contains the application you want to update.
2. Right-click the application in the graph view and select View Details.
3. Click Open Application.
4. In the Versions list, click More Actions next to the version that you want to download the queue configuration for, then select Edit.
5. In the Event Flows section of the application, select Consumers.
6. In the Consumer Details section for a Solace Event Queue, click Download above the Configuration field.

Adding Applications to Environments

Environments in PubSub+ Cloud represent the operational environments within your organization. In Event Portal you create modeled event meshes within environments to represent event flows through one or more operational event brokers. When you add an application to an environment, you promote a version of the application to a model event broker in a modeled event mesh. For more information about environments, see Creating and Managing Environments.

You should be aware of the following considerations when you add application versions to environments:

Environment Considerations

• You must have at least Editor level access to both the application domain for the application and the environment.

• The environment must have at least one modeled event mesh of the same type as the application (Solace or Kafka) and the modeled event mesh must have at least one model event broker. For more information about adding and updating modeled event meshes, see Designing Modeled Event Meshes.

• If an application references an event that requires approval, a banner appears on the application details page. All event access requests must be approved before the application can be added to an environment. For more information, see Requesting Event Access.

• Only one version of an application can be associated with an event broker. If you add a new version of an application to a model event broker while another version is associated with it, the previously added version is replaced with the new version. You can revert to a previous version of an application in an environment by re-adding it.

• You can add application versions to more than one model event broker. For example, you may have a released version of an application in a production environment and an updated draft version in two different model event brokers in a development environment.

• You can add application versions in any lifecycle state to an environment.

• When you add an application to an environment, if there are any discrepancies between the declared event versions that the application intends to subscribe to and the events attracted by consumer subscriptions set up for the application, or if no application in the environment publishes a declared subscribed event, a message displays and allows you to view the list of discrepancies. You don't need to fix the discrepancies to add the application to the environment. After you add the application, you can view any discrepancies in Runtime Event Manager. For more information, see Fixing Event Flow Discrepancies.

Runtime Configuration Considerations

The following considerations apply when you have enabled runtime configuration and you are using Event Portal to configure endpoints and clients on event brokers.

• When you add an application to a model event broker that is connected to an operational event broker, queue configuration, ACL profiles, and client username credentials are pushed to the operational event broker. For more information about the application details sent, see How Application Settings are Applied to Event Brokers.

• Your Middleware Integration team must still configure the event broker, including client profiles, management and messaging authentication, uploading certificates, and other settings that apply to the event broker or Message VPN. You only configure settings for endpoints and clients from Event Portal.

• You need to specify the authorization type used by the event broker for messaging access and the credential details for the client application. The authentication type your application uses for messaging (basic authentication, LDAP group, OAuth group, or certificate-based) should already be configured on the event broker. For more information about configuring authentication for event broker services, see Configuring Authentication for Messaging Clients.

  Solace recommends following best security practices for event broker access and authentication and disabling basic authentication for messaging access to the Message VPN if you have a more secure method configured.

• If using a Solace queue template is required for the environment, you must use an allowed template for all queue configurations to be able to add the application to the environment. The runtime tab displays a warning for environments that are incompatible for this reason. For more information about Solace queue templates, see Creating Solace Queue Templates.

• If a client profile name template is required for the environment, you must use an allowed template for the client profile name to be able to add the application to the environment. The runtime tab displays a warning for environments that are incompatible for this reason. For more information about client profile name templates, see Creating Client Profile Name Templates.

• Environments may not have runtime configuration enabled for several reasons:

  • Your organization's security policies don't allow a direct connection between Event Portal and your event brokers.
  • You are using Kafka event brokers or Solace event broker versions that don't support configuration from Event Portal.
  • You use the environment for an early stage in the design process when you're not ready to promote applications to operational event brokers.

Adding an Application Version to an Environment

To add an application to an environment, 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 application detail panel that appears, click Open Application.
4. On the Application page, select the Runtime tab.
5. In the Version list, select the version of the application that you want to add.
6. In the Event Brokers list, select the event broker that you want to add the application to. If another version of the application is already associated with the event broker, the version you selected replaces the currently associated version on the event broker.
7. Click Add Application.
8. If runtime configuration is enabled for the environment and the client credentials for the application have not been specified, the Add to Environment dialog prompts you to provide them. These settings specify the authentication method the runtime client application uses to connect to the event broker to send and receive messages. To enter the credential information, do the following:
   1. Select the Access Type. You can select Basic, Authorization Group, or Client Certificate.
   2. If you selected Basic authentication, specify the Client Username and Password.
      • If the Client Username already exists on the event broker, configuration details for the application can update the client on the event broker. 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 authentication, specify the Authorization Group Name and Client Username.
      • The Authorization Group Name is the name for the LDAP or OAuth authorization group.
      • If the Client Username already exists on the event broker, configuration details for the application can update the client on the event broker.
   4. If you selected Client Certificate authentication, specify the Client Username.
      • The Client Username should match the certificate Common Name for the application's certificate. You do not upload certificates to the event broker from Event Portal.
   5. Click Save Credentials and Continue.
9. In the Add to Environment dialog, click Add.
10. (Optional) If there is a mismatch between a declared event version that the application intends to subscribe to and the consumers set up for the application, or if no application in the environment publishes a declared subscribed event, click View Mismatches and perform one of the following steps:
    • Click Edit Application to open the application version in a new tab and fix one or more of the discrepancies. For more information, see Fixing Event Flow Discrepancies.
    • Click Close to return to the Add to Environment dialog box and fix the discrepancy later.
11. Click Add.

12. Event Portal adds the application version to the event broker and displays the details.



If runtime configuration is enabled and fully set up, the client username and any ACL profile and queue configuration details are pushed to the operational event broker. The client username on the event broker is automatically associated with the specified client profile and an ACL profile based on the credentials set in Designer.

The Runtime tab displays an error when runtime configuration is enabled, but the model event broker does not have a connection to an operational event broker. If this error is expected because you have not yet established a connection between Event Portal and the event broker, you can ignore the error. For more information about setting up runtime configuration, see Setting Up Event Broker Configuration.

Fixing Event Flow Discrepancies

If Event Portal detects discrepancies in the event flows, the Add to Environment dialog box displays a message. You can choose to display the discrepancies and fix them if necessary. For more information, see Adding Applications to Environments.

The list of discrepancies can help you verify that the consumers set up for the application are set up correctly to behave according to your expectations. You can correct discrepancies before adding the application to the environment, but it is not required. The following table describes the discrepancies and potential resolutions.

Discrepancy	Description	Resolutions
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.	Add a new subscription to an existing consumer or add a new consumer to the application that subscribes to the event version, or remove the event version from the list of declared events the application intends to subscribe to.
Not Published in Environment	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.
Different 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
Additional Attracted Event Version	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.	Update the application version to declare the intent to subscribe to the event version, or 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.
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.

Managing Runtime Associations for Applications

On the application Runtime tab you can perform several tasks, including:

• Filtering the Event Broker List
• Viewing Modeled Event Mesh and Connection Details
• Updating Credentials for an Event Broker
• Removing an Application From an Environment
• Downloading an AsyncAPI Document for an Application

Filtering the Event Broker List

You can filter the list of event brokers on the Runtime tab to view the event brokers that an application can be added to or that an application or specific version has already been added to.

To filter the list of event brokers, perform these steps:

1. On the Runtime tab for an application, select an option from the Filter by version list:
   • All Application Versions—displays all model event brokers that any version of the application has been added to.
   • Version number—displays all model event brokers that the selected version of the application has been added to.
   • No Version Added— displays all model event brokers that no version of the application has been added to.
2. Clear the Hide incompatible environments checkbox to display environments that have configuration template requirements that no version of the application meets, or that the version selected in the Filter by version list does not meet.

Viewing Modeled Event Mesh and Connection Details

You can open the modeled event mesh and event broker connection details in Runtime Event Manager from the event broker list on the Runtime tab.

To view modeled event mesh and event broker connection details, perform these steps:

1. On the Runtime tab for an application, click More Actions for the event broker that you want to set the credentials for.
2. Select one of the following options:
   • Click Open Event Broker Connections to open Runtime Event Manager to the Event Broker Connection tab for the modeled event mesh.
   • Click Open Modeled Event Mesh to open Runtime Event Manager to the Architecture tab for the modeled event mesh.

Updating Credentials for an Event Broker

When you add an application to an event broker in an environment that has runtime configuration enabled, you must set the client username and the event broker credentials for the client application if they have not already been set. You can update the username and credentials on the Runtime tab. For security reasons, you can't retrieve a previously set password.

To update event broker credentials for a client application, perform these steps:

1. On the Runtime tab for an application, click More Actions for the event broker that you want to set the credentials for and select Manage Credentials.
2. Enter the client credentials. These credentials allow the client application in the runtime to authorize with the event broker to send and receive event messages. To enter the credential information, do the following:
   1. Select the Access Type. You can select Basic, Authorization Group, or Client Certificate.
   2. If you selected Basic authentication, specify the Client Username and Password.
      • If the Client Username already exists on the event broker, configuration details for the application can update the client on the event broker.
      • The Password can be a maximum of 128 characters and can't include the following characters: : ( ) " ; ' < > , ` \ & |
   3. If you selected Authorization Group authentication, specify the Authorization Group Name and Client Username.
      • The Authorization Group Name is the name for the LDAP or OAuth authorization group.
      • If the Client Username already exists on the event broker, configuration details for the application can update the client on the event broker.
   4. If you selected Client Certificate authentication, specify the Client Username.
      • The Client Username should match the certificate Common Name for the application's certificate. You do not upload certificates to the event broker from Event Portal.
   5. Click Save Credentials and Continue.
3. Click Save.

Removing an Application From an Environment

You can remove an application version from a modeled event broker if it is no longer needed. Only one version of an application can be associated with a model event broker. If you add a new version of an application, the previously associated version is automatically removed. You don't need to remove it manually.

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

1. On the Runtime tab for an application, click More Actions for the event broker that you want to set the credentials for and select Remove Application.
2. Click Remove.

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

You can download the document from the Details tab or the Runtime tab. If you download the document from the Runtime tab the document always includes server details for the event broker.

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 application detail panel that appears, click Open Application.
4. In the Versions list, select the version that you want to download the AsyncAPI document for.
5. In the version details, click More Actions and select Download Async API.

   Alternatively, select the Runtime tab for the application, 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 Details tab 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 Runtime tab, 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.