Unity Connection Message Archiver CLI

Contents

Overview. 1

Selecting Users. 2

Messages Backed Up. 2

Using HTTP Based CUMI 2

Limitations using HTTP instead of IMAP: 3

Requirements/Special Notes. 3

Connecting to Unity Connection 7.x or Later 3

Task 1: Configure a User without a mailbox with the Remote Administrator and System Administrator roles  3

Task 2: Set the Database Proxy Service Shutdown Time. 3

Task 3: Activate the Remote Database Proxy Service. 4

Troubleshooting Remote Login Issues. 4

Double Check Connection Server Settings. 4

Disable CSA and all Virus Scanning Applications. 4

Make sure the Informix .NET Driver is Installed and the PATH Points to it. 5

Trouble with Initial Unity Connection Login. 5

Message Extraction Problems. 5

Revision History. 6

Overview

This is the command line version of the Message Archive utility – it provides the same functionality but can be run against multiple users selected in one of 3 ways and issued from schedulers or run via BAT files automatically.

When running scheduled be sure to include the “-i false” option to disable interactive mode so the application will exit automatically without waiting for user input to continue.

 

 Command line options:

 

a:AllUsers                         If true all users on the target server have their messages backed up.

b:BannedUsers                List of user aliases to exclude from a backup - usually used with -a

c:CxnServer                     Server name or IP address of Connection Server to attach to

s:CxnServerSecondary    Server name or IP address of secondary Connection server to attach to

d:DeletedMsg                   Include deleted messages. Default true.

f:FileOfUsers                    CSV file name containing user aliases of mailboxes to back up.

h:HTTPRest                     Use HTTP based CUMI for message extraction instead of IMAP

i:Interactive                       Set to true and the console will wait for user input to continue.

l:LoginName                     Login name to use attaching to the Connection server

p:Password                       Password to use attaching to the Connection server

r:BackupRootFolder         Root folder for message backups

u:UserAliases                   List of one or more alias strings to backup mailboxes for.

w:WaitAfterMessageCalc If true the app will pause after calculating message count/space

y: Limit messages to this many days old or newer only. Defaults to all messages

 

Examples:

 

[Backup messages for all users on server including deleted, non interactive]

MessageArchiverCli -c 10.29.118.72 -l admin -p password -i false -a

 

[Backup messages for all users except operator on server including deleted, non interactive]

MessageArchiverCli -c 10.29.118.72 -l admin -p password -i false –a –b operator

 

[Backup undeleted messages for selected aliases]

MessageArchiverCli -c 10.29.118.72 -l admin -p password -d false -u jsmith sjohnson xavierd

 

[Backup all messages for aliases in csv file]

MessageArchiverCli -c 10.29.118.72 -l admin -p password -f c:\userAliases.csv

 

Selecting Users

You may select users by alias in 1 of 3 ways:

·         Use “-a” to get all users on the target server.  If this option is enabled it will ignore the other 2 options and proceed with all users.  This option also allows the optional “-b” to include specific users to skip such as operator and undeliverablemessagesmailbox.

·         Use the “-u” option with a list of one or more user aliases.  If this option is found it will use it and ignore the CSV option.

·         Finally you can use the “-f” followed by the full path to a CSV file containing a column named “alias” that contains the alias of users on the server to include.  Any other columns that may appear in the file will simply be ignored.

 

Messages Backed Up

The message archiver backs up messages for users in the “Messages” folder created where the Message Archiver is installed – each user gets a folder using their alias under “Messages” and all messages are stored as EML files which can be opened by most email readers including Outlook, Outlook Express, Thunderbird and others.

All messages are stored “in the clear” – there is no encryption on the messages pulled from Connection.

The Message Archive tool will look at messages already backed up before deciding which ones to download.  Thus running the tool multiple times will never pull down messages that are already present on your system which greatly reduces overhead on the system and speed of backup.

By default deleted messages are included in the backup – use the “-d false” option to turn that off.

Using HTTP Based CUMI

By default the Message Archiver uses IMAP to extract messages from Unity Connection and store them as EML files on your target repository location.  If you have an “unrestricted” installation of Unity Connection, access to messages via IMAP is prohibited by design so this cannot be used.  In this case you can use the “-h” parameter to have the archiver instead fetch messages via HTTP REST protocols.  NOTE: this is considerably slower than IMAP and should only be used when you have no other choice.

If you have messages marked secure you want to archive off via HTTP you must configure the API to allow this to happen – by default it’s restricted.  Under Advanced | API Settings in the Unity Connection administration interface you need to check the “Allow Access to Secure Message Recordings through CUMI” option.  If not, you will get an error on all secure messages the application tries to export.

Limitations using HTTP instead of IMAP:

The message archiver is designed to use IMAP – using HTTP is only there for sites that have no other choice (i.e. they have an unrestricted installation of Connection which does not allow for IMAP connections).  There’s a few things to note about what you lose going with HTTP CUMI for backing up messages:

1.     It’s considerably slower (around 3 to 5 times slower) than IMAP

2.     It only gets voice mail, no other message types.  This includes read receipts, emails, NDRs, faxes or any other message types.

3.     For messages with transcriptions, the transcription text is stored as a text attachment file for the message (along with the usual WAV file attachment for the voice mail) – for IMAP this is embedded in the body type.

Requirements/Special Notes

The message archiver is built using .NET 4.5.  If you are running Windows 7 or later, likely this version or later is already installed.

You need to install the Informix 4.x or later SDK (32 bit – regardless of the OS you’re installing on).  Be sure to include the ADO.NET drivers as well as ODBC.

You need to log into Unity Connection with an account that has both the “Remote Administrator” and “Mailbox Access Delegate Account” roles.

You need to be sure your ODBC Proxy service is enabled on the Connection server (see the next section).

Connecting to Unity Connection 7.x or Later

For installations of 7.0(1) and later you need to use the database proxy service for access to the database from off box for any DB tool including User Data Dump.

Task 1: Configure a User without a mailbox with the Remote Administrator and System Administrator roles

1.     Go to the Cisco Unity Connection Administration web interface for your installation.

2.     You can leverage a user with or without a mailbox for off box data access purposes, but it’s suggested that you create a new user without a mailbox that is used solely for the purpose of remote administration tasks for security reasons.

3.     Be sure the web administration password for this user is not configured to require a change at first login on the “Password Policy” page for that user.

4.     If necessary, change the web administration password on the “Change Password” page.  Note that only the web application password comes into play for remote data access.

5.     Finally, on the “Role” page for the user, add the “Remote Administrator” and the “System Administrator” roles to the “Assigned Roles” list and save.  You can assign any or all other roles as well but for the purposes of remote access to the database and making updates to users those two are necessary.

Task 2: Set the Database Proxy Service Shutdown Time

NOTE: For Unit Connection 10.0(1) and later this step is not necessary as there is no longer a Database Proxy Service Shutdown Time.

Out of the box the database proxy service is not running and if you try to start the service it will shut down right away.  First you need to set the “Database Proxy: Service Shutdown Timer” value found in the System Settings -> Advanced -> Connection Administration section of the Cisco Unity Connection Administration page.  By default this is 0.  You can set it to as high as 999 days if you like.  After the number of days configured here the remote database proxy service will shut down.  This is useful if you want to do some migration work, for instance, and don’t want to forget to have the service disabled for security reasons.

NOTE: If you restart the server on versions prior to Unity Connection 10.0(1), the remote database proxy service will remain shut off.  After a system restart you have to go in and manually turn on the service again (see step 3)

Task 3: Activate the Remote Database Proxy Service

1.     Out of the box the service that listens to remote database requests is not active, you must turn it on.  To do this, go to the “Cisco Unity Connection Serviceability” web admin page.

2.     On the Tools menu, select the “Service Management” page.

3.     The “Connection Database Proxy” item under the “Optional Services” section will be marked as “Deactivated” and stopped.  Press the “Activate” button and it will be activated and started automatically.

Once you’ve started the proxy service you can connect with any tool that needs off box database access using the user name, web administration password and port “20532”.

NOTE:  For versions of Unity Connection prior to 10.0(1) the service will automatically shut down after the number of days configured in step 2 above or if you restart the server.

Troubleshooting Remote Login Issues

The error message issued by the application should have some details for you on the failure reason based on the error codes issued by the Informix driver to help narrow down your investigation.  Here’s some general things to check that have been run across in the field for sites having trouble connecting to their remote Connection servers.

Double Check Connection Server Settings

Make sure the remote database proxy service is running.  This service does shut itself off after a period of time and does not start itself automatically on a server reboot.

Make sure the user you are logged in as has the remote administrator role assigned to their account, that their password is not set to reset at the next login and that their account is not currently locked. 

Make sure the server name or IP address you are using to connect with is reachable from your Windows client.  DNS issues often come up in connection failures.

Disable CSA and all Virus Scanning Applications

It’s a good idea to disable CSA and all virus scanning applications if you are having problems connecting to be sure the ODBC port (20532) is not being blocked.  Also check your firewall settings (assuming you are running one). 

Make sure the Informix .NET Driver is Installed and the PATH Points to it.

For 32 bit OS installs, the IBM Informix driver is installed in C:\Program Files\IBM\Informix\Client-SDK.  Make sure this path exists on your server and has not been removed or renamed.

The system PATH variable will also include a reference to the “\IBM\Informix\Client-SDK\bin” location where the driver is installed.  Make sure this path is referenced in the PATH.  Also, if the PATH is very long sometimes the Informix driver will not find it, try moving it to the beginning of the PATH statement.

If you had an older version of the IBM Informix Client SDK installed it's a good idea to uninstall all other versions and make sure you have a single instance of the SDK 3.5 or later.  Mixing versions of Informix drivers is not a good idea as only one can be active at a time.

Trouble with Initial Unity Connection Login

If the initial login to Unity Connection fails then there is a problem making the ODBC connection.  These are the two most common errors you’ll see:

·         Unspecified System Error = -27001”.  This means it was able to find the server and attach to the ODBC proxy service but the service rejected the credentials you supplied.  This can be due to the wrong login name or password for your remote user account or it could be that the account is locked out or that the password settings have the “must change password at next login” value set.  The latter is the default value for the password settings on Connection installs and is a common failure reason – be sure you uncheck this.

·         Unspecified System Error = -908”.  This means the server name is wrong or the ODBC Proxy service is not responding.  The former is often a DNS issue – be sure name resolution is pointing where you think it is.  The latter usually means the service is not running properly on the target server or that the port being used (20532) is being blocked between your Windows client you’re running on and the target Connection server.

·         Error -11048”.  This can sometimes mean that the PATH environment variable in Windows is too long – try moving the INFORMIXDIR/bin reference to the beginning of the PATH variable.  Also make sure only one version of the ODBC driver is installed on this client machine.

Message Extraction Problems

The most common problem encountered after initial connection completes has to do with message extraction. Couple things to note here:

    1. Please check and double check that you do not have a virus scanning package installed on the Windows server you are running on.  This is by far the most common problem.  By default they will block use of port 7993 (IMAP) and message access will fail if that’s the case.
    2. Make sure there is no firewall either on the Windows server or between the Windows server and the Connection server blocking port 7993 (for secure IMAP used for export).
    3. For message extraction in COBRAS export be sure you are using Connection 7.0(2) or later.  Also make sure you are connecting to the server using a user _without_ a mailbox.
    4. If you have verified that the above do not apply, turn on all SMTP and MTA traces on the Connection server and gather the Message Archive log and the Connection logs and provide them to the TAC engineer you’re working with.

Revision History

Version 1.0.12 – 1/11/2018

·         Added option to restrict backups by message age

·         Added additional logging output for message extraction

Version 1.0.10 – 7/20/2017

·         Added option to extract messages using HTTP CUMI instead of IMAP for unrestricted installations of Unity Connection.

·         Added date to log file name for easier tracking

·         Updated summary message information at the end of the output log

Version 1.0.9 – 7/14/2017

·         Fixed issue iterating over multiple mailstores if defined in the target Connection server.

·         Fixed issue for sites using “mixed case” for their user aliases that was skipping some mailboxes when gathering messages to archive

·         Fixed issue handling special characters in alias names such as * when extracting messages via IMAP

Version 1.0.6 – 6/13/2017

·         Fixed issue with SQLite database failing to open via UNC path in some cases

Version 1.0.5 – 11/1/2016

·         Added secondary Connection server option to fail over to if login to the primary server fails.

·         Changed output to console to exclude progress bars when no running in interactive mode to prevent issues piping output to a text file in non interactive mode

Version 1.0.4 – 10/31/2016

·         First release of application

Version 1.0.1 – 10/4/2016

·         First beta release of the CLI version of Message Archiver

 

© 2018 Cisco Systems, Inc. -- Company Confidential