Unity Connection Message Archiver CLI
Limitations
using HTTP instead of IMAP:
Connecting
to Unity Connection 7.x or Later
Task
2: Set the Database Proxy Service Shutdown Time
Task
3: Activate the Remote Database Proxy Service
Task
4: For Connection 12.x and Later Activate Secure IMAP
Troubleshooting
Remote Login Issues
Double
Check Connection Server Settings
Disable
CSA and all Virus Scanning Applications
Make
sure the Informix .NET Driver is Installed and the PATH Points to it.
Trouble
with Initial Unity Connection Login
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
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.
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.
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.
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.
By default CUPI will not allow secure messages to be exported off box – if you are using secure messages and you want those to be exportable by the Message Archiver using CUMI, you nave to turn on the option “Allow Access to Secure Message Recordings through CUMI” found in Advanced settings under the “API Settings” section. If you don’t turn this on, you’ll get “access denied” type errors coming back from the server for all secure messages it tries to export.
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).
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.
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
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)
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.
Connection 12.0 and later ship with secure IMAP connections turned off by default. For message extraction using IMAP in 12.0 and later you must:
1. Attach the server to a licensing service. You cannot turn on secure protocols for a server that is not licensed – as such you cannot extract messages via IMAP until you’ve licensed the server.
2. From the Unity Connection CLI logged in as an administrator you need to run the command “utils cuc encryption enable”. Once this is done successfully the secure IMAP connection used by COBRAS and other tools will be enabled.
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.
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).
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.
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.
The most common problem encountered after initial connection
completes has to do with message extraction. Couple things to note here:
Version 1.0.19 – 6/24/2023
· Fixed issue for Unity Connection Message Archiver CLI not fetching all messages for users.
Version 1.0.18 – 5/14/2020
· Fixed issue where CUMI backups using the -a parameter were using lower cased aliases fetched via ODBC instead of leaving the case as is from the query.
Version 1.0.17 – 6/10/2019
· Fixed issue with aliases being forced to lower case by the PathSafe string extension call – caused a problem when pulling messages via CUMI which is case sensitive as opposed to ODBC/IMAP which is not.
Version 1.0.16 – 1/28/2019
· Updated all dependency libraries and added new license unlock codes for the Chilkat software library
Version 1.0.15 – 9/17/2018
· Remove FK constraint on message id guid in the SQLite database
Version 1.0.14 – 6/11/2018
· Updated NuGet libraries for all sub projects
· Fixed issue with CSV parsing not getting header information correctly regardless of case.
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
© 2019 Cisco Systems, Inc. -- Company Confidential