Table Of Contents
Installation Guide for the Cisco Unified Application Environment
Messaging Plugin, Release 2.5(1) SR1Understanding System Requirements
Performing Pre-Installation Tasks
Installing the Cisco Unified Application Environment
Messaging Plugin and Messaging Plugin ServiceInstalling the Messaging Plugin Developer Tools
Performing Post Installation Tasks
Managing Messaging Plugin Configuration Options
Connecting the Messaging Plugin Server to the
Cisco Unified Application EnvironmentConnecting to the Management Service
Configuring the Plugin Host Server Connection
Configuring the Etch Bridge Connection
Encrypting the Management Service Password
Troubleshooting Installation Error Messages
Obtaining Documentation and Submitting a Service Request
Installation Guide for the Cisco Unified Application Environment
Messaging Plugin, Release 2.5(1) SR1
Revised: January 1, 2009, OL-18463-01
Use this document to install the Cisco Unified Application Environment Messaging Plugin.
Contents
•
Installing the Cisco Unified Application Environment Messaging Plugin and Messaging Plugin Service
•
Installing the Messaging Plugin Developer Tools
•
Performing Post Installation Tasks
•
Managing Messaging Plugin Configuration Options
•
Troubleshooting Installation Error Messages
•
Obtaining Documentation and Submitting a Service Request
Conventions
Consider the following documentation conventions as you review this installation document:
Blue Text—To quickly navigate to a section or URL, click text that appears in blue.
Note
Reader, take note. Notes contain helpful suggestions or references to material not covered in the publication.
CautionReader, be careful. You may do something that could result in equipment damage or loss of data.
Related Documentation
There are two types of related documentation: product and developer.
•
Table 1 provides links to product documentation.
•
For developer documentation, go to: http://developer.cisco.com/web/cuae/docs
Table 1 Related Documentation
Related Information URLCisco Unified Application Environment Installation Guide, Release 2.5.1
http://www.cisco.com/en/US/products/ps7058/prod_installation_guides_list.html
Cisco Unified Application Environment Administration Guide, Release 2.5.1
http://www.cisco.com/en/US/products/ps7058/prod_maintenance_guides_list.html
Cisco Unified Application Environment Release Notes, Release 2.5.1 SR1
http://www.cisco.com/en/US/products/ps7058/prod_release_notes_list.html
Cisco Unity Support and Documentation
http://cisco.com/en/US/products/sw/voicesw/ps2237/tsd_products_support_series_home.html
Cisco Unity Connection Support and Documentation
http://www.cisco.com/en/US/products/ps6509/tsd_products_support_series_home.html
Before You Begin
This section contains the following topics to help you prepare to install the Cisco Unified Messaging Plugin:
•
Understanding System Requirements
•
Performing Pre-Installation Tasks
Choosing an Installer
The Messaging Plugin components enable developers to build applications that interact with Cisco Unity and Cisco Unity Connection, Release 7.0.
There are two installers:
•
Messaging Plugin Installer (CUAE-messaging-plugin-2.5.x.exe)—
Communicates with Cisco Unity or Cisco Unity Connection servers or a cluster or servers and allows developers to call functions that support reading and sending voicemail.•
Developer Tools Installer (CUAE-messaging-plugin-dev-tools.2.5.x.exe):
–
Messaging Plugin API—The etch IDL required for developing applications that utilize the Messaging Plugin Service.
–
Messaging Plugin Documentation—API reference documentation.
Understanding System Requirements
The Messaging Plugin components have the following system requirements:
For information about downloading and installing the most recent version of the Cisco Unified Application Environment and Development Tools, see the Cisco Unified Application Environment Installation Guide, Release 2.5.1 listed in Related Documentation.
Performing Pre-Installation Tasks
Table 3 describes the pre-installation tasks that you must complete before starting the Messaging Plugin installation.
Note
The Developer Tools installation does not require you to complete any pre-installation tasks.
Table 3 Pre-Installation Tasks
Task Pre-Installation Tasks Important Notes1.
![]()
For Messaging Plugin installations, make sure the Cisco Unified Application Server is running and you can connect to it over the network.
None.
2.
![]()
Make sure you have the information required for installation.
See the following tables for a list of the information you need about each of the systems:
•
The Cisco Unified Application Server — See Table 4
•
The Messaging Plugin Host Server — See Table 5
•
The Cisco Unity Server — See Table 6 and Table 7
•
The Cisco Unity Connection Server — See Table 6 and Table 8
3.
![]()
Make sure you know which connection protocol is used by the Management Service and the Etch Bridge.
For information about connection protocols, see Connecting the Messaging Plugin Server to the Cisco Unified Application Environment.
Installing the Cisco Unified Application Environment
Messaging Plugin and Messaging Plugin ServiceTo install the Cisco Unified Application Environment Messaging Plugin and Messaging Plugin Service, follow these steps:
Procedure
Step 1
Access the Messaging Plugin installer on the Cisco Unified Application Environment Release 2.5.1 SR1 DVD or download it from the Cisco Unified Application Environment wiki. The Messaging Plugin installer is named CUAE-messaging-plugin-2.5.x.exe.
Step 2
Double-click the installer.
The Messaging Plugin Setup Wizard appears.
Step 3
Click Next.
The end-user license agreement appears.
Step 4
Read the end-user license agreement, and if you agree with the terms, select I Agree.
The Choose Install Location dialog appears.
Step 5
Accept the default or click Browse to locate a new destination for the Plugin files. Click Next when you finish selecting the install location.
The Choose Start Menu Folder dialog appears.
Step 6
Accept the default or create a new Start menu shortcut path for the Messaging Plugin Developer Tools. Click Next.
The Cisco Unified Application Server Settings dialog appears.
Step 7
Enter the following setting information as described in Table 4. Provide the requested information for each field and click Next.
Table 4 Cisco Unified Application Server Settings
Field Description/RecommendationDomain Name/IP Address
Fully qualified domain name or IP address of the Cisco Unified Application Server.
Management Service Port
Port on the Cisco Unified Application Server used for the Management Service listener.
Username
Cisco Unified Application Environment Administration interface user name.
Password
Cisco Unified Application Environment Administration interface password.
Use TLS
Select this check box if you are using TLS for installation. The connection method must correspond to the method configured on the Management Server. See Connecting to the Management Service.
Authenticate
Select this check box if you are using TLS authentication. See Connecting to the Management Service.
Trust Store
Path to the truststore where you have imported the Management Service TLS certificate. See Connecting to the Management Service.
The Messaging Plugin Host Settings dialog appears.
Step 8
Enter the following setting information as described in Table 5. Provide the requested information for each field and click Next.
The Cisco Unity/Cisco Unity Connection Settings dialog appears.
Step 9
The required fields depend on which setting you choose for the Server Type. Table 6, Table 7, and Table 8 describe all fields. Enter the information as prompted and click Next.
Table 6 Cisco Unity/Cisco Unity Connection Shared Settings
Field Description/RecommendationDomain Name/IP Address
Enter the host name or IP address of the Unity Connection or Unity server.
Server Type
Select Cisco Unity or Cisco Unity Connection. If you select Cisco Unity, enter the values for the fields in Table 7. If you select Cisco Unity Connection, enter the value for the fields described in Table 8.
Table 7 Cisco Unity Settings
Field Description/RecommendationUnity Domain
The Active Directory domain created for the machine running the Unity Server. For more information about Active Directory domains, see the following article: http://technet.microsoft.com/en-us/library/cc739093.aspx
Step 10
The Installation dialog window indicates progress as the installation proceeds. When complete, the Completing the Messaging Plugin Setup Wizard screen appears.
Step 11
Select Reboot Now or I want to manually reboot later.
Step 12
Click Finish to close the Setup Wizard.
Note
After installation completes, you must perform post-installation tasks. For more information, see Performing Post Installation Tasks.
Installing the Messaging Plugin Developer Tools
To install the Messaging Plugin Developer Tools, follow these steps:
Procedure
Step 1
Access the Messaging Plugin installer on the Cisco Unified Application Environment Release 2.5.1 SR1 DVD or download it from the Cisco Unified Application Environment wiki. The Messaging Plugin Developer Tools installer is named CUAE-messaging-plugin-dev-tools.2.5.x.exe.
Step 2
Execute the installer.
Step 3
The Messaging Plugin Developer Tools Setup Wizard appears. Click Next.
The end-user license agreement appears.
Step 4
Read it, and if you agree with the terms, select I Agree.
The Choose Components dialog appears.
Step 5
Select to install either the API or Documentation or to install both.
Step 6
Click Next.
The Choose Start Menu Folder dialog appears.
Step 7
Accept the default or create a new Start menu shortcut path for the Messaging Plugin Developer Tools. Click Next.
Note
You can alternatively choose not to create a Start menu shortcut by clicking Do not create shortcuts.
Step 8
The Installation dialog window indicates installation progress. Click Next when the installation is complete.
Step 9
Click Finish to close the Setup Wizard.
Performing Post Installation Tasks
This section contains the following topics to help you perform post-installation tasks:
Verifying the Plugin Service
To verify that the plugin service was properly installed, follow these steps:
Procedure
Step 1
Log in to the Cisco Unified Application Environment Administration interface.
Step 2
Choose Plugins > List Plugins.
The messaging plugin appears in the list of installed plugins. If it does not, check the installation logs to determine if there was an error during installation. For more information about troubleshooting, see Troubleshooting Installation Error Messages.
Starting the Plugin Service
The Messaging Plugin service does not start automatically after installation. The service must be running to enable applications to send and receive voice messages from the Unity or Unity Connection servers.
To start the Messaging Plugin service, follow either of the following procedures:
Procedure
Step 1
Choose Start > Cisco Systems > Messaging Plugin > Start Messaging Plugin Service.
Note
•
If you selected a different shortcut in the Messaging Plugin installer, enter that path instead.
•
The shortcut is not available if you selected the Do not create shortcuts option in the Plugin Service installer.
Procedure
Step 1
Choose Start > Control Panel > Administrative Tools > Services.
Step 2
Click the CUAE Messaging Plugin service.
Step 3
On the Action menu, click Start.
Setting the Logs To Roll
After installation, it is highly recommended that you set the Messaging Plugin logs to roll to prevent log files from growing too large to manage.
To set the logs to roll, follow these steps:
Procedure
Step 1
Open the Messaging Plugin configuration file. By default, the file is stored here:
C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\messaging-plugin.conf.Step 2
Locate the Wrapper Logging Properties section of the file.
Step 3
Change the value for the following setting to a number greater than 0:
wrapper.logfile.maxsize=0
Step 4
Restart the Messaging Plugin Service.
Note
Cisco Unified Application Environment Messaging Plugin uses a third-party tool—the Tanuki Software Java Service Wrapper configuration file—to control the various wrapper settings, including logging. For more information about the logging properties, see the documentation on the Tanuki Software website: http://wrapper.tanukisoftware.org/doc/english/prop-logfile.html
Managing Messaging Plugin Configuration Options
The following topics describe additional tasks related to the Messaging Plugin, which are not required to be performed immediately after installation.
•
Connecting the Messaging Plugin Server to the Cisco Unified Application Environment
•
Encrypting the Management Service Password
Connecting the Messaging Plugin Server to the
Cisco Unified Application EnvironmentThe Messaging Plugin, like any etch-based plugin or application, can run on any machine that has network access to the Cisco Unified Application Environment. As such, it is highly recommended that you secure all connections between the Messaging Plugin host machine and the Cisco Unified Application Environment because the nature of voicemail messaging requires a high level of privacy.
This section contains the following topics to help you configure connections between the Cisco Unified Application Environment and the Messaging Plugin:
•
Connecting to the Management Service
•
Connecting to the Etch Bridge
•
Configuring the Plugin Host Server Connection
•
Configuring the Etch Bridge Connection
Connecting to the Management Service
The Messaging Plugin installer connects to the Cisco Unified Application Environment Management Service using either TCP or Transport Layer Security (TLS) depending on the options you select in the Messaging Plugin installation process. You must select the protocol used by the Management Service in your deployment. TLS is enabled on the Management Service by default, but can be disabled by the administrator. Therefore, you should contact your administrator to find out whether to use TCP or TLS.
If you select Use TLS and Authenticate during installation, the installer prompts you for the location of the truststore, so you must first import the Management Service TLS certificate to a truststore before running the Messaging Plugin installer.
For more information about the Management Service TLS certificate, see the Cisco Unified Application Environment Administration Guide, Release 2.5.1 listed in Related Documentation.
Connecting to the Etch Bridge
After installation, when the plugin runs, there are two different connections that can use TCP or TLS:
•
The connection from the Messaging Plugin to the Etch Bridge
•
The connection from the Etch Bridge to the Messaging Plugin
The configuration options and steps to configure differ depending on the connection.
TLS or TCP is used for connections between plugins and the Etch Bridge. Figure 1 illustrates the connections between the components.
Figure 1 Plugin and Application Connections to the Etch Bridge
Technically a plugin can act as both a server and client of the Etch Bridge.When the plugin connects to the Etch Bridge to use methods exposed by the Cisco Unified Application Environment, the plugin acts as the client and the Etch Bridge is the server.
When the Etch Bridge connects to the plugin as a proxy for an application that is using the plugin's API, the plugin acts as the server and the Etch Bridge is the client.
Different connection strings within the plugin code control whether a connection uses TLS or TCP, and when TLS is used, whether the connection is encrypted or encrypted and authenticated.
Configuring the Plugin Host Server Connection
The Messaging Plugin passes the Etch Bridge a URL to use to connect back to the Plugin Server. In this scenario, the Etch Bridge is a client of the Plugin Host Server. Table 9 describes the steps required to configure this connection.
Table 9 Messaging Plugin Host Server Connection Options
Option StepsEncrypt the connection
None. By default, the Messaging Plugin installer creates a default TLS certificate and stores it here: C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\default.keystore. This causes TLS to be enabled on the Plugin Hosting Server. In addition, the PluginURL connection string, which is stored in C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\Configuration.xml, is set to use TLS encryption.
Authenticate the connection
1.
Export a certificate from the Messaging Plugin keystore using the keytool command
Note
For more information about using keytool, see http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html
2.
Copy the certificate to the truststore on the Cisco Unified Application Server and import it to a truststore, using keytool.
3.
On the Messaging Plugin server, open C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\Configuration.xml.
4.
Locate the PluginURL entry:
<entry key="PluginURL" value="tls://127.0.0.1:4001?TlsConnection.authReqd=false&TcpTransport.reconnectDelay=4000&filter=KeepAlive&Packetizer.maxPktSize=0"/>Save the file.5.
Remove the TlsConnection.authReqd=false parameter. This causes the EtchBridge to authenticate by default when connecting to the Messaging Plugin server:
<entry key="PluginURL" value="tls://127.0.0.1:4001?;TcpTransport.reconnectDelay=4000&filter=KeepAlive&Packetizer.maxPktSize=0"/>Save the file.6.
Save the file.
7.
Restart the CUAE Messaging Plugin service and the CUAE Application Server service.
Disable TLS; Use TCP
1.
Open C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\messaging-plugin.conf.
2.
Comment out the following lines:
wrapper.java.additional.2=-Djavax.net.ssl.keyStore="C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\default.keystore"
wrapper.java.additional.3=-Djavax.net.ssl.keyStorePassword=123456
wrapper.java.additional.4=-Djavax.net.ssl.keyPairPassword=1234563.
Save the file.
4.
Open C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\Configuration.xml.
5.
Locate the PluginURL entry:
<entry key="PluginURL" value="tls://127.0.0.1:4001?TlsConnection.authReqd=false&TcpTransport.reconnectDelay=4000&filter=KeepAlive&Packetizer.maxPktSize=0"/>Save the file.6.
Modify the URL to use TCP as the connection protocol:
<entry key="PluginURL" value="tcp://127.0.0.1:4001?;TcpTransport.reconnectDelay=4000&filter=KeepAlive&Packetizer.maxPktSize=0"/>Save the file.7.
Save the file.
8.
Restart the CUAE Messaging Plugin service and the CUAE Application Server service.
Configuring the Etch Bridge Connection
The Messaging Plugin connects to the Cisco Unified Application Environment Etch Bridge to register itself. In this scenario, the Plugin Host Server is the client of the Etch Bridge. Table 10 describes the steps required to configure this connection.
Note
You must select the protocol used by the Etch Bridge in your Cisco Unified Application Environment deployment. TLS is enabled on the Etch Bridge by default, but can be disabled by the administrator. Therefore, you should contact your administrator to find out whether to use TCP or TLS.
Table 10 Etch Bridge Server Connection Options
Option StepsEncrypt the connection
None. The EtchBridgeURL connection string in the C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\Configuration.xml uses TLS encryption by default.
Authenticate the connection
1.
Copy the Etch Bridge TLS certificate to the Messaging Plugin server and import it to a truststore, using keytool.
Note
For more information about using keytool, see http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html
2.
On the Messaging Plugin server, open C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\Configuration.xml.
3.
Locate the EtchBridgeURL entry:
<entry key="EtchBridgeURL" value="tls://192.0.2.0:9000?TlsConnection.authReqd=false&TcpTransport.reconnectDelay=4000&filter=KeepAlive&Packetizer.maxPktSize=0"/>Save the file.4.
Remove the TlsConnection.authReqd=false parameter, which will cause the Messaging Plugin server to authenticate by default when connecting to the Etch Bridge:
<entry key="EtchBridgeURL" value="tls://192.0.2.0:9000?;TcpTransport.reconnectDelay=4000&filter=KeepAlive&Packetizer.maxPktSize=0"/>Save the file.5.
Save the file.
6.
Restart the CUAE Messaging Plugin service and the CUAE Application Server service.
Disable TLS; Use TCP
1.
Open C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\Configuration.xml.
2.
Locate the EtchBridgeURL:
<entry key="EtchBridgeURL" value="tls://192.0.2.0:9000?TlsConnection.authReqd=false&TcpTransport.reconnectDelay=4000&filter=KeepAlive&Packetizer.maxPktSize=0"/>Save the file.3.
Modify the EtchBridgeURL to use TCP as the connection protocol:
<entry key="EtchBridgeURL" value="tcp://192.0.2.0:9000?;TcpTransport.reconnectDelay=4000&filter=KeepAlive&Packetizer.maxPktSize=0"/>Save the file.4.
Restart the CUAE Messaging Plugin service and the CUAE Application Server service.
Encrypting the Management Service Password
During installation, you are prompted to provide Cisco Unified Application Environment user credentials, which are used to log on to the Cisco Unified Application Environment Administration interface, as well as to authenticate with the Management Service and the Etch Bridge.
Initially, the password is written to the C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\configuration.xml file in plain text. When the Messaging Plugin service starts, it detects that the password is not encrypted and automatically encrypts it.
If you modify the username and password on the Management Service, you must modify the C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\configuration.xml file and set the password to be encrypted.
To set the password to be encrypted, follow these steps:
Procedure
Step 1
Open C:\Program Files\Cisco Systems\Messaging Plugin\Service\conf\configuration.xml.
Step 2
Locate the following entries:
<entry key="MgmtServiceUserName" value=""/>
<entry key="MgmtServicePassword" value=""/>
<entry key="MgmtEncryptPwd" value="true"/>Step 3
Replace the MgmtServiceUserName value with the new user name.
Step 4
Replace the MgmtServicePassword value with the new password.
Step 5
Set the MgmtServiceEncryptPwd value to false.
Step 6
Save the file.
Step 7
Restart the Messaging Plugin Service.
Troubleshooting Installation Error Messages
Table 11 describes installation error messages that might be displayed in the dialog boxes and log files during installation. The logs are located in:
•
C:\2.5.1.xxxxcisco_unified_application_environment_messaging_plugin-install.log
•
C:\2.5.1.xxxxcisco_unified_application_environment_messaging_plugin_dev_tools-install.log
Note
After verifying that the installation was a success, you can either delete or archive the log files.
Obtaining Documentation and Submitting a Service Request
For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What's New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at:
http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html
Subscribe to the What's New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0.
CCDE, CCENT, Cisco Eos, Cisco HealthPresence, the Cisco logo, Cisco Lumin, Cisco Nexus, Cisco StadiumVision, Cisco TelePresence, Cisco WebEx, DCE, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn and Cisco Store are service marks; and Access Registrar, Aironet, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, EtherFast, EtherSwitch, Event Center, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iPhone, iQuick Study, IronPort, the IronPort logo, LightStream, Linksys, MediaTone, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, Network Registrar, PCNow, PIX, PowerPanels, ProConnect, ScriptShare, SenderBase, SMARTnet, Spectrum Expert, StackWise, The Fastest Way to Increase Your Internet Quotient, TransPath, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries.
All other trademarks mentioned in this document or website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0812R)
Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.
© 2009 Cisco Systems, Inc. All rights reserved.


