Configuring Event Brokers in Event Portal

You can configure client details and queues for a Solace event broker in Designer and use the configuration to add, update, and delete client credentials and queues on Solace event brokers. For information about configuring queues on event brokers using Cluster Manager, see Configuring Queues.

This page includes the following information:

• Setting Up Event Broker Configuration
• How Application Settings are Applied to Event Brokers
• Adding a Queue to an Application in Designer
• Sending Configuration Updates to an Event Broker

Setting Up Event Broker Configuration

To manage event broker configuration from Event Portal, you must complete several set-up steps.

1. Make sure that your operational event brokers support configuration management from Event Portal. The event brokers must be PubSub+ Cloud event broker services or Solace software event brokers or appliances running version 10.5 or later. For more information about creating an event broker service in PubSub+ Cloud, see Creating Event Broker Services.

2. Configure a connection between Event Portal and your operational event brokers in the runtime by setting up an Event Management Agent in Scan from Event Portal mode. See Setting Up Event Management Agent Connections.

3. Enable runtime configuration for the environments containing the model event brokers that represent the operational event brokers you want to configure from Event Portal. For more information, see Creating and Managing Environments.

4. (Optional) Create Solace queue templates to define the queue configuration values you require on your event brokers. You can make using templates required in one or more environments and specify which templates are allowed in those environments.

5. (Optional) If client profiles are configured on the operational event broker, create client profile name templates so developers can select the correct client profile for the application in Designer. For more information about client profiles in PubSub+ Cloud, see Creating a Client Profile. You can make using templates required in one or more environments and specify which templates are allowed in those environment.

How Application Settings are Applied to Event Brokers

The following diagram shows how the events, consumers, and client details you add to an application relate to your runtime when you set up PubSub+ Cloud to configure event broker services from Event Portal.

1. In an application in Event Portal, you can specify events that the application publishes and consumers that subscribe to events. A consumer in the application represents a queue on the event broker that the runtime client application can bind to in order to consume messages from the queue. You can also specify the name of the client profile on the event broker that defines the ACL profiles and other settings that are applied to the runtime client application when it connects to the event broker.

2. When you add the application to an environment in Event Portal, you must also specify the client username and the credentials for basic authentication or group authorization that the runtime application uses to connect to the event broker and bind to the queue. Optionally, you can download an AsyncAPI document from the application that includes the event broker connection and authentication details to give to the application developer who is creating the runtime client application.

3. When Event Portal sends the configuration to the operational event broker, the following updates can occur on the event broker.

   • A queue is created or updated on the event broker for each Solace queue consumer with the properties and topic subscriptions specified by the queue configuration in Designer. If a queue with the same queue name already exists, the updates are applied to the existing queue.

   • The event broker is configured to apply the specified client profile for the client application when it connects to the event broker using the specifed username and credentials. If no client profile name is set, the application uses the default client profile on the event broker.

4. An application developer creates or updates a runtime client application to use the authentication credentials specified in Event Portal. When the client application authenticates with the operational event broker

   • it is assigned the client profile specified in Designer

   • it can bind to the queue that was configured in Designer and consume any event messages attracted by the topic subscriptions for the queue.

Adding a Queue to an Application in Designer

To add a Solace event queue that can be configured on an event broker to an application in Designer, 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 add queue configuration to, then select Edit. If the application doesn’t have a version in Draft state, create a new version.
5. In the Event Flows section, select Runtime Configuration.
6. (Optional) To set the client profile used by the application, perform these steps:
   1. Click Manage Client Profile Name.
   2. If client profile name templates have been set up in Runtime Event Manager, select a client profile name from the Template list, or click Customize Name to type the name of a profile that has been set up on the operational event broker.
   3. If no client profile name templates have been set up, type a client profile name in the Client Profile Name field.
   4. Click Apply.

   If you don't set a client profile name, the operational event broker uses the default client profile for the application.

7. Click Add Consumer.
8. Type a Name for the consumer.
9. In the Type list, select Solace Event Queue.
10. To add a topic subscription to the consumer, perform these steps:
    1. Click Add Subscriptions to add a topic subscription to the consumer.
    2. Enter the topic subscription. 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 in Designer that are published by an application version that has been added to at least one modeled event mesh.
    3. Click Add Subscription.
    4. When you are finished adding subscriptions, click Close .
11. To add queue configuration details to a consumer, perform these steps:
    1. Click Manage Configuration.
    2. (Optional) If Solace queue templates have been set up in Runtime Event Manager, select a configuration from the Template list.
    3. If you want to conform to the template, enter values for the queue in the available fields. The fields available and the allowable values are defined in the template. The Queue Name field is always required. If the queue you are configuring already exists on the event broker service, the "queueName" in the consumer and on the event broker service must match. Otherwise, sending the configuration details to the event broker service creates a new queue.
    4. If you want to enter custom configuration details instead of following the template, click Customize Configuration and add the necessary details.
    5. (Optional) Select Full Configuration and review the configuration sent to the event broker. The configuration may include properties with required values that can't be set in the consumer.
    6. Click Apply.
12. Click Save Version.

Queue Configuration Properties

The JSON queue configuration for the consumer can include the following properties. Some of these properties are not supported by earlier event broker versions. For more information, see SEMP API queue parameters.

Property	Description
accessType Access Type (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 Consumer Acknowledgment Propagation	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 DMQ Name	Specifies the name of the dead message queue (DMQ) used by this queue. The default is #DEAD_MSG_QUEUE. Solace recommends using a separate DMQ for each queue and topic endpoint that needs one and setting the DMQ name to the name of the queue, followed by "_dmq", For example if a queue named MyQueue needs a DMQ, the DMQ should be named MyQueue_dmq. For more information about configuring a DMQ, see Adding a Dead Message Queue to an Application. A DMQ collects undelivered messages that would otherwise be discarded from the queue because the Maximum TTL or Maximum Redelivery Count has been reached.
deliveryCountEnabled Enable Client Delivery Count	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 Delivery Delay	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 Maximum Consumer Count Alert Thresholds	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 Messages Queued Quota Alert Thresholds	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 Reject Low Priority Messages Alert Thresholds	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 Maximum Consumer Count	Specifies the maximum number of consumer flows that can bind to the queue. The default value is 1000.
maxDeliveredUnackedMsgsPerFlow Maximum Delivered Unacknowledged Messages per Flow	Specifies the maximum number of messages delivered but not acknowledged per flow for the queue. The default value is 10000.
maxMsgSize Maximum Message Size	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 Maximum Redelivery Count	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 try forever. The default value is 0.
maxTtl Maximum TTL	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. Expired messages are discarded or moved to a DMQ. A value of 0 disables expiry. The default value is 0.
msgVpnName	Specifies the name of the Message VPN hosting the queue. This property is not necessary for PubSub+ Cloud event broker services. Solace software event brokers and appliances can have multiple Message VPNs.
owner Owner	Specifies the client username that owns the queue. By default, users with access to PubSub+ Broker Manager have ownership privileges. Use this parameter to give ownership to the client application.The queue owner has full unlimited permissions for the queue. The owner can consume, delete, or modify topics in the queue.
partitionCount Count	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 Rebalance Delay	Specifies the delay, in seconds, before a partition rebalance is started once needed. The default value is 5.
partitionRebalanceMaxHandoffTime Rebalance Max Handoff Time	Specifies the maximum time, in seconds to wait before handing off a partition while rebalancing. The default value is 3.
permission Non-Owner 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 Queue Name (included in default configuration)	Specifies the name of the queue. This property is required.
redeliveryDelayEnabled Delayed Redelivery	1 Enables or disables message redelivery. When enabled, the number of redelivery attempts is controlled by maxRedeliveryCount and undelivered messages are discarded or moved to the DMQ after the specified number of attempts is reached. When disabled, the queue never attempts message delivery more than once. The default value is true.
redeliveryDelayInitialInterval Initial Delay	Specifies the delay to be used between the first two redelivery attempts, in milliseconds. The default value is 1000.
redeliveryDelayMaxInterval Maximum Delay	Specifies the maximum delay to be used between any two redelivery attempts, in milliseconds. The default value is 64000.
redeliveryDelayMultiplier Multiplier	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 Redelivery	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 Reject Low Priority Messages	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 Reject Low Priority Messages Limit	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 Reject Messages to Sender on Discard	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 Respect Message Priority	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 Respect TTL	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.

Queue Configuration Example

The following JSON queue configuration example creates a queue on the event broker named samplequeue with default values for all properties.

{
	"queueName" : "samplequeue",
	"accessType" : "exclusive",
	"consumerAckPropagationEnabled" : true,
	"deadMsgQueue" : "#DEAD_MSG_QUEUE",
	"deliveryCountEnabled" : false,
	"deliveryDelay" : 0,
	"eventBindCountThreshold": {
		"clearPercent": 60,	
		"setPercent": 80
	},
	"eventMsgSpoolUsageThreshold": {
		"clearPercent": 18,
		"setPercent": 25
	},
	"eventRejectLowPriorityMsgLimitThreshold": {
		"clearPercent": 60,
		"setPercent": 80
	},
	"maxBindCount": 1000,
	"maxDeliveredUnackedMsgsPerFlow": 10000,
	"maxMsgSize": 10000000,
	"maxMsgSpoolUsage": 5000,
	"maxRedeliveryCount": 0,
	"maxTtl": 0,
	"partitionCount": 0,
	"partitionRebalanceDelay": 5,
	"partitionRebalanceMaxHandoffTime": 3,
	"redeliveryDelayEnabled": false,
	"redeliveryDelayInitialInterval": 1000,
	"redeliveryDelayMaxInterval": 64000,
	"redeliveryDelayMultiplier": 200,
	"redeliveryEnabled": true,
	"rejectLowPriorityMsgEnabled": false,
	"rejectLowPriorityMsgLimit": 0,
	"rejectMsgToSenderOnDiscardBehavior": "when-queue-enabled",
	"respectMsgPriorityEnabled": false,
	"respectTtlEnabled": false
}

Adding a Dead Message Queue to an Application

You can configure a dead message queue (DMQ) to receive messages that are discarded from a queue when they can't be delivered to the subscribing client. By default, messages are discarded from a queue in the following circumstances:

• the maximum time-to-live (TTL) value for the message has been reached and the queue is configured to respect message TTL expiry times.

• the number of redelivery attempts to the consumer for a message has reached the max redelivery count value for the original endpoint.

You can configure a Solace event queue in Designer to act as a DMQ for another Solace event queue by setting the appropriate attribute values for both queues.

To configure a DMQ for another Solace event queue, perform these steps:

1. Configure a Solace event queue according to the instructions for Adding a Queue to an Application in Designer.

2. In the configuration for your queue, set the following values:

   Attribute	Description
   deadMsgQueue	Specify the queueName for the DMQ to send expired messages to. Solace recommends using a separate DMQ for each queue that requires one and setting the DMQ name to the name of the queue, followed by "_dmq", for example MyQueue_dmq.
   maxRedeliveryCount	Set this value if you want to specify the maximum number of times the queue attempts to deliver the message before the message expires. If you want to specify the maximum redelivery count, you must also set redeliveryEnabled to true.
   maxTtl	Set this value if you want to specify the TTL in seconds that the queue applies to messages when the message arrives in the queue. If you specify the maximum TTL, you must also set respectTtlEnabled to true.
   respectTtlEnabled	Set this value if you want messages that have not been delivered to expire at the end of the message TTL. If a message is not consumed and its TTL time is reached, the message is discarded or moved to a DMQ.

3. Configure a second Solace event queue to act as the DMQ for the first queue and set the queueName to match the deadMsgQueue value you set for the first queue.

   The DMQ does not need to subscribe to events. It receives only the expired messages from the first queue.

For instructions to configure DMQs in Mission Control, see Configuring Dead Message Queues.

Sending Configuration Updates to an Event Broker

If you update the configuration data or add new configuration data to a Solace event queue in an application after adding the application to an event broker, Update Required appears next to the names of the environments that the application appears in that have runtime event broker configuration enabled.

To send the updates to the runtime event broker, perform these steps:

1. Click Expandnext to the environment to see the list of model event brokers.
2. Click More Actions> Update Event Broker for the event broker that needs to be updated.
3. Review the update to be sent to the event broker and click Update.