Creating a Universal Messaging Connection Alias

Software AG Products 10.11 | Administering Integration Server | Configuring Integration Server for webMethods Messaging | Working with Messaging Connection Aliases | Creating a Universal Messaging Connection Alias

Creating a Universal Messaging Connection Alias

About Follow the Master for webMethods Messaging

A Universal Messaging connection alias is a webMethods messaging connection alias that contains the configuration information for establishing a connection to a Universal Messaging server. Each Integration Server can have multiple Universal Messaging connection aliases.

If Integration Server uses the Universal Messaging connection alias to connect to a secure socket protocol port on the Universal Messaging server, you must configure the connection alias to use SSL. You specify truststore and possibly keystore information in the alias. This allows communication between Integration Server and Universal Messaging to be secured through secure socket layers (SSL). A Universal Messaging port uses SSL if the port specifies an interface protocol of NSPS or NHPS. Depending on how the Universal Messaging port is configured, you might need to supply a client certificate:

If the Universal Messaging port specifies NSPS or NHPS and the Enable Client Cert Validation option is not selected for the port, you need to specify a truststore alias during configuration of the Universal Messaging connection alias.

If the Universal Messaging port specifies NSPS or NHPS and the Enable Client Cert Validation option is selected for the port, you need to specify a truststore alias, keystore alias, and key alias during configuration of the Universal Messaging connection alias.

Note:
Use Universal Messaging Enterprise Manager to view the protocol and Enable Client Cert Validation option selected for the port.

If the Universal Messaging connection alias establishes a connection to as secure port on Universal Messaging, you need to do the following before completing configuration of the alias.

Create a truststore that contains the certificate authority (CA) of the certificates for the Universal Messaging server. Then create a truststore alias for the truststore. For more information about creating a truststore alias, see Creating Truststore Aliases.

If the Universal Messaging port performs client certificate validation, do the following:

Create a keystore that contains the client certificates used by Integration Server to connect with Universal Messaging. Create a keystore alias for the keystore, making sure to specify a key alias for the key that contains the private key for connecting to the Universal Messaging port securely. For more information about creating a keystore alias, see Creating Keystore Aliases.

Verify that truststore used by Universal Messaging contains the certificate authority of the certificates used by Integration Server.

Note:
Keep the Universal Messaging client libraries up to date. If you install a Universal Messaging fix that updates the client libraries, make sure to copy the updated Universal Messaging client library files to the Software AG_directory /common/lib directory used by Integration Server.

Use the following procedure to create a Universal Messaging connection alias.

To create a Universal Messaging connection alias

1. Open the Integration Server Administrator.

2. Go to Messaging > webMethods settings.

3. Click Create Universal Messaging Connection Alias.

4. Under General Settings, specify the following:

Field	Description
Connection Alias Name	A unique name for the messaging connection alias.
Description	A description of the messaging connection alias.
Client Prefix	A string that identifies the Integration Server to Universal Messaging. If your Integration Server belongs to a cluster, make sure all servers in the cluster use the same client prefix.
Client Prefix Is Shared (prevents removal of shared messaging provider objects)	Whether Integration Server shares the client prefix with multiple Integration Servers and you want to prevent automatic updates, including deletions, to shared objects associated with this alias on Universal Messaging server. Leave the check box cleared if you do not want to prevent automatic updates to shared objects on the Universal Messaging server. When the Client Prefix Is Shared check box is selected, you must update objects on Universal Messaging manually. For example, if you delete a trigger on Integration Server you need to manually delete the associated channel on Universal Messaging. You must select Client Prefix Is Shared if the Integration Server: Belongs to a cluster and you want to prevent automatic updates to shared objects associated with this alias on the Universal Messaging server. Belongs to a non-clustered group of Integration Servers that operate in a load-balanced fashion and you want to prevent automatic updates to shared objects associated with this alias on the Universal Messaging server. For more information about configuring Integration Servers to receive messages from Universal Messaging in a load-balanced fashion, see Load Balancing with a Non-Clustered Group of Integration Servers. The Universal Messaging connection alias is used by loggers on multiple Integration Servers in a cluster or non-clustered group to write or read logs from a Universal Messaging queue. Selecting the Client Prefix Is Shared check box ensures that Universal Messaging queue name includes the client prefix which allows Integration Servers to write to and read from the same logging queue across a Universal Messaging realm. For more information about using a Universal Messaging queue as the logging queue, see the webMethods Audit Logging Guide.

5. Under Connection Settings, specify the following:

Field	Description
Realm URL	The URL for the Universal Messaging server in the format protocol:// UM_host: UM_port where protocol is the protocol for the port, such as nsp, nsps, or nhps. For example, nsp://127.0.0.1:9000 or nsps://localhost:9000. If the protocol for connecting to Universal Messaging server is nsps or nhps, you must provide the appropriate certificates for use with the connection alias. You must provide a truststore alias or a truststore alias and keystore alias. If you are using a cluster of servers, supply the list of URLs to each server in the cluster using a comma-separated or a semicolon-separated list. By default, Integration Server is configured to follow the master realm server in a cluster, which indicates that Integration Server always connects to the master realm server in the cluster. Software AG recommends using a comma-separated list of URLs if the alias uses follow the master. Note: You must specify a URL for every Universal Messaging server in the cluster. Integration Server connects only to the Universal Messaging servers for which you specify a URL. Consequently, Integration Server creates resources such as channels and durable subscriptions only on the specified Universal Messaging servers. If you specify only one Universal Messaging server in a cluster, the resources will be local to that server only. To use the Universal Messaging horizontal scalability feature with this messaging connection alias, enclose each realm URL or multiple realm URLs separated by commas in parenthesis. In a cluster, the realm URLs must be separated by a comma. Examples of Horizontal Scalability URL Syntax (realm1)(realm2)(realm3)(realm4) - Indicates 4 standalone realms, namely realm1, realm2, realm3 and realm4. (realm1,realm2)(realm3,realm4) - Indicates 2 clusters, one consisting of realm1 and realm2 and the other consisting of realm3 and realm4. (realm1)(realm2,realm3)(realm4) - Indicates one cluster consisting of realm2 and realm3, and two standalone realms, namely realm1 and realm4.
	If you disabled the follow the master behavior for producers and/or consumers using this alias, whether you separate the realm servers in a cluster with a comma or a semicolon determines the Universal Messaging realm server to which Integration Server connects. Separate the URLs using a comma if Integration Server always attempts to connect to the first Universal Messaging server in the list, only trying the second Universal Messaging server in the list if the first server becomes unavailable. Separate the URLs using a semicolon if Integration Server connects to a randomly chosen URL from the list. This may result in better distribution of clients across the servers in the cluster. For more information about the follow the master behavior including how to disable it, see About Follow the Master for webMethods Messaging.
Maximum Reconnection Attempts	Specify the maximum number of reconnection attempts that Integration Server makes if the connection to Universal Messaging fails. If the connection cannot be re-established, Integration Server writes messages to the error log and the connection created by this messaging connection alias will be stopped. The default is 5 attempts. Note: The Maximum Reconnection Attempts value is a factor only when an existing connection fails. The Maximum Reconnection Attempts value is not a factor that Integration Server considers when starting a messaging connection alias.

6. Under Producer Settings, specify the following:

Field	Description
Enable CSQ	Whether a client side queue is used with this Universal Messaging connection alias. Do one of the following: Select the Enable CSQ check box if you want to use a client side queue with this Universal Messaging connection alias. When a client side queue is in use, if the Universal Messaging server is not available when Integration Server publishes documents using this Universal Messaging connection alias Integration Server writes the documents to the client side queue. Clear the Enable CSQ check box if you do not want to use a client side queue with this Universal Messaging connection alias. When a client side queue is not in use, if the Universal Messaging server is not available when Integration Server publishes documents using this Universal Messaging connection alias, the publishing service ends with an ISRuntimeException.
Maximum CSQ Size (messages)	The maximum number of documents (messages) that can exist in the client side queue for this Universal Messaging connection alias. If the client side queue is at capacity, publishing services that use this connection alias will end with an ISRuntimeException. Specify -1 if you want the client side queue to be able to contain an unlimited number of messages.
Drain CSQ in Order	Whether Integration Server drains the client side queue for this alias by sending the messages to the Universal Messaging server in the same order in which Integration Server placed the messages in the client side queue. Do one of the following: Select the Drain CSQ in Order check box if you want Integration Server to send messages to the Universal Messaging in publication order when the connection to the Universal Messaging server is re-established. After the connection to the Universal Messaging server is re-established, Integration Server continues to write newly published messages to the client side queue until the client side queue is completely drained. Clear the Drain CSQ in Order check box if you do not want Integration Server to preserve publication order when the connection to the Universal Messaging server is re-established. After the connection to the Universal Messaging server re-established, Integration Server sends newly published messages directly to the Universal Messaging server while draining the client side queue.
Publish Wait Time While Reconnecting	The number of milliseconds that a publishing service using this Universal Messaging connection alias will wait for a connection to the Universal Messaging server to be re-established after the connection fails. If Integration Server re-establishes the connection before the Publish Wait Time While Reconnecting elapses, the publishing service continues executing. If the specified time elapses before a connection is re-established, the publishing service ends with an ISRuntimeException. The default is 0 milliseconds, which means that publishing services will not wait for Integration Server to re-establish the connection. Note: When a Universal Messaging connection alias is configured to connect to a Universal Messaging cluster, make sure the Publish Wait Time While Reconnecting value is long enough to accommodate the time the Universal Messaging cluster takes to establish a quorum after one of the member servers fails.
Enable Follow the Master for Producers	Whether Integration Server always connects to the master realm server in a Universal Messaging cluster when Integration Server uses this Universal Messaging connection alias to publish messages. Do one of the following: Select the Enable Follow the Master for Producers check box to indicate that Integration Server always connects to the master realm server in a Universal Messaging cluster when Integration Server uses this Universal Messaging connection alias to publish messages. Clear the Enable Follow the Master for Producers check box to disable the follow the master behavior for this alias when it is used to send messages. When follow the master is disabled for producers, Integration Server connects to a server in a Universal Messaging cluster using the order dictated by the comma or semi-colon separated list of URLs in the Realm URL parameter. For more information about the follow the master behavior, see About Follow the Master for webMethods Messaging.

7. Under Consumer Settings, specify the following for the Enable Request/Reply Channel and Listener check box.

Field	Description
Enable Request/Reply Channel and Listener	Whether you intend to use this Universal Messaging connection alias to send request documents, send reply documents, or receive reply documents as part of a request/reply or publish-and-wait scenario. Do one of the following: Select the Enable Request/Reply Channel and Listener if you intend to use this Universal Messaging connection alias to send request documents, send reply documents, or receive reply documents as part of a request/reply or publish-and-wait scenario Clear the Enable Request/Reply Channel and Listener check box if you do not intend to use this Universal Messaging connection alias as part of a request/reply or publish-and-wait scenario. This will conserve resources on Integration Server and Universal Messaging. When the Enable Request/Reply Channel and Listener check box is selected, Integration Server does the following when the Universal Messaging connection alias starts: Create a request/reply channel for this Universal Messaging connection alias if one does not yet exist. The request/reply channel name includes a string identifying the Integration Server, the client prefix, and the text “RequestReply”. Start a listener on Integration Server that subscribes to the alias-specific request/reply channel.
Enable Follow the Master for Consumers	Whether Integration Server always connects to the master realm server in a Universal Messaging cluster when Integration Server uses this Universal Messaging connection alias to retrieve messages. Do one of the following: Select the Enable Follow the Master for Consumers check box to indicate that t Integration Server always connects to the master realm server in a Universal Messaging cluster when using this Universal Messaging connection alias to retrieve messages Clear the Enable Follow the Master for Consumers check box to disable the follow the master behavior for this alias when it is used to retrieve messages. When follow the master is disabled for consumers that use this alias, Integration Server connects to a server in a Universal Messaging cluster using the order dictated by the comma or semi-colon separated list of URLs in the Realm URL parameter. For more information about the follow the master behavior, see About Follow the Master for webMethods Messaging.

8. Under Client Authentication Settings, specify the following:

Field	Description
Client Authentication	The type of authentication an Integration Server client will use to connect to the Universal Messaging server. Choose one of the following options: None. Select this option if no authentication should be performed. This is the default. Even if Universal Messaging does not perform client authentication, if the protocol specified for Realm URL is nsps or nhps, you must select a truststore alias in the Truststore Alias field. Username/Password. Select this option if the Universal Messaging server performs basic client authentication using user name/password combinations. If you select this option, specify the user name and password the client will use in the Username and Password fields. In addition to providing the username and password for client authentication, if the protocol specified for Realm URL is nsps or nhps, you must also select a truststore alias in the Truststore Alias field. Certificate Based. Select this option if Integration Server connects to a secure socket layer (SSL) port on the Universal Messaging and Universal Messaging performs certificate-based authentication. Depending on how the Universal Messaging port is configured, you must specify a truststore alias and possibly a keystore alias and key alias for theUniversal Messaging connection alias. If the Universal Messaging port does not have the Enable Client Cert Validation option selected, you must specify a truststore alias. If the Universal Messaging port has the Enable Client Cert Validation option selected, you must specify a truststore alias, keystore alias, and key alias. Note: Use Universal Messaging Enterprise Manager to view the protocol and Enable Client Cert Validation option specified for a port.
Truststore Alias	The alias for the truststore that contains the certificate authority (CA) certificates for the Universal Messaging server. You must select a truststore alias if the Universal Messaging port is configured for certificate-based authentication or if the protocol specified for Realm URL is nsps or nhps.
Keystore Alias	The alias for the keystore that contains the client certificates that you want Integration Server to use when connecting to the Universal Messaging port. You must select a keystore alias if the Universal Messaging port is configured for certificate based authentication.
Key Alias	The alias to the key that contains the private key for connecting to the Universal Messaging port securely. The key alias must be in the keystore specified in Keystore Alias. You must specify a Key Alias if you specify a Keystore Alias.

9. Under Enhanced Logging, specify the following to configure additional logging for messages sent and/or received using this connection alias:

Field	Description
Logging Type	Specifies where Integration Server writes log messages when enhanced logging is enabled for the message producers and/or consumers that use this messaging connection alias to send and/or receive documents. SERVER LOG. Select this option to write enhanced logging messages to the server log. If you specify the server log as the destination, make sure to increase the logging level for the 0168 Messaging (Enhanced Logging) server log facility to at least Info. MESSAGING AUDIT LOG. Write enhanced logging messages to the messaging audit log. You can select one of the options only. Integration Server cannot write enhanced logging messages to the server log and the messaging audit log.
Enable Producer Message ID Tracking	Select to indicate that Integration Server writes additional log messages when a message producer uses this messaging connection alias to publish documents that are instances of the publishable document types listed in Producer Message ID Tracking: Include Channels.
Producer Message ID Tracking: Include Channels	The name of each channel that corresponds to a publishable document type for which Integration Server performs additional logging during publication. Use a semicolon (;) to separate each channel name. Leave this field blank if you want Integration Server to perform enhanced logging for every channel to which this messaging connection alias sends messages
Enable Consumer Message ID Tracking	Select to indicate that Integration Server writes additional log messages for messaging consumers (triggers) that use this messaging connection alias to receive messages. Integration Server writes additional log message for the triggers listed in Consumer Message ID Tracking: Include Triggers.
Consumer Message ID Tracking: Include Triggers	The fully qualified name of the triggers for which Integration Server performs additional logging during trigger processing. Use a semicolon (;) to separate each trigger name. Leave this field blank if you want Integration Server to perform enhanced logging for every trigger that uses this messaging connection alias to receive messages.

For more information about using enhanced logging for documents sent to and received from Universal Messaging, Using Enhanced Logging for Messaging.

10. Click Save Changes.

11. Enable the Universal Messaging connection alias.

Note:
To configure a Universal Messaging connection alias to connect to a Universal Messaging port that performs certificate-based authentication, the alias needs to specify a truststore alias, keystore alias, and key alias. However, if you set Client Authentication to Certificate Based in the connection alias but do not supply the truststore alias or keystore alias needed to establish an SSL connection with the Universal Messaging server, Integration Server looks for this information in the JVM. For information about setting the SSL-related system properties in the JVM, see Configuring SSL Information for the Integration Server JVM.

Software AG recommends specifying the truststore alias, keystore alias, and key alias information in the Universal Messaging connection alias instead of relying on the JVM system properties.