Runtime Configuration Templates

Administrators and Event Portal Managers can create configuration templates in Runtime Event Manager to help users set Solace queue configurations and client profile names in applications. If you're sending runtime configuration data from Event Portal to your event brokers, configuration templates help govern the resources being configured on your event brokers and help developers configure client applications to meet your organization's standards.

Runtime Event Manager has two types of configuration templates:

Solace Queue Templates
Solace queue templates define the properties that must be configured for a Solace event queue consumer in an application. You can include the queue properties that need to be set on your operational event brokers and the values that developers are allowed to use when they configure a queue in Designer.
Client Profile Names
Event brokers use client profiles to assign a set of properties to client applications after they successfully authenticate with the event broker. Client profiles define a set of client behaviors and capabilities that the event broker can assign to client applications. For more information, see Using Client Profiles and Client Usernames. Solace event brokers have a default profile that is assigned to all connecting client applications unless another client profile is specified. If you have event brokers that use client profiles other than the default, you can use client profile name templates to allow developers to select from a list of names of the available client profiles.

You can require the use of one of both template types in an environment. If using a Solace queue template is required for an environment, you must use an allowed template for any queue configurations or you can't add the application to the environment. If a client profile name template is required, you must set a client profile name for the application using an allowed template or you can't add the application to the environment. You designate which environments a template is available for in the template settings. If an environment doesn't require configuration templates, applications can use any template that's been added to Event Portal.

This page includes the following information:

Creating Solace Queue Templates

Solace queue templates assist users when they configure a Solace queue consumer in an application in Designer. For more information, see Adding a Queue to an Application in Designer. You define a Solace queue template using a JSON schema.

Queues on Solace event brokers have a range of properties that govern their behavior. For more information, see Queue Configuration Properties. When you create a Solace queue template, you can specify which properties are required in the configuration, which values are fixed, which values application developers can set, and what the allowable values are.

When developers add or update a consumer, they can select a template and set the configurable values, or they can use the template as an example to set a custom configuration.

If you select one or more environments that the template is available in, the template can be used in applications added to the specified environments when a Solace queue template is required. The template can be used in all environments that don't require the use of templates.

To create a Solace queue template, perform these steps:

  1. Log in to the Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your SAP BTP region. For more information, see Logging In to the Cloud Console.
  2. On the navigation bar, select Runtime Event Manager .
  3. In the top-right corner of the screen, click More Actions > Manage Configuration Templates.
  4. In the Template Types list, select Solace Queues.
  5. Click Create Solace Queue Template.
  6. Type a Name and Description for the template.
  7. In the Available In list, select the environments that allow this template when a Solace queue template is required.
  8. Select the Template Schema tab and define the template using a JSON schema. A default template displays in the field to help you get started.

  9. (Optional) After you've finished drafting the template, select the Developer Preview tab and verify that the configurable values are the ones you want developers to be able to configure when they create or update a Solace event queue using the template.

    If you want the preview to display the property names from the template instead of the names for the properties as they appear in Broker Manager, select Show Property Names.

  10. Click Save.

Solace Queue Template Schemas

You create Solace queue templates using a JSON schema.

The default template schema includes these properties:

  • accessType
  • maxBindCount
  • maxMsgSpoolUsage
  • queueName

For more information about the available configuration settings, see Queue Configuration Properties. The template defines which properties need to be configured for the Solace queue, whether the value is constant or can be set by the application developer, and any specific requirements for the value, such as maximums and minimums for integers and patterns or length for string values. The following example shows a schema with the various types of properties that you may want to include in a template:

{
	"additionalProperties": false,
		"properties": {
			"accessType": {
				"const": "exclusive",
				"type": "string"
			},
			"eventMsgSpoolUsageThreshold": {
				"additionalProperties": false,
				"properties": {
					"clearPercent": {
						"type": "integer",
						"default": 60,
						"maximum": 70
					},
					"setPercent": {
						"type": "integer",
						"default": 80,
						"minimum": 70
					}
				},
				"required": ["clearPercent", "setPercent"],
				"type": "object"
			},
			"deadMsgQueue": {
				"pattern": "^^[a-zA-Z]{1,60}_[a-zA-Z]{1,60}_[a-zA-Z]{1,60}_dmq$",
				"placeholder": "applicationDomain_application_consumer_dmq",
				"type": "string"
			},
			"maxMsgSpoolUsage": {
				"default": 5000,
				"maximum": 10000,
				"minimum": 1000,
				"type": "integer"
			},
			"queueName": {
				"pattern": "^[a-zA-Z]{1,60}_[a-zA-Z]{1,60}_[a-zA-Z]{1,60}$",
				"placeholder": "applicationDomain_application_consumer",
				"type": "string"
			},
			"rejectMsgToSenderOnDiscardBehavior": {
				"default": "when-queue-enabled",
				"enum": ["when-queue-enabled", "always"],
				"type": "string"
			},
			"respectTtlEnabled": {
			"default": true,
			"type": "boolean"
			}
		},
		"required": ["deadMsgQueue", "queueName"]}

To view the complete template schema definition, see Solace Queue Template Meta-Schema.

Template Best Practices

You can use the default schema as a base to define your template. When defining a template, we recommend that you follow these best practices:

  • The "additionalProperties": false attribute of the schema restricts the queue configuration to the properties included in the template. This line must be in the template.

  • You must include the queueName property in the template. All other properties are optional.

  • If you want a queue property to always use the event broker default, don't include the property in the template.

  • You can specify a default value for every property except queuename and deadMsgQueue.

  • For queuename and deadMsgQueue you can specify a naming pattern using a regular expression (regex) and a placeholder value. If you specify a pattern, the placeholder should demonstrate the pattern.

    "queueName": {
	"pattern": "^[a-zA-Z]{1,60}_[a-zA-Z]{1,60}_[a-zA-Z]{1,60}$",
	"placeholder": "applicationDomain_application_consumer",
	"type": "string"
},

  • Use "const": "[value]" to include a value in the queue configuration that the user can't change. If you set both "const": "[value]" and "default": "[value]" for the same property, the values should be the same.

    "accessType": {
	"const": "exclusive",
	"type": "string"
},

  • For properties with integer values you can specify an allowable range using the minimum and maximum attributes.

    "maxBindCount": {
	"default": 1000,
	"maximum": 1200,
	"minimum": 800,
	"type": "integer"
},

  • For properties with string values you can specify an allowable length using the minLength and maxLength attributes.

    "deadMsgQueue": {
	"minLength": "7",
	"maxLength": "50",
	"placeholder": "myQueueName_dmq",
	"type": "string"
},

  • Some properties allow enumerations of acceptable values.

    "accessType": {
	"default": "exclusive",
	"enum": ["exclusive", "non-exclusive"],
	"type": "string"
},

Updating Solace Queue Templates

You can update Solace queue templates to match any new requirements. Updating a template does not affect queues on operational event brokers that were configured from an application that used the template in Designer.

After you update a template, applications that use the template display a message that the template is out of date. Users can update an application that uses the template and choose whether to update the queue configuration with the new values from the template or switch to using a custom configuration to keep the current configuration for the queue.

You can also delete templates. If you delete a template, the configuration remains as a custom configuration in any applications that were using the template and applications that use the template display a message that the template had been deleted. Users can update applications that used the template and choose whether switch to using a custom configuration or use a different template.

To update a Solace queue template, perform these steps:

  1. On the navigation bar, select Runtime Event Manager.
  2. In the top-right corner of the screen, click More Actions > Manage Configuration Templates.
  3. In the Template Types list, select Solace Queues.
  4. Click the name of the template that you want to update.
  5. (Optional) In the Available In list, update the list of environments that require template use where this template is allowed.
  6. Update the JSON template schema as necessary.
  7. Click Save.

Creating Client Profile Name Templates

You can create client profile name templates to allow users to select the name of the client profile that the application should use on the event broker. You should only create templates for the names of client profiles that exist on your event brokers. For more information about creating and using client profiles on event brokers, see Using Client Profiles and Client Usernames.

Users can select a client profile name template when they configure consumers in an application to specify the name of the client profile used by the runtime application when it connects to the operational event broker. For more information, see Adding a Queue to an Application in Designer.

If you select one or more environments that the template is available in, the template can by used by applications added those environments when they require a client profile name template. The template can be used in all environments that don't require applications to use a client profile name template.

If you update or delete a client profile name template, a message displays in applications that used the template. Users can choose whether to continue to use a template or switch to using a custom client profile name.

To add a client profile name in Runtime Event Manager, perform these steps:

  1. On the navigation bar, select Runtime Event Manager .
  2. In the top-right corner of the screen, click More Actions > Manage Configuration Templates.
  3. In the Template Types list, select Client Profile Names.
  4. Click Create Client Profile Name Template.
  5. Type a Name and Description for the template.
  6. In the Available In list, select the environments that allow this template when a client profile name template is required.
  7. In the Client Profile Name field, type the client profile name exactly as it appears in Cluster Manager or Broker Manager for the operational event broker.
  8. Click Save.