Universal Messaging Commands
Instance Management
The following table lists the required parameters that you must include when managing the Universal Messaging instances using the Universal Messaging instance management commands:
Command | Parameter | Description |
sagcc create instances | NumRealmServer, NumEnterpriseManager, and NumTemplateApplications | The product ID for the Universal Messaging instance. |
| instance.name | Required. A name for the new Universal Messaging instance. |
| instance.ip | Optional. An IP address for the Universal Messaging server interface. If you do not specify a value, 0.0.0.0 is the default value. |
| instance.port | Optional. A port number for the Universal Messaging server. If you do not specify a value, 9000 is the default port number. |
| instance.dataDir | Optional. Absolute path to Universal Messaging server data directory. If you do not specify a path, the default directory location is used for creating the data directory. Location of the default directory is: Universal Messaging_directory \server\umserver |
| license.file | Optional. Absolute path to the Universal Messaging license file. If you do not specify a path, the default license is used. Location of the default directory is: Universal Messaging_directory \server\umserver |
| instance.config.profile | Optional. Initial configuration settings for the Universal Messaging server instance. Options for the parameter value:  wM: webmethods suite use cases. TC: Standalone use cases. CUSTOM: Custom profile. |
| instance.config.file | Required if the instance.config.profile parameter value is CUSTOM. Absolute path to the custom profile XML file. |
Important: Universal Messaging does not support sagcc update instances. You cannot rename a Universal Messaging instance.
Examples:
To check if
Universal Messaging supports instance management operations through
Command Central for a node with alias “messagingNode”:
sagcc list instances messagingNode supportedproducts
To create an instance of
Universal Messaging server named “umserver” on port number “9000” of the node with alias “messagingNode”:
sagcc create instances messagingNode NUMRealmServer instance.name=umserver
instance.ip=0.0.0.0 instance.port=9000
To create an instance of
Universal Messaging server named “umserver” on port number “9000” of the node with alias “messagingNode” and having a custom data directory path and license file:
sagcc create instances messagingNode NUMRealmServer instance.name=umserver
instance.ip=0.0.0.0 instance.port=9000
instance.dataDir=Data_Directory_Absolute_Pathlicense.file=
absolute path to the license file
To create an instance of
Universal Messaging server named "umserver" on port number “9000” of the node with alias “messagingNode”, and provide an initial configuration settings:
sagcc create instances messagingNode NUMRealmServer instance.name=umserver
instance.ip=0.0.0.0 instance.port=9000 instance.config.profile=wM or TC
To create an instance of
Universal Messaging server named "umserver" on port number “9000” of the node with alias “messagingNode”, and provide custom initial configuration settings:
sagcc create instances messagingNode NUMRealmServer instance.name=umserver
instance.ip=0.0.0.0 instance.port=9000 instance.config.profile=CUSTOM
instance.config.file=absolute path to the custom profile XML file
To read the following properties of
Universal Messaging server named “umserver":
Port number
Interface IP address
Server data directory path
License path
sagcc list instances messagingNode Universal-Messaging-umserver
To remove the “umserver”
Universal Messaging server instance existing on the node with alias “messagingNode” node:
sagcc delete instances messagingNode Universal-Messaging-umserver
To create an Enterprise Manager instance named “EM1”:
sagcc create instances messagingNode instance.name=em1
instance.ip=0.0.0.0 instance.port=9000
Use the Universal Messaging Instance Manager tool to delete the Enterprise Manager and Template Applications instances. You cannot use Command Central commands for deleting these instances as they are not listed in the product inventory.
Note: You can create a Template Applications instance using the same command used to create an Enterprise Manager instance.
Universal Messaging Configuration Types
The following table lists the configuration types that Universal Messaging server instance supports.
Configuration Type | Use to... |
COMMON-LOCAL-USERS | Configure and manage users of a Universal Messaging server instance. COMMON-LOCAL-USERS-userId supports configuring the user ID and password of each user. By default, the users have administrator privileges for the Universal Messaging server instance. |
COMMON-LICENSE | Configure the Universal Messaging-specific SagLic license file. |
COMMON-LICLOC | View the location of a Universal Messaging server instance’s license file. You cannot change the location of the license file. |
COMMON-SYSPROPS | Configure Universal Messaging server instance properties. |
UM-JNDI-CF | Configure the following JNDI connection factories: Connection Factory Topic Connection Factory Queue Connection Factory XA Connection Factory |
UM-JNDI-DEST | Configure the following JNDI destinations: Topics Queues |
COMMON-CLUSTER | Configure an active/active Universal Messaging cluster. |
COMMON-MEMORY | Configure the size of the initial memory, maximum memory, and the maximum direct memory (extended property) of a Universal Messaging server instance. |
COMMON-PORTS | Configure the Universal Messaging server interfaces. You cannot change the protocol, bind address, port number, or alias of a port of an existing server interface. If you change the SSL certificates of a secured interface, you must restart the interface. |
UM-CHANNELS | Create and manage Universal Messaging channels. |
UM-QUEUES | Create and manage Universal Messaging queues. |
User Configuration
You can use the command line interface commands, web user interface, or internaluserrepo.bat/sh script to configure users of a Universal Messaging server instance.
You can perform the following user configuration tasks on a Universal Messaging server instance from the command line interface:
List the path and the users existing in the user repository using the
sagcc get configuration instances node_alias Universal-Messaging-umserver command.
Retrieve information about a specific user using the
sagcc get configuration instances node_alias Universal-Messaging-umserver COMMON-LOCAL-USERS-user name command.
Add new users to the user repository using the
sagcc create configuration data node_alias Universal-Messaging-umserver COMMON-LOCAL-USERS --input absolute path to the XML file containing the user ID and password.Update or change the password of an existing user using the
sagcc update configuration data node_alias Universal-Messaging-umserver COMMON-LOCAL-USERS-user name --input absolute path to the XML file containing new password.Delete existing users from the user repository using the
sagcc delete configuration data node_alias Universal-Messaging-umserver COMMON-LOCAL-USERS-user name command.
Information to authenticate the users of a Universal Messaging server instance is stored in the user repository (users.txt file). The path of the user repository users.txt file is specified in the Server_Common.conf file of the Universal Messaging server instance irrespective of whether you are running Universal Messaging as a service or as an application. The default path for the Universal Messaging user repository (users.txt file) is Universal Messaging directory\server\umserver instance. While creating the user repository, if you specify a relative path, the users.txt file will be created in a directory relative to the bin directory of the Universal Messaging server instance.
Examples:
To list the path of the user repository and the users of a
Universal Messaging server instance:
sagcc get configuration instances sag01 Universal-Messaging-umserver
where umserver is the name of the Universal Messaging server instance, and sag01 is the alias name of the installation where umserver is running.
To retrieve information of a
Universal Messaging server instance user:
sagcc get configuration instances sag01 Universal-Messaging-umserver
COMMON-LOCAL-USERS-user1
where umserver is the name of the Universal Messaging server instance, sag01 is the alias name of the installation where umserver is running, and user1 is the user ID of the user.
To add a user to a
Universal Messaging server instance:
sagcc create configuration data sag01 Universal-Messaging-umserver
COMMON-LOCAL-USERS --input c:\inputxmls\user2.xml
where umserver is the name of the Universal Messaging server instance, sag01 is the alias name of the installation where umserver is running, and user2.xml is file that contains the user ID and the password of the new user.
Format of the user2.xml file:
To update the password of a
Universal Messaging server instance user:
sagcc update configuration data sag01 Universal-Messaging-umserver
COMMON-LOCAL-USERS-user2 --input c:\inputxmls\user2.xml
where umserver is the name of the Universal Messaging server instance, sag01 is the alias name of the installation where umserver is running, and user2.xml is the file that contains the new password of the specified user.
To delete a
Universal Messaging server instance user:
sagcc delete configuration data sag01 Universal-Messaging-umserver
COMMON-LOCAL-USERS-user2
where umserver is the name of the Universal Messaging server instance, sag01 is the alias name of the installation where umserver is running.
License Configuration
You can view the content and the location of the license file, and change the license file of a Universal Messaging server instance.
View the license details of a
Universal Messaging server instance using the
sagcc get configuration data node_alias Universal-Messaging-umserver COMMON-LICENSE-Universal-Messaging command.
View the license location of a
Universal Messaging server instance using the
sagcc get configuration data node_alias Universal-Messaging-umserver COMMON-LICLOC-Universal-Messaging command.
Add a
Universal Messaging license key file with the specified alias to the
Command Central license key manager using the
sagcc add license-tools keys license key alias -i absolute path to the license file command.Update a license key file assigned to the specified license key alias using
sagcc update configuration license node_alias Universal-Messaging-umserver COMMON-LICENSE-Universal-Messaging
license key alias.
Examples:
To view the license details of a
Universal Messaging server instance with "Universal-Messaging-umserver" component ID that runs in the installation with alias name “sag01”:
sagcc get configuration data sag01 Universal-Messaging-umserver
COMMON-LICENSE-Universal-Messaging
To view the license file location of a
Universal Messaging server instance with "Universal-Messaging-umserver" component ID that runs in the installation with alias name “sag01”:
sagcc get configuration data sag01 Universal-Messaging-umserver
COMMON-LICLOC-Universal-Messaging
To add a
Universal Messaging license key file with the license key alias "um_lic" to the
Command Central license key manager:
sagcc add license-tools keys um_lic -i C:\umlicense\new_license.xml
To update a license key file assigned to the license key alias "um_lic" with "Universal-Messaging-umserver" component ID that runs in the installation with alias name “sag01” :
cc update configuration license sag01 Universal-Messaging-umserver
COMMON-LICENSE-Universal-Messaging um_lic
Properties Configuration
You can view configuration properties for a specific configuration group by using the
sagcc get configuration data command.
You can update the configuration properties by using the
sagcc update configuration data command.
For information about configuration properties, see
Properties Configuration.
Examples:
To view the cluster configuration properties for the
Universal-Messaging-umserver server instance:
sagcc get configuration data sag01 Universal-Messaging-umserver
COMMON-SYSPROPS-Data_Stream_Config
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. Data_Stream_Config is the name of the configuration group.
To update cluster configuration properties for
Universal-Messaging-umserver server instance:
sagcc update configuration data sag01 Universal-Messaging-umserver
COMMON-SYSPROPS-Data_Stream_Config --input c:\datastreamconfig.properties
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running.
COMMON-SYSPROPS-Cluster_Config is the configuration instance ID where COMMON-SYSPROPS is the configuration type and Data_Stream_Config is the name of the configuration group.
datastreamconfig.properties is the properties file containing the modified configuration parameters.
The properties file should contain parameter values in the following format:
FanoutTaskQueueSize=66
FanoutTraversalType=2
MaxSessionIdSize=14
MonitorTimer=10000
OffloadMulticastWrite=false
ParallelFanoutThreshold=50
SendInitialMapping=true
Important: Parameter names are case sensitive. For parameter values of enumeration type, set values ranging from 0 to n to map to the corresponding enumeration values in the Command Central user interface. For example, in the above properties file, FanoutTraversalType=2 will be mapped to the value Reversed Order.
Note: The sagcc update configuration data command exits and displays an error at the first instance of a wrong parameter definition. For example, in the above example, the command will exit displaying an error if MonitorTimer is assigned a string value.
JNDI Configuration
You can create, view, update, and delete a JNDI asset. Ensure that the Universal Messaging server instance is running before executing the following commands.
View all the configuration types for a
Universal Messaging server instance using the
sagcc get configuration types node_alias Universal-Messaging-umserver command.
View all the configuration instances for a
Universal Messaging server instance using the
sagcc get configuration instances node_alias Universal-Messaging-umserver command.
Create a new JNDI connection factory by passing parameters defined in an XML file using the
sagcc create configuration data node_alias Universal-Messaging-umserver UM-JNDI-CF -i absolute path to the XML file command. You can create the following connection factory types:
ConnectionFactory,
TopicConnectionFactory,
QueueConnectionFactory, and
XAConnectionFactory.
The XML file should contain the parameters in the following format:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<connectionFactory>
<name>connection_factory_name</name>
<type>connection_factory_type</type>
<url>connection_factory_binding_url</url>
<sharedDurable>true/false</sharedDurable>
</connectionFactory>
Note: The parameters name, type, and url are required and the sharedDurable parameter is optional.
Create a new JNDI destination by passing parameters defined in an XML file using the
sagcc create configuration data node_alias Universal-Messaging-umserver UM-JNDI-DEST -i absolute path to the XML file command. You can create the following destination types:
Topic and
Queue.
The XML file should contain the parameters in the following format:
name parameter can include upper and lower case alphabetic characters, digits (0-9), double colon (::), slash (/), and periods (.), for example, destination1. Use the double colon (::) for specifying nested name space, for example, destination1::destination2. A combination of special characters in a name is not allowed, for example, destination1::destination2/destination3. storeName parameter can include upper and lower case alphabetic characters, digits (0-9), double colon (::), slash (/), and underscores (_) but cannot include periods (.).
Retrieve information about a specific JNDI connection factory using the
sagcc get configuration data node_alias Universal-Messaging-umserver UM-JNDI-CF-connection_factory_name command.
Retrieve information about a specific JNDI destination using the
sagcc get configuration data node_alias Universal-Messaging-umserver UM-JNDI-DEST-destination_name command.
Update a JNDI connection factory by passing the new parameters defined in an XML file using the
sagcc update configuration data node_alias Universal-Messaging-umserver UM-JNDI-CF-connection_factory_name -i absolute path to the XML file command.
Important: You can update the URL and the sharedDurable property, you cannot update the name of the connection factory.
Delete a JNDI connection factory using the
sagcc delete configuration data node_alias Universal-Messaging-umserver UM-JNDI-CF-connection_factory_name command.
Delete a JNDI destination using the
sagcc delete configuration data node_alias Universal-Messaging-umserver UM-JNDI-DEST-destination_name command.
Note: Deleting a JNDI destination will not delete the channel or queue that exists in the Universal Messaging server instance.
Examples:
To view all the configuration types for a
Universal Messaging server instance:
sagcc get configuration types sag01 Universal-Messaging-umserver
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running.
To view all the configuration instances for a
Universal Messaging server instance:
sagcc get configuration instances sag01 Universal-Messaging-umserver
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running.
To create a new JNDI connection factory by passing parameters defined in an XML file:
sagcc create configuration data sag01 Universal-Messaging-umserver
UM-JNDI-CF -i C:\jndi\connecton_factory.xml
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. UM-JNDI-CF is the configuration type and C:\jndi\connecton_factory.xml is the absolute path to the XML file in which the parameters are defined. Example of properties defined in the XML file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<connectionFactory>
<name>connectionfactory1</name>
<type>ConnectionFactory</type>
<url>nhp://124.597.890:9100</url>
<sharedDurable>true</sharedDurable>
</connectionFactory>
To create a new JNDI destination by passing parameters defined in an XML file:
sagcc create configuration data sag01 Universal-Messaging-umserver
UM-JNDI-DEST -i C:\jndi\destination.xml
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. UM-JNDI-DEST is the configuration type and C:\jndi\destination.xml is the absolute path to the XML file in which the parameters are defined. Example of properties defined in the XML file:
To retrieve information about a specific JNDI connection factory:
sagcc get configuration data sag01 Universal-Messaging-umserver
UM-JNDI-CF-connectionfactory1
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. UM-JNDI-CF is the configuration type and connectionfactory1 is the name of the JNDI connection factory from which information is to be retrieved.
To retrieve information about a specific JNDI destination:
sagcc get configuration data sag01 Universal-Messaging-umserver
UM-JNDI-DEST-destination1
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. UM-JNDI-DEST is the configuration type and destination1 is the name of the JNDI destination from which information is to be retrieved.
To update a JNDI connection factory by passing the new parameters defined in an XML file:
sagcc update configuration data sag01 Universal-Messaging-umserver
UM-JNDI-CF-connectionfactory1 -i C:\jndi\update.xml
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. UM-JNDI-CF is the configuration type, onnectionfactory1 is the name of the connection factory to be updated, and C:\jndi\update.xml is the absolute path to the XML file in which the updated parameters are defined. Example of properties defined in the XML file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<connectionFactory>
<url>nhp://123.567.890:9100</url>
<sharedDurable>false</sharedDurable>
</connectionFactory>
To delete a JNDI connection factory:
sagcc delete configuration data sag01 Universal-Messaging-umserver
UM-JNDI-CF-connectionfactory1
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. UM-JNDI-CF is the configuration type and connectionfactory1 is the name of the JNDI connection factory.
To delete a JNDI destination:
sagcc delete configuration data sag01 Universal-Messaging-umserver
UM-JNDI-DEST-destination1
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. UM-JNDI-DEST is the configuration type and destination1 is the name of the JNDI destination.
Usage Notes
Updating JNDI destinations is not supported.
Creating a connection factory and destination with the same name is not allowed for a
Universal Messaging server instance.
Channel and Queue Configuration
Ensure that the Universal Messaging server instance is running before executing the following commands.
View all the configuration instances for a
Universal Messaging server instance using the
sagcc get configuration instances node_alias Universal-Messaging-umserver command.
Create a channel on a
Universal Messaging server instance using the
sagcc create configuration data node_alias Universal-Messaging-umserver UM-CHANNELS -i absolute path to the XML file containing channel properties command .
Update a channel on a
Universal Messaging server instance using the
sagcc update configuration data node_alias Universal-Messaging-umserver UM-CHANNELS-channel_name -f xml -i absolute path to the XML file containing channel properties command.
Create a queue on a
Universal Messaging server instance using the
sagcc create configuration data node_alias Universal-Messaging-umserver UM-QUEUES -i absolute path to the XML file containing queue properties command .
Update a queue on a
Universal Messaging server instance using the
sagcc update configuration data node_alias Universal-Messaging-umserver UM-QUEUES-queue_name -f xml -i absolute path to the XML file containing channel properties command.
Retrieve the configuration information of a specific channel using the
sagcc get configuration data node_alias Universal-Messaging-umserver UM-CHANNELS-channel_name command.
Retrieve the configuration information of a specific queue using the
sagcc get configuration data node_alias Universal-Messaging-umserver UM-QUEUES-queue_name command.
Examples:
To view all the configuration instances for a
Universal Messaging server instance:
sagcc get configuration instances sag01 Universal-Messaging-umserver
sag01 is the alias name of the installation where the Universal-Messaging-umserver server instance is running.
To create a channel on a
Universal Messaging server instance:
sagcc create configuration data sag01 Universal-Messaging-umserver
UM-CHANNELS -i C:\Channels\channel_create.xml
sag01 is the alias name of the installation where the Universal-Messaging-umserver server instance is running. UM-CHANNELS is the configuration type and channel_create.xml is an XML file containing the channel attributes of the new channel that is created.
Format of the channel_create.xml file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Channel>
<name>channel1</name>
<type>Persistent</type>
<ttl>0</ttl>
<capacity>0</capacity>
.......
</Channel>
To update a channel on a
Universal Messaging server instance:
sagcc update configuration data sag01 Universal-Messaging-umserver
UM-CHANNELS-channel1 -f xml -i C:\Channels\channel_edited.xml
sag01 is the alias name of the installation where the Universal-Messaging-umserver server instance is running. UM-CHANNELS-channel1 is the configuration type, in which channel1 is the name of the channel. channel_edited.xml is an XML file containing the channel attributes to be updated.
Format of the channel_edited.xml file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Channel>
<name>channel1</name>
<type>Persistent</type>
<ttl>50000</ttl>
<capacity>50000</capacity>
<deadEventStore/>
<engine>JMS Engine</engine>
......
</Channel>
To create a queue on a
Universal Messaging server instance:
sagcc create configuration data sag01 Universal-Messaging-umserver
UM-QUEUES -i C:\queues\queue_create.xml
sag01 is the alias name of the installation where the Universal-Messaging-umserver server instance is running. UM-QUEUES is the configuration type and queue_create.xml is an XML file containing the attributes of the new queue.
Format of the queue_create.xml file:
To update a queue on a
Universal Messaging server instance:
sagcc update configuration data sag01 Universal-Messaging-umserver
UM-QUEUES-queue1 -f xml -i C:\queues\queue_edited.xml
sag01 is the alias name of the installation where the Universal-Messaging-umserver server instance is running. UM-QUEUES-queue1 is the configuration type, in which queue1 is the name of the queue. queue_edited.xml is an XML file containing the queue attributes to be updated.
Format of the queue_edited.xml file:
To retrieve configuration information about a specific channel:
sagcc get configuration data sag01 Universal-Messaging-umserver
UM-CHANNELS-channel1
sag01 is the alias name of the installation where the Universal-Messaging-umserver server instance is running. UM-CHANNELS-channel1 is the configuration type, in which channel1 is the name of the channel.
To retrieve configuration information about a specific queue:
sagcc get configuration data sag01 Universal-Messaging-umserver
UM-QUEUES-queue1
sag01 is the alias name of the installation where the Universal-Messaging-umserver server instance is running. UM-QUEUES-queue1 is the configuration type, in which queue1 is the name of the queue.
Cluster Configuration
Before you create or update a Universal Messaging cluster:
Make sure the server instances that you want to add to the cluster are running.
Verify that the permissions on the server machines allow connections to the other servers in the cluster.
Make sure the /naming/defaultContext channel exists only on one or none of the nodes that will form the cluster. The
Universal Messaging server instance used as a JNDI provider uses the /naming/defaultContext channel to store JMS references and JNDI objects. If channels exists on multiple nodes, you cannot create the cluster.
If you have created custom composite templates for
Command Central 9.9 or earlier, ensure that you remove the
Universal Messaging server instance name suffix from COMMON-CLUSTER configuration type in the composite template when applying the composite template in
Command Central 9.10 or later. For example,
In Command Central 9.9 and earlier:
um-cluster:
description: Cluster configuration for two UM instances
products:
NUMRealmServer:
${node.host}:
instance.port: ${um.instance.port}
instance.ip: ${um.host}
runtimeComponentId: Universal-Messaging-${instance.name}
configuration:
Universal-Messaging-${instance.name}:
COMMON-CLUSTER:
COMMON-CLUSTER-${instance.name}: &umClusterConfig
Name: ${um.cluster}
Servers: # two UM instances cluster
Server:
-
"@name": ${um.host}
URL: "nsp://${um.host}:${um.instance.port}"
-
"@name": ${um.host2}
URL: "nsp://${um.host2}:${um.instance.port2}"
In Command Central 9.10 and later:
um-cluster:
description: Cluster configuration for two UM instances
products:
NUMRealmServer:
${node.host}:
instance.port: ${um.instance.port}
instance.ip: ${um.host}
runtimeComponentId: Universal-Messaging-${instance.name}
configuration:
Universal-Messaging-${instance.name}:
COMMON-CLUSTER:
COMMON-CLUSTER: &umClusterConfig
Name: ${um.cluster}
Servers: # two UM instances cluster
Server:
-
"@name": ${um.host}
URL: "nsp://${um.host}:${um.instance.port}"
-
"@name": ${um.host2}
URL: "nsp://${um.host2}:${um.instance.port2}"
Create a Universal Messaging cluster:
To create an active/active cluster of Universal Messaging server instances, input the cluster configuration details in an XML file to the sagcc create configuration data command.
Configure... | By specifying... |
Cluster name | Cluster name that is unique to an installation. |
Server instances | Name, URL, and port of each server node. |
Sites (Optional) | Name of the site to which each server node belongs. siteName is a server level property. |
Primary site (Optional) | Name of the primary site, if you have configured sites in the cluster. primeSite is a cluster level property that holds the name of the site, which is flagged as isPrime. |
To create a new cluster with the following configurations specified in the umSalesClusterConfig.xml file:
Cluster name: umSales
Cluster sites: site1 and site2
Primary site: site1
Server instances in site1: um9000, um9001
Server instances in site2: um9002, um9003
sagcc create configuration data sag01 Universal-Messaging-um9001
COMMON-CLUSTER --input C:\inputxmls\umSalesClusterConfig.xml
where sag01 is the alias name of the installation where Universal-Messaging-um9001 server instance is running. The cluster configurations are specified in the umSalesClusterConfig.xml file as shown:
To retrieve the following details of the Universal Messaging cluster in an XML file, specify one of the server instances of the cluster in the sagcc get configuration data command.
Name of the cluster
Name, URL, and port of each
Universal Messaging server instance in the cluster
Site information, if sites are configured
Example when executing on Command Central
To view the details of the cluster configuration of the um9001 Universal Messaging server instance:
sagcc get configuration data sag01 Universal-Messaging-um9001 COMMON-CLUSTER
where sag01 is the alias name of the installation where Universal-Messaging-um9001 server instance is running.
To update a Universal Messaging cluster:
The XML file used for configuring a cluster must contain all the specifications for the cluster. When you update a cluster, you only edit the parameters that specify the change; other specifications in the cluster configuration file should not be changed. You can make these Universal Messaging cluster configurations changes:
To... | Edit the cluster configuration XML file to... |
Add one or more server instances to the existing cluster | Include the name, URL, and port of the server instances that you want to add to the cluster. |
Remove one or more server instances from the existing cluster | Remove the specifications of the server instances that you want to remove from the existing cluster. |
Create sites and assign server instances to sites | Set the siteName extended property of the corresponding server instances. |
Assign a site as the prime site of a cluster | Assign the name of the prime site to the primeSite cluster level property. |
Remove one or more server instances from a cluster site | Remove the siteName extended property of the corresponding server instances. |
Remove sites from a cluster | Remove the site definitions of all the server instances in the cluster. |
Usage notes:
A Universal Messaging server instance can be part of only one cluster.
If you remove all the server instances from a site, the site will be deleted. Server instance deletion is not allowed if the deletion operation leaves less than two server instances in the cluster
Example when executing on Command Central
To update the configuration of the cluster that contains the um9001 server instance:
sagcc update configuration data sag01 Universal-Messaging-um9001
COMMON-CLUSTER --input C:\inputxmls\umSalesClusterConfig.xml
where sag01 is the alias name of the installation where Universal-Messaging-um9001 server instance is running.
To delete Universal Messaging cluster:
You delete the cluster by specifying one of the server instances of the cluster by using the sagcc delete configuration data command.
Example when executing on Command Central
To delete the cluster that contains the um9001 server instance:
sagcc delete configuration data sag01 Universal-Messaging-um9001
COMMON-CLUSTER
where sag01 is the alias name of the installation where Universal-Messaging-um9001 server instance is running.
Monitoring Channels and Queues
You can retrieve information about channels and queues using the following commands:
View the list of administration namespaces using the
sagcc get administration component node_alias Universal-Messaging-umserver command.
Retrieve all the configuration information about a channel in XML format using the
sagcc get configuration data node_alias Universal-Messaging-umserver UM-CHANNELS-channel name command.
Retrieve information about the options available for monitoring channels using the
sagcc get administration component node_alias Universal-Messaging-umserver channels command.
List the channels on a
Universal Messaging server instance using the
sagcc get administration component node_alias Universal-Messaging-umserver channels list command.
Retrieve the status of a specific channel in TSV format using
sagcc get administration component node_alias Universal-Messaging-umserver channels status name=channel name command.
Retrieve a list of durable subscribers on a specific channel in TSV format using the
sagcc get administration component node_alias Universal-Messaging-umserver channels durablesubscribers name=channel name command.
Delete a durable subscriber subscribed to a channel using
sagcc exec administration component node_alias Universal_Messaging-umserver channels deletedurablesubscriber name=channel_name durablesubscriber=durable subscriber nameExamples:
To view the list of administration namespaces:
sagcc get administration component sag01 Universal-Messaging-umserver
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running.
To retrieve all the configuration information about a channel:
sagcc get configuration data sag01 Universal-Messaging-umserver
UM-CHANNELS-channelname
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. UM-CHANNELS is the configuration type and channelname is the name of the channel from which the information is to be retrieved.
To retrieve information about the options available for monitoring channels:
sagcc get administration component sag01 Universal-Messaging-umserver channels
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running.
To retrieve the list of channels on a
Universal Messaging server instance:
sagcc get administration component sag01 Universal-Messaging-umserver channels
list
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. list is the command to list all the channels in a server instance.
To retrieve the status of a specific channel in TSV format:
sagcc get administration component sag01 Universal-Messaging-umserver channels
status name=channel_name
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running.channel_name is the channel name for which the status is to be retrieved.
To retrieve a list of durable subscribers on a specific channel in TSV format:
sagcc get administration component sag01 Universal-Messaging-umserver channels
durablesubscribers name=channel_name
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. channel_name is the name of the channel from which the durable subscribers list is to be retrieved.
To delete a durable subscriber subscribed to a channel:
sagcc exec administration component sag01 Universal_Messaging-umserver channels
deletedurablesubscriber name=channel_name durablesubscriber=durable_subscriber_name
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. channel_name is the name of the channel, and durable_subscriber_name is the name of the durable subscriber that has to be deleted from this channel.
Monitoring Durable Subscribers
You can monitor durable subscribers using the following commands:
View the list of administration namespaces using the
cc get administration component node_alias Universal-Messaging-umserver command.
Retrieve information about the options available for monitoring durable subscribers using the
cc get administration component node_alias Universal-Messaging-umserver durablesubscribers command.
Retrieve the list of durable subscribers of an
Universal Messaging server instance using:
sagcc get administration component node_alias Universal-Messaging-umserver durablesubscribers list -f xml command for XML format.
sagcc get administration component node_alias Universal-Messaging-umserver durablesubscribers list -f tsv command for TSV format.
sagcc get administration component node_alias Universal-Messaging-umserver durablesubscribers list -f csv command for CSV format.
Retrieve the attributes of a specific durable subscriber using:
sagcc get administration component node_alias Universal-Messaging-umserver durablesubscribers details channel=channel_name name=durable subscriber name -f xml command for XML format.
sagcc get administration component node_alias Universal-Messaging-umserver durablesubscribers details channel=channel_name name=durable subscriber name -f TSV command for TSV format.
sagcc get administration component node_alias Universal-Messaging-umserver durablesubscribers details channel=channel_name name=durable subscriber name -f CSV command for CSV format.
Retrieve specific attributes of the durable subscribers using the
cc get administration component node_alias Universal-Messaging-umserver durablesubscribers list -f tsv or csv properties=comma separated attribute list command.
Delete a durable subscriber using the
sagcc exec administration component node_alias Universal-Messaging-umserver durablesubscribers delete channel=channel_name name=durable subscriber name Examples:
To list all the administration namespaces:
sagcc get administration component sag01 Universal-Messaging-umserver
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running.
To retrieve information about the options available for monitoring durable subscribers:
sagcc get administration component sag01 Universal-Messaging-umserver
durablesubscribers
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running.
To retrieve the list of durable subscribers in a
Universal Messaging server instance:
XML format
sagcc get administration component sag01 Universal-Messaging-umserver
durablesubscribers list -f xml
TSV format
sagcc get administration component sag01 Universal-Messaging-umserver
durablesubscribers list -f tsv
CSV format
sagcc get administration component sag01 Universal-Messaging-umserver
durablesubscribers list -f csv
To retrieve attributes of the durable subscribers:
XML format
sagcc get administration component sag01 Universal-Messaging-umserver
durablesubscribers details channel=channelname name=durable_subscriber_name
-f xml
TSV format
sagcc get administration component sag01 Universal-Messaging-umserver
durablesubscribers details channel=channelname name=durable_subscriber_name
-f tsv
CSV format
sagcc get administration component sag01 Universal-Messaging-umserver
durablesubscribers details channel=channelname name=durable_subscriber_name
-f csv
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. channelname is the name of the channel, and durable_subscriber_name is the name of the durable subscriber from which the attributes are to be retrieved.
To retrieve the attributes specific attributes of a durable subscriber:
sagcc get administration component sag01 Universal-Messaging-umserver
durablesubscribers list -f tsv properties=name,channel,lastEventID,
outStandingEvents
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. name, channel, lastEventID, and outStandingEvents are attribute values to be retrieved.
To delete a durable subscriber:
sagcc exec administration component sag01 Universal-Messaging-umserver
durablesubscribers delete channel=channelname name=DS3
sag01 is the alias name of the installation where Universal-Messaging-umserver server instance is running. channelname is the name of the channel on which the durable subscriber exists, and durablename is the name of the durable subscriber.
Inventory
sagcc get inventory components and sagcc list inventory components gets and lists Universal Messaging inventory:
The commands retrieve information about the Universal Messaging server instances configured in the Universal Messaging_directory \server directory in an installation. Information from all the folders under the server directory, except templates, is displayed.
Property | Value |
Display name | Universal-Messaging-ServerInstanceName |
Run-time component ID | Universal-Messaging-ServerInstanceName |
Product ID | NUMRealmServer |
Run-time component category | PROCESS |
Note: ServerInstanceName can include upper and lower case alphabetic characters, digits (0-9), and underscores (_) but cannot include hyphens (-), periods (.), and colons (:).
Lifecycle Actions
The following table lists the actions that Universal Messaging supports with the sagcc exec lifecycle command and the operation taken against a Universal Messaging server when an action is executed.
Action | Description |
start | Starts theUniversal Messaging server instance. When successful, the Universal Messaging server instance run-time status is set to ONLINE. |
stop | Stops the Universal Messaging server instance. The Universal Messaging server run-time status is STOPPED. |
restart | Stops, then restarts the Universal Messaging server instance. The Universal Messaging server run-time status is set to ONLINE. |
Key Performance Indicators
sagcc get monitoring runtimestate and sagcc get monitoring state commands provide information about the following key performance indicators (KPIs) for a Universal Messaging server instance:
KPI | Description |
JVM memory usage | Indicates the utilization of JVM memory. The KPI uses the following marginal, critical, and maximum values: Marginal is 80% of the maximum JVM memory. Critical is 95% of the maximum JVM memory. Maximum is 100% of the maximum JVM memory. |
Fanout backlog | Indicates the total number of events currently waiting to be processed by the fanout engine. If the fanout backlog is more than the critical value, there is a possibility that the subscribers receive the published events after some delay. The KPI uses the following marginal, critical, and maximum values: Marginal is 80% of the maximum value. Critical is 95% of the maximum value. Maximum is 100% of the peak value (high-water mark) of fanout backlog. Default is 100. |
Tasks queued for read and write | Indicates the total number of tasks in the read, write, and common read/write pools. If the number of read and write tasks queued is more than the critical value, it indicates that the Universal Messaging server instance is unable to match the speed of the publishers and subscribers. The KPI uses the following marginal, critical, and maximum values: Marginal is 80% of the maximum value. Critical is 95% of the maximum value. Maximum is 100% of the peak value (high-water mark) of read and write tasks queued. Default is 100. |
For more information about the
Universal Messaging server instance KPIs, see information about monitoring
Universal Messaging server instance in
Universal Messaging Run-time Monitoring Statuses.
Run-time Monitoring Statuses
sagcc get monitoring runtimestatus command lists the run-time statuses for a Universal Messaging server instance, the following table lists the run-time statuses.
Note: Universal Messaging server instance does not return the STARTING and STOPPING statuses.
Run-time Status | Meaning |
ONLINE | Universal Messaging server instance is running. |
FAILED | Universal Messaging server instance is not running due to some failure. LOCK file exists. |
STOPPING | Universal Messaging instance is being stopped. LOCK file exists. |
STOPPED | Universal Messaging server instance is not running because it was shut down normally. LOCK file does not exist. |
UNRESPONSIVE | Universal Messaging server instance does not respond to a ping operation. LOCK file exists and the Universal Messaging server instance is running. |
UNKNOWN | The status of Universal Messaging server instance cannot be determined. |
Migrating a Universal Messaging Server Instance
Ensure that the target Universal Messaging has the migration utility installed.
For information about the migration utility, see Upgrading Software AG Products.
Note: These commands must be run in the context and order documented in Upgrading Software AG Products. Otherwise, you may experience unpredictable results, possibly including corruption of your installation and data.
View the command line help for the migration utility using the
sagcc list administration product node_alias NUMRealmServer migration help command.
Migrate all Universal Messaging server instances present in a source installation using
sagcc exec administration product node_alias NUMRealmServer migration migrate srcDir=SAG_Installation_directory command.
Note: Use this command when migrating from Universal Messaging server version 9.8 and later.
Start migration by providing the source
Universal Messaging instance name using the
sagcc exec administration product node_alias NUMRealmServer migration migrate srcDir=SAG_Installation_directory instanceName=instance_name[,instance_name,instance_name...] command .
Note: Use this command when migrating from Universal Messaging server version 9.8 and later.
Start migration by passing arguments and using the migrate.dat file using the
sagcc exec administration product node_alias NUMRealmServer migration migrate srcDir=SAG_Installation_directory importFile=migrate.dat command.
Note: Use this command when migrating from Universal Messaging server 9.0 through 9.7. The arguments silent is set to true and continueOnError is set to false by default.
Start migration using the Zip file from the old product installation using the
sagcc exec administration product node_alias NUMRealmServer migration migrate srcFile=old_installation.zip importFile=migrate.dat command.
Start migration using the Zip file from the old product installation and specifying the source
Universal Messaging instance name using
sagcc exec administration product node_alias NUMRealmServer migration migrate srcFile=old_installation.zip instanceName=instance_name[,instance_name,instance_name...] command.
View APIs under the migration namespace using the
sagcc list administration product node_alias NUMRealmServer migration command.
View if
Universal Messaging supports migration as a custom API using the
sagcc list administration product node_alias NUMRealmServer command.
Examples:
To view command line help:
sagcc list administration product sag01 NUMRealmServer migration help
sag01 is the alias name of the installation where NUMRealmServer server instance is running. migration is the namespace for the custom Command Central API. Help is the command to view the migration tool's command line help.
To migrate all
Universal Messaging server instances present in a source installation:
sagcc exec administration product sag01 NUMRealmServer
migration migrate srcDir=C:\SoftwareAG
sag01 is the alias name of the installation where NUMRealmServer server instance is running. migration is the namespace for the custom Command Central API. migrate is the command to access the migration tool. scrDir is the source Software AG installation directory.
To start migrating an older server instance to a new
NUMRealmServer server instance by providing the source instance name:
sagcc exec administration product sag01 NUMRealmServer
migration migrate srcDir=C:\SoftwareAG
instanceName=umserver1,umserver2
sag01 is the alias name of the installation where NUMRealmServer server instance is running. migration is the namespace for the custom Command Central API. migrate is the command to access the migration tool. scrDir is the source Software AG installation directory. instanceName is the comma separated names of the Universal Messaging instances that are to be migrated.
To start migrating an older server instance to a new
NUMRealmServer server instance using the migrate.dat file:
sagcc exec administration product sag01 NUMRealmServer
migration migrate srcDir=C:\SoftwareAG
silent=true importFile=migrate.dat
sag01 is the alias name of the installation where NUMRealmServer server instance is running. migration is the namespace for the custom Command Central API. migrate is the command to access the migration tool. scrDir is the source Software AG installation directory. importFile specifies the data file containing the migration settings.
To start migration using the Zip file from the old product installation:
sagcc exec administration product sag01 NUMRealmServer
migration migrate srcFile=99Src.zip importFile=migrate.dat
sag01 is the alias name of the installation where NUMRealmServer server instance is running. migration is the namespace for the custom Command Central API. migrate is the command to access the migration tool. scrFile argument is used to provide the name of the Zip file from the source Universal Messaging instance. importFile specifies the archive file path containing migration settings.
To view APIs under the migration namespace for the
NUMRealmServer server instance:
sagcc list administration product sag01 NUMRealmServer migration
sag01 is the alias name of the installation where NUMRealmServer server instance is running.
To view if
Universal Messaging supports migration as a custom API:
sagcc list administration product sag01 NUMRealmServer
sag01 is the alias name of the installation where NUMRealmServer server instance is running.