Unity Connection Tenant Manager


Overview. 1

Requirements/Special Notes. 1

Connecting to Unity Connection 10.x or Later 2

Using Tenant Manager 2

Overview – What is a “Tenant” 2

Routing Inbound Calls To Tenants. 2

Adding a New Tenant 4

Removing a Tenant 4

Managing Tenants. 4

Obtaining Updates. 4

Revision History. 4


The Tenant Manager tool is designed to assist in creating groups of objects in Unity Connection that provide a basic "tenant services" application.  In short it allows you to create a tenant which includes numerous interrelated database objects in Connection that work together to provide basic directory segmentation features to allow for isolated groups of users and handlers within your Connection server.  Be sure to review the "What is a Tenant" section below for some more details on what's meant here.


Requirements/Special Notes

The Tenant Manager requires Unity Connection 10.0(1) or later.  For creating tenant routing based on dialed number instead of phone system assignment, 11.0 or later is required.

This version of Tenant Manager runs on Windows 2012 server, Windows 7, Windows 8 or Windows 10. 

This tool uses Microsoft’s full .NET 4.5 library (the limited “client” version of .NET 4.5 is not sufficient).  The installation will check to see if you have that installed.

NOTE: You cannot create tenants on a Unity Connection server that has users created on it already – it is only allowed in a dedicated tenant setup, you cannot mix non tenant and tenant users on the same installation.

Connecting to Unity Connection 10.x or Later

Tenant Manager uses HTTP based REST protocols to communicate with Connection so only HTTPS via port 443 is required - no ODBC driver needs to be installed on the client and no ODBC proxy configuration is necessary on the server.

You need only to authenticate with an account that has the system administrator role associated with it to use the tool.

NOTE: the feature to remove “damaged” tenant installs that do not remove cleanly via REST is offered and it does require ODBC access to Unity Connection to work – this feature is optional however.

Using Tenant Manager

Overview – What is a “Tenant”

When we use the term "tenant", what are we talking about, exactly?  A "tenant" is basically a small voice mail setup for a sub-company within your larger Connection server.  In other words if you had 4 companies sharing a single Connection server for voice mail services, you can set each one up as a separate "tenant" in your install which effectively isolates them from one another.

The key aspects to a tenant is that each one is given their own set of routing rules, default operator and opening greeting call handlers, operator subscriber, schedule, switch assignment, partition and search space along with a few other things.  The idea is you map the switch assignment for that "tenant" to some ports on your phone system and inbound calls get routed to users and handlers within that tenant.  Once a call is in that tenant's partition they cannot access handlers or users outside of items assigned to that tenant.

The same is true for users assigned to that tenant.  They cannot address to users or public distribution lists that are not assigned to that tenant.  Their outbound notification devices use only the ports assigned to that tenant on the phone system integration.  They are effectively an "island" within your Connection server.

To be clear Connection has had the ability to configure such setups since the 8.0 release.  However the steps for managing the configuration are numerous and complex and highly error prone - this tool is designed to automate much of that and provide an easier way for administrators to create and manage such configurations.

Be sure to review the next section to understand what the limitations are here.

Routing Inbound Calls to Tenants

Before we discuss the process of creating and managing tenant collections, lets briefly review the call routing path for identifying calls as being assigned to a tenant - this is the most critical piece of functionality and needs to be understood up front to determine if you will be able to leverage the Tenant Manager in your environment.

When you create a new tenant using the Tenant Manager, by default a new phone system instance is created in Connection and assigned exclusively to that tenant.  By default no ports are configured for it, it's just a switch instance that is then assigned to routing rules and all users/handlers created for that tenant.  It's up to you to define the ports and hook it up to your phone system.

For versions of Unity Connection prior to 11.0 this is the only way Tenant Manager allows you to assign inbound calls to a tenant.  It's also important to note that MWI activity and phone based notification devices will also leverage that tenant's switch definition for users assigned to that tenant - keep this in mind when deciding how many ports to assign.

Connection can support numerous phone system definitions - so having each tenant assigned their own is not a problem from that perspective but it does entail extra work for the admin to configure and may require you configure additional port ranges on your Communications Manager for instance.

NOTE: For Unity Connection 11.0 and later you have the option to route calls to tenants using dialed number mapping instead (i.e. all tenants are on a single phone system definition).  This is not the default routing mechanism, the phone system assignment is still recommended.  If you choose to route based on dialed number you run the risk of busy tenants “starving” less busy tenants out and there may be no ports available for handling inbound calls for them among other things.  If you go this route, keep a very close eye on port usage during peak times.

In addition to the switch definition above, each tenant gets its own set of routing rules (two direct and two forwarding rules).  The direct routing rules page for a system with four tenants configured on it is shown here:

Notice that the routing rules are assigned to the tenant's Phone System definition - so those rules will only trigger for calls that come in on that phone system and no other.  In short the calls will route to the opening greeting call handler constructed for that tenant, log a user assigned to that tenant into their mailbox or forward a call to the greeting for a user/handler in that tenant. 

Of course you can create additional routing rules "by hand" assigned to that phone system but be sure to make sure they route to an object for that tenant and are assigned to the partition for that tenant or you'll cause all kinds of havoc in the routing process.


Adding a New Tenant

Simply hit the "Create New Tenant" button on the main application form and you are presented with the Create New Tenant form which requires three items to create a new tenant:

The description, alias and SMTP Domain name must all be unique among tenants in your system. 

The alias is used as a prefix for all objects created in the tenant - used to make sure all objects in Connection are uniquely named. 

NOTE: The option to create a tenant using a pilot number for routing is only active if you are attached to a Unity Connection 11.0 or later system.

Removing a Tenant

Press the "Delete Tenant" button on the main form and the option to select a tenant to remove is presented.

Note that when deleting a tenant, ALL OBJECTS associated with that tenant are deleted as well.  This means all users, call handlers, interviewers, schedules, COS etc... are deleted.  There is NO UNDO for this.  Make sure you really want to remove a tenant and all its objects before doing so.

NOTE: If a tenant has had critical data removed or changed it can result in the REST based removal chain breaking.  If an error occurs during removal via REST, you will get an optional checkbox asking if you’d like to remove the tenant’s data via ODBC instead.  This will log in via ODBC and manually remove data from all the tables that contain references to the tenant including users, handlers, schedules, phone systems, COSes, routing rules etc… This should always work regardless.  If you use this option you must be using an account that has the Remote Database Access role associated with it and your ODBC Proxy Service must be turned on for the Unity Connection server you are attaching to or it will fail.

Managing Tenants

Press the "Manage Tenants" button on the main form and the main tenant management interface is presented.


This allows you to view and, in some cases, add new objects to a tenant.  Note that you cannot delete objects in the manage tenants view.

In all cases you can double click on an object and the full CUCA web interface will be presented for that object for you to edit or delete if you like.

For Users, Call Handlers, Distribution Lists, Interview Handlers, Directory Handlers, Schedules Classes of Service, User Templates and Call Handlers templates you can view and add new items to the tenant via this interface.

For Phone System, routing Rules, Partitions and Search Spaces you can only view items. 


Obtaining Updates

To check for updates to this tool, visit http://www.CiscoUnityTools.com

Revision History

Version 2.0.8 – 8/8/2017

·         Updated project to .NET 4.5 framework

·         Updated NuGet libraries

·         Added support for choosing either pilot number routing or phone system assignment routing for new tenants

·         Added support for manually removing tenant data from database via ODBC when a tenant object is damaged or a dependency was removed and the REST based removal fails.

Version 2.0.5 – 4/7/2014

·         Added additional debug output for logging.

·         Plumbed in error event handling to back end REST SDK – log file may have semi-redundant error output but some errors that cannot be caught in the UI thread will be noted for troubleshooting purposes

·         Fixed minor display issue with versions that involve TT or ES release string details

·         Removed references to ODBC SDK used for pilot number routing beta work.

·         Updated SQLite and JSON.NET libraries to be the latest from NuGet

·         Updated setup package.

Version 2.0.4 – 2/3/2014

·         Updated for trunk based routing on 10.x installations – pilot number routing will be available in 10.5 release trains for Connection.

Version 2.0.2 – 11/3/2013

·         Updated version parsing/checking routine to handle non digit strings beyond expected “ES” designations to handle non production release designations such as “TT” and the like.

Version 2.0.1 – 10/17/2013

·         Added logic to do post tenant creation work to setup for “shared port group” model instead of tying each tenant to a specific phone system/port group.

Version 1.0.3 - 6/18/2013

·         Added compound query option for call handler fetches so only system handlers are returned.

·         Fixed UI issue where grid was not updating properly when moving between users and handlers and back quickly.

Version 0.0.1 – 5/13/2013

·         First internal beta drop of tool


© 2014 Cisco Systems, Inc. -- Company Confidential