Apama 10.15.0 | Connecting Apama Applications to External Components | Standard Connectivity Plug-ins | The Universal Messaging Transport Connectivity Plug-in | Configuring the Universal Messaging connectivity plug-in | Configuring the connection to Universal Messaging (dynamicChainManagers)
 
Configuring the connection to Universal Messaging (dynamicChainManagers)
The Universal Messaging dynamic chain manager monitors channels that are subscribed to or sent-to within the correlator and, as per its configuration, connects these to Universal Messaging channels as needed. This is where you specify how to connect to Universal Messaging. When the dynamic chain manager identifies a channel that should be connected to a Universal Messaging channel, it will create a chain using one of the templates in the dynamicChains section of the YAML configuration (see also Configuring message transformations (dynamicChains)).
One UM dynamic chain manager is created under dynamicChainManagers which specifies the Universal Messaging realm or cluster of realms you are connecting to. The managerConfig stanza contains all of the configuration for connecting to that Universal Messaging realm.
dynamicChainManagers:
UM:
transport: UMTransport
managerConfig:
rnames: nsp://127.0.0.1:9000
session:
poolSize: 8
certificateAuthorityFile: /mypath/my_UM_certificate
authentication:
username: me
certificateFile: /mypath/my_client_certificate
certificatePassword: mycertificatepassword
channel:
prefix: "um:"
missingChannelMode: create
escapeNamesOnUM: true
includePrefixOnUM: false
createChannelPermissions:
user@host:
- Manage ACL
- Full
"*@*":
- Publish
- Subscribe
- Last EID
Everyone:
- Purge
The following table describes the options that can be used in the managerConfig section:
Option
Description
rnames
Required. The Universal Messaging connection string of realm names to connect to.
You can specify one or more Universal Messaging realm names (RNAME) separated by commas or semicolons.
Commas indicate that you want the correlator to try to connect to the Universal Messaging realms in the order in which you specify them here. For example, if you have a preferred local server you could specify its associated realm name first and then use commas as separators between specifications of other realm names, which would be connected to if the local server is down.
Semicolons indicate that the correlator can try to connect to the specified Universal Messaging realms in any order. For example, use semicolons when you have a cluster of equally powered machines in the same location and you want to load balance a large number of clients.
You can specify multiple Universal Messaging realms only when they are connected in a single Universal Messaging cluster. That is, all realm names you specify must belong to the same Universal Messaging cluster. Since channels are shared across a cluster, connecting to more than one Universal Messaging realm lets you take advantage of Universal Messaging's failover capability.
For additional information on communication protocols and realm names, and on clusters, see the Universal Messaging documentation.
Default value: none.
session/poolSize
The number of sessions (connections) to create to the Universal Messaging realm. Either a number of sessions or a string of the form /N which indicates a divisor applied to the number of CPUs to obtain the number of sessions. Channels are allocated to sessions in a round-robin style.
Default value: 8.
certificateAuthorityFile
The path to a CA certificate for the Universal Messaging realm. This is used by the Apama to confirm the identity of the Universal Messaging realm server.
Default value: none.
authentication/username
The username that is to be used to connect to the Universal Messaging realm. The default is the user which the correlator is running as.
Default value: none.
authentication/certificateFile
The path to a certificate that is used by the Universal Messaging realm server to authenticate this client.
Default value: none.
authentication/certificatePassword
The password for the certificate.
Default value: none.
channel/prefix
A prefix for the channel. Only channels with this prefix will be considered as Universal Messaging channels. If the prefix ends with a colon (:), it needs to be enclosed in quotation marks (see also Using YAML configuration files).
Default value: "um:".
channel/includePrefixOnUM
If set to false, the channel prefix is stripped from the Apama channel name before it is looked up on Universal Messaging.
Default value: false.
channel/escapeNamesOnUM
If set to true, non-alphanumeric characters in the Apama channel name are escaped on Universal Messaging. Set this to false if you want to use the slash (/) for hierarchical channels on Universal Messaging.
Default value: true.
channel/missingChannelMode
Defines the behavior when subscribing to channels which do not exist. You can define one of the following options:
*error - Print an error to the correlator log file. The channel remains only accessible within the correlator.
*ignore - Silently ignore the failure and therefore do not print an error to the correlator log. The channel remains only accessible within the correlator.
*create - Create the channel on the Universal Messaging realm, then subscribe/send to it. See also Subscribing to automatically created Universal Messaging channels.
Default value: create.
createChannelPermissions
Defines the ACL (access control list) permissions for automatically created channels in the following format:
client:
- permission1
- permission2
- ...
The client can be either a subject (of the format user@host) or a group. Universal Messaging supports the * wildcard for representing all users/hosts. You can specify the following permissions:
*Manage ACL
*Full
*Publish
*Subscribe
*Purge
*Last EID
For additional information on subject, group, wildcards and permission ACLs, see the Universal Messaging documentation.
Default:
creating-user@*:
- Subscribe
- Publish
- Last EID
Note: 
Apama clients require Last EID permission in addition to Subscribe permission for a client to subscribe to a channel.
Setting channel permissions correctly is important to protect the security of your application, and also to protect any personal data included in the messages. For more information, see Protecting Personal Data in Apama Applications.