Applications

An application represents a program, process, microservice, IoT device, integration component, or other runnable consumer, producer, or processor of events that interacts with an event broker.

You can create new applications in Designer and you can add applications to Designer by importing Solace queues and Kafka consumer groups from your runtime data in Runtime Event Manager. For more information on importing applications, see Importing Runtime Objects into Event Portal

This section includes the following tasks:

Creating an Application in Designer
Updating an Application
Changing the State of an Application Version
Adding an Application to an Environment
Downloading an AsyncAPI Document for an Application
Specifying Queue Configuration for a Solace Event Broker

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

You can also move applications to a different application domain. For more information, see Moving Objects Between Application Domains.

Creating an Application in Designer

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

name
broker type
version display name, number, and state for each version
event flows

When you model event flows for an application you can use the following options:

Specify events that the application intends to subscribe to.

This option is most useful early in the design process when you may not be ready to specify topic addresses or consumer details but you want to specify the intent of an application to consume a particular event. Identifying the intent can be 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 to remind you that you still need to configure a consumer to attract the event.
- It enables Event Portal to provide suggestions to help you create the consumer and topic subscription when you are ready to do so.
- It includes the application when calculating the event reuse index in KPI Dashboard.
Specify the consumers, such as event queues, direct clients, and Kafka consumer groups, that subscribe to the event in the runtime. You can specify three types of consumers:
- Event Queue—an endpoint on a Solace event broker that attracts Guaranteed messages with topic subscriptions. You have the option to specify configuration details for the queue in Designer. For information, see Specifying Queue Configuration for a Solace Event Broker.
- Direct Client—a direct connection to a Solace event broker that attracts Direct messages with topic subscriptions but does not store messages while the consumer is offline or reconnecting
- Consumer—a consumer group in a Kafka cluster that subscribes to topics
Specify events that the application publishes to be consumed by other applications.

To create an application in Designer, perform these steps:

On the Application Domains page, click the application domain that you want to add the application to.
Click Components to switch to the list view.
Select the Applications tab and click Create Application.
Enter a Name for the application.
Select the Broker Type for the application.
In the Version field, specify a semantic version value for the application in the format major.minor.patch. The default is 0.1.0.
(Optional) Enter a Version Name for the initial version of the application.
(Optional) Enter a Description for the application. The Description field supports Markdown. Click toggle preview to preview the rendered text.
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 for an event that you want the application to publish or subscribe to. By default, the list shows events from the current application domain. If you select a different application domain or remove the filter, the list also shows shared events in selected application domain or in all application domains that you have access to.
4. Expand an event to see the list of event versions.
5. Select Sub for a version of each event that you want the application to subscribe to.
6. Select Pub for a version of each event that you want the application to publish.
7. When you are finished selecting events, click Close .
To specify a consumer that the application receives events from, perform these steps:
1. In the Event Flows section, select Consumers.
2. Click Add Consumer.
3. Type a Name for the consumer.
4. Select a consumer type. The options available depend on the selected Broker Type.
5. (Optional) If you set the Type to Solace Event Queue, enter Configuration details for the queue. For more information, see Specifying Queue Configuration for a Solace Event Broker.
  - Click Set to default to add default queue settings.
  - If you use the default settings, you must add a name for the queue, for example: "queueName": "Product",.For ease of management, you may want to use the same name for the consumer in the application and the queue it represents on the event broker.
  - After you set the configuration, clicking Reset to Default removes any customizations.
6. To add a topic subscription to the consumer, click Add Subscription. You can add more than one subscription to a consumer.
7. Enter a topic subscription for the consumer to subscribe to. You can use * and > as wildcard characters to subscribe to a group of related topics. For more information, see Topic Subscriptions. 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.
8. Repeat steps b to f for every consumer that you want to add.
(Optional) Add values for any custom attributes that have been set up in your organization.
Click Save Application.

Updating an Application

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. You can only edit versions that are in Draft 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 an existing 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, you can choose when to update references to the new version.

To update an application, perform these steps:

On the Application Domains page, click the application domain that contains the application you want to update.
Click Components to switch to the list view.
Select the Applications tab.
In the list of applications, click More Actionsfor the application that you want to update and select Open Application.
Perform one of the following actions:

In the Versions list, click More Actionsfor 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 Actionsfor 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 Addto 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.

Update the application version as necessary.
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 the Event Portal User role with Manager level access to the application domain to change the version state. For more information about version states, see Object Versions and Lifecycle States.

You can only change an application version from Draft to Released state after all event versions that the application references have been changed out of Draft state.

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

On the Application Domains page, click the application domain that contains the application you want to update.
Click Components to switch to the list view.
Select the Applications tab.
In the list of applications, click More Actionsfor the application that you want to update and select Open Application.
Select the version that you want to change the state of then click Change State.
Select the new state and click Change State.

Adding an Application to an Environment

When a version of an application is ready to include in a modeled event mesh, you add the application version to an environment from Designer. When you add an application version to an environment, you choose the environment and modeled event mesh and then select one or more event brokers in the modeled event mesh to associate the application version with.

When you import an application into Event Portal using Runtime Event Manager, you select the environment, modeled event mesh, and event broker. You can add the imported application to additional environments from Designer.

After you add an application version to a modeled event mesh, you can view the application and its associated events in Runtime Event Manager. You can add the same application version to more than one environment or add different versions of an application to different environments. For example, you may have a production version of an application in a modeled event mesh in one environment and an updated draft version ready for testing in two modeled event meshes in another environment.

Before you add an application to an environment, the environment must have at lease one modeled event mesh of the same type as the application and you must have added at least one event broker to the modeled event mesh.

To add an application version to an environment:

On the Application Domains page, click the application domain that contains the application you want to update.
Click Components to switch to list view.
Select the Applications tab.
Select the application.
In the Versions list, select the version that you want to add to an environment
In the Application Details pane, click More Actions, then select Add to Environment.
Select the Environment that contains the modeled event mesh that you want to add the application version to.
Select a modeled event mesh from the Modeled Event Mesh list.
Select one or more Event Brokers to associate the application with.
Click Add.

After you add the application version, you can view it in the modeled event mesh in Runtime Event Manager.

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

You can download an AsyncAPI document for an application with or without server details and operation bindings for any model event brokers that the application is associated with in an environment.

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

On the Application Domains page, click the name of the application domain that contains the application.
Click Components to switch to the list view.
Select the Applications tab.
In the list of applications, click the name of the application.
In the Versions list, select the version that you want to download the AsyncAPI document for.
In the version details, click More Actions and select Download Async API.
If you want to include server details and operation bindings for an event broker that you have associated the application with, select the event broker from the Event Broker drop-down list.
(Optional) If you selected an event broker, select Include both attracted and designed events to include events that are specified by both the pub/sub and consumer event flows.

If you select an event broker but don't select this option, only events attracted by a consumer topic subscription are included in the AsyncAPI file.

If you don't select an event broker, this setting is not available and only events that have a publish or subscribe event flow specified in Designer are included in the AsyncAPI file.
Select JSON or YAML file format.
Click Download File.

Specifying Queue Configuration for a Solace Event Broker

If you add a Solace event queue as a consumer in your application, you have the option to specify configuration details for the queue in JSON format. At this time you can download the configuration details to help you configure a queue on a runtime Solace event broker. Future updates will enable sending this queue configuration to event broker services managed in the same PubSub+ Cloud account.

For more information about configuring queues on event brokers in PubSub+ Cloud, see Configuring Queues.

Default Queue Configuration

If you choose to set the event queue configuration, you can start with the default values. The default values added in Event Portal represent the default values of the required settings for a queue on a Solace event broker.

The JSON default settings are:

{
  "queueName": "consumer_name",
  "accessType": "exclusive",
  "maxMsgSpoolUsage": 5000
}

Event Portal validates that the configuration is in proper JSON format, so you must add a name for the queue, for example: "queueName": "Product". For ease of management, you may want to use the same name for the consumer in the application and the queue it represents on the event broker.

Queue Configuration Properties

Your JSON queue configuration can include the following parameters. For more information, see SEMP API queue parameters.

Property	Description
`accessType` (included in default configuration)	Specifies how messages are delivered when multiple consumer flows are bound to the queue. The default value is `exclusive`. `Exclusive` specifies that only one consumer can receive a message at any one time, while additional consumers may be connected as standby. Only the first consumer to bind can receive messages. If the first consumer disconnects, the second consumer receives data, and so on. Exclusive queues always deliver messages in the order they are received. `Non-Exclusive` specifies that multiple consumers can bind to the queue, which enables load balancing and consumer auto-scaling. A non-exclusive queue can be non-partitioned or partitioned. For a non-partitioned queue (`partitionCount` is `0`), each consumer is serviced in a round-robin fashion. If a connection fails, unacknowledged messages are delivered to another consumer with the re-delivered flag set. In this way, messages can be delivered to consumers out of order. For a partitioned queue (`partitionCount` is greater than `0`), each consumer is delivered messages from one or more partitions. Messages are mapped to partitions based on a hash of the partition key, which is set by the publishing application. Message order is maintained within a partition, but not between partitions.
`consumerAckPropagationEnabled`	Enables or disables the propagation of consumer acknowledgments (ACKs) received on the active replication Message VPN to the standby replication Message VPN. The default value is `true`.
`deadMsgQueue`	Specifies the name of the dead message queue (DMQ) used by the queue.
`deliveryCountEnabled`	Enables or disables the ability for client applications to query the message delivery count of messages received from the queue. This is a controlled availability feature. Please contact support to find out if this feature is supported for your use case. The default value is `false`.
`deliveryDelay`	Specifies the delay, in seconds, to apply to messages arriving on the queue before the messages are eligible for delivery. The default value is `0`.
`eventBindCountThreshold`	Specifies event bind count thresholds for the queue: `clearPercent`—the clear threshold for the value of this counter as a percentage of its maximum value. Falling below this value will trigger a corresponding event `clearValue`—the clear threshold for the absolute value of this counter. Falling below this value will trigger a corresponding event. `setPercent` —the set threshold for the value of this counter as a percentage of its maximum value. Exceeding this value will trigger a corresponding event. `setValue`—the set threshold for the absolute value of this counter. Exceeding this value will trigger a corresponding event.
`eventMsgSpoolUsageThreshold`	Specifies message spool usage thresholds for the queue: `clearPercent`—the clear threshold for the value of this counter as a percentage of its maximum value. Falling below this value will trigger a corresponding event `clearValue`—the clear threshold for the absolute value of this counter. Falling below this value will trigger a corresponding event. `setPercent` —the set threshold for the value of this counter as a percentage of its maximum value. Exceeding this value will trigger a corresponding event. `setValue`—the set threshold for the absolute value of this counter. Exceeding this value will trigger a corresponding event.
eventRejectLowPriorityMsgLimitThreshold	Specifies message spool usage thresholds for the queue: `clearPercent`—the clear threshold for the value of this counter as a percentage of its maximum value. Falling below this value will trigger a corresponding event `clearValue`—the clear threshold for the absolute value of this counter. Falling below this value will trigger a corresponding event. `setPercent` —the set threshold for the value of this counter as a percentage of its maximum value. Exceeding this value will trigger a corresponding event. `setValue`—the set threshold for the absolute value of this counter. Exceeding this value will trigger a corresponding event.
`maxBindCount`	Specifies the maximum number of consumer flows that can bind to the queue. The default value is `1000`.
`maxDeliveredUnackedMsgsPerFlow`	Specifies the maximum number of messages delivered but not acknowledged per flow for the queue. The default value is `10000`.
`maxMsgSize`	Specifies he maximum message size allowed in the queue, in bytes. The default value is `10000000`.
`maxMsgSpoolUsage` (included in default configuration)	Specifies the maximum message spool usage allowed by the queue, in megabytes. A value of `0` only allows spooling of the last message received and disables quota checking. The default value is `5000`.
`maxRedeliveryCount`	Specifies the maximum number of times the queue will attempt redelivery of a message prior to it being discarded or moved to the DMQ. A value of `0` means to retry forever. The default value is `0`.
`maxTtl`	Specifies the maximum time, in seconds, a message can stay in the queue when `respectTtlEnabled` is `true`. A message expires when the lesser of the sender assigned time-to-live (TTL) in the message and the `maxTtl` configured for the queue, is exceeded. A value of `0` disables expiry. The default value is `0`.
`msgVpnName`	Specifies the name of the Message VPN hosting the queue.
`owner`	Specifies the client username that owns the queue. The queue owner has full unlimited permissions for the queue. The owner can consume, delete, or modify topics in the queue. By default, users with access to PubSub+ Broker Manager have ownership privileges. You can also give ownership to client applications.
`partitionCount`	Specifies the count of partitions of the queue. This setting is only relevant for queues with an access type of non-exclusive. When set to `0`, bound clients receive messages in a round-robin fashion. Otherwise, bound clients receive messages from individually assigned partitions. The default value is `0`.
`partitionRebalanceDelay`	Specifies the delay, in seconds, before a partition rebalance is started once needed. The default value is `5`.
`partitionRebalanceMaxHandoffTime`	Specifies the maximum time, in seconds to wait before handing off a partition while rebalancing. The default value is `3`.
`permission`	Specifies the access level given to client applications other than the queue owner. The default value is `consume`. Possible values are: `no-access`—Disallows all access. `read-only`—Clients have read-only access to messages spooled to the queue. `consume`—Clients can consume and delete messages from the queue. `modify-topic`—Clients can consume and delete messages and modify the topic or selector assigned to the queue. `delete`—Clients can consume and delete messages, modify the topic or selector assigned to the queue, and delete the queue.
`queueName` (included in default configuration)	Specifies the name of the queue.
`redeliveryDelayEnabled`	Enables or disables a message redelivery delay. When `false`, messages are redelivered as soon as possible. When `true`, messages are redelivered according to the initial, max, and multiplier. The default value is `false`.
`redeliveryDelayInitialInterval`	Specifies the delay to be used between the first two redelivery attempts, in milliseconds. The default value is `1000`.
`redeliveryDelayMaxInterval`	Specifies the maximum delay to be used between any two redelivery attempts, in milliseconds. The default value is `64000`.
`redeliveryDelayMultiplier`	Specifies the amount each delay interval is multiplied by after each failed delivery attempt. This number is in a fixed-point decimal format in which you must divide by 100 to get the floating point value. For example, a value of `125` would cause the delay to be multiplied by 1.25. The default value is `200`.
`redeliveryEnabled`	Enables or disables message redelivery. When enabled, the number of redelivery attempts is controlled by `maxRedeliveryCount`. When disabled, the message will never be delivered from the queue more than once. The default value is `true`.
`rejectLowPriorityMsgEnabled`	Enables or disables the checking of low priority messages against the `rejectLowPriorityMsgLimit`. This can be enabled only if `rejectMsgToSenderOnDiscardBehavior` does not have a value of `never`. The default value is `false`.
`rejectLowPriorityMsgLimit`	Specifies the number of messages of any priority in the queue above which low priority messages are not admitted but higher priority messages are allowed. The default value is `0`.
`rejectMsgToSenderOnDiscardBehavior`	Specifies when to return negative acknowledgments (NACKs) to sending clients on message discards. Note that NACKs cause the message to not be delivered to any destination and Transacted Session commits to fail. The default value is `when-queue-enabled`. Possible values are: `never`—Silently discard messages `when-queue-enabled`—NACK each message discard back to the client, except messages that are discarded because an endpoint is administratively disabled `always`—NACK each message discard back to the client, including messages that are discarded because an endpoint is administratively disabled
`respectMsgPriorityEnabled`	Enables or disables the respecting of message priority. When enabled, messages contained in the queue are delivered in priority order. The default value is `false`.
`respectTtlEnabled`	Enables or disables the respecting of the time-to-live (TTL) for messages in the queue. When enabled, expired messages are discarded or moved to the DMQ. The default value is `false`.

Downloading a Queue Configuration

You can download the queue configuration as a JSON file.

To download the configuration for a queue:

In the Event Flows section of an application, select Consumers.
In the Consumer Details section for a Solace Event Queue, click Download above the Configuration field.

Provide feedback