The Bulk Password Edit tool allows for applying unique passwords (for GUI logins) and PINs (phone passwords) for users with mailboxes in the Unity Connection database using a CSV file as input. It can also be used to automatically generate random PINs (phone passwords) for selected users and generate a CSV file with the new values and email addresses of users. When creating large numbers of users it is often not desirable for them all to have the same password from a shared template or one set with the BulkEdit utility. The Bulk Password Edit tool allows the administrator to setup a CSV file with unique strings for these passwords that can then be applied in bulk or to generate random PINs for users in bulk. Conversely if the administrator does not want to provide a CSV, the Bulk Password Edit tool can generate random PINs and a CSV for you and you can then bulk email the generated PINs to users via the CSV output.

Requirements/Special Notes

This version of Bulk Password Edit runs on Windows XP/2000/2003/2008, Vista or Windows 7. When run on Vista or Windows 7 you may need to use the “as administrator” option when running the application.

This version of Bulk Password Edit requires .NET framework 2.0 or better. The install will detect if this needs to be installed and launch the setup automatically if it’s missing.

This version Bulk Password Edit only works with Unity Connection 7.0(1) or later.

Bulk Password Edit allows user password edits only for stand alone installations of Connection, not CoRes (Business Edition) installs.

You must enable the ODBC proxy service on the Unity Connection server and attach to the database using an account enabled for the remote database access role. See the next section for details on this.

You must first install the Informix ODBC drivers before using this tool. Many off box tools for Connection 2.1(1) and later use these same drivers and you only need to install them once per client machine. You can download the installer for this on its home page here: http://ciscounitytools.com/App_InformixDrivers.htm

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 tool that uses database access.

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 strongly suggested that you create a new user without a mailbox that is used solely for the purpose of remote administration tasks for security reasons. This is also required if you want to export messages from a Connection 7.0(2) or later server – a user with a mailbox may not be allowed to extract messages from other mailboxes, whereas a user without a mailbox should have no problem.

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

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, 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: The service will automatically shut down after the number of days configured in step 2 above or if you restart the server.

Task 4: Login to the Remote Server

When you select to connect to a remote server from Bulk Password Edit, you will see a login dialog box that will be empty except for port 20532 filled in as the default for the port. You must provide the server name or IP address for the “Server” field and provide the login and password for the database connection account. Use the alias and web administration password of the database user created above for the login and password fields.

Bulk Password Edit will remember your entries including the password (which is stored in a secure hash). Each time you run Bulk Password Edit it will load the settings of the last connection you made. Every server you’ve successfully connected to in the past will be listed in the drop down list in the order in which you connected to it last – most recent to least recent.

NOTE: The login and password information is stored along with the local Windows login name. Only those servers that have been attached to successfully using the current Windows login will be listed. If you are logging into the same Windows server with different users you will only see servers connected to with that particular Windows login.

NOTE: Providing the wrong password or login will fail quickly and give you a chance to try a different pair. Providing an incorrect server or port, however, results in a 60 second timeout while Bulk Password Edit waits for the Informix ODBC driver to return. Unfortunately this cannot be shorted. Type carefully.

Troubleshooting Tips

Double Check Connection Server Settings

If you are attaching to a remote Connection server for import or export, 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.

Review the Connecting to Unity Connection 7.0(2) and Later section above.

Disable CSA and all Virus Scanning Applications

For Windows based systems (all Unity versions and Connection 1.2) it’s a good idea to disable CSA and all virus scanning applications if you are having problems running either exports or imports for either local Unity versions or remote Connection 7.x and later servers. CSA and various virus scanning packages often block access to ports necessary to attach to remote servers and file systems and/or create local files and the like. Before escalating a failure be sure to make sure this basic issue is not tripping you up since TAC will usually first start here.

Disable or Edit your Firewall Settings

Make sure this application is allowed to communicate externally and that port 20532 (for ODBC access) is open for use.

Trouble with Initial Unity Connection Login

If the initial login to Unity Connection for either import or export 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 COBRAS 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 COBRAS 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.

Using Bulk Password Edit

The Bulk Password Edit is a simple 4 page wizard that walks you through the process of changing passwords and/or PINs via CSV or generating random PINs and outputting them to CSV

Page 1: Intro

The first page of the wizard lets you select which function you wish to perform.

If you have a CSV file with user information (alias and/or extension at a minimum) along with PINs and/or passwords you wish to apply to those users, select the “Update user PIN and/or passwords from a CSV import file” radio button and hit next. To follow the pages in the wizard for this page, go to “Page 2: Update Passwords from CSV – Selecting a CSV File” and proceed from there.

If instead you want the Bulk Password Edit tool to randomly generated PINs for selected users, update their PINs in Connection and then output that information to a CSV file, select the “Generate random PINs for users and write them to a CSV file” radio button and hit Next. To follow the pages in the wizard for this page, go to “Page 2: Generate Random PINs – Selecting a CSV File” and proceed from there.

Page 2: Update Passwords from CSV - Selecting a CSV File

This tool allows users with mailboxes to be selected only by CSV file – the file must contain an Alias and/or extension number for the user and a PIN and/or a password to be applied to that user.

The column headers in the CSV file that are searched for in the first line of the file (comma separated) are:

ALIAS – the alias of the subscriber you wish to apply a new PIN and/or Password to.
EXTENSION – the extension of the subscriber (primary or alternate) you wish to apply a new PIN and/or Password to.
PIN – a new phone password for a user. Must be all digits.
PASSWORD – a new web application password for a user.

The file must contain either an ALIAS and/or an EXTENSION column AND a PIN and/or PASSWORD column. It may contain all four, of course, but one of each is required.

If the file contains other columns they will be ignored during processing.

When loading users into the grid the alias is used to search by first. If a match is found, the tool stops. If a match is not found or an alias is not provided on the line then the extension will be searched for.

If either a valid PIN or Password is not provided on a line, it will be skipped during processing.

You must select at least one user in the grid before proceeding – you can select all users by clicking on the ckeckbox in the upper left of the grid control in the header – this will automatically select all or deselect all alternately.

NOTE: Bulk Password Edit does NOT evaluate all passwords and PINs for validity against any given authentication rule that users may be assigned to. As long as the strings pass basic content requirements (for instance PINs are all digits) it will attempt to apply them using the stored procedures provided by Connection. If a password fails to pass all the authentication requirements (length, repeated credentials, trivial check etc…) the stored procedure will not apply the new password and an error will be returned. Bulk Password Edit includes this error in the “FAILURE_REASON” column of the CSV file it creates to hold all failures during processing. Read through the failure reason string and it should be obvious why the PIN or Password did not get applied.

The CSV Failure file created has the same file name and location as the CSV file you select for import, however it’s appended with the year, month, day, hour, minute and second along with “failure.csv”. Each line that produced a failure during processing will have the ALIAS, EXTENSION, PIN, PASSWORD and FAILURE_REASON columns in it. If your input file had other columns they will not show up in the failure CSV file.

You may adjust values found in the file and/or adjust password policy settings for those users and then reapply those passwords using the failure CSV file as an input.

Page 3: Update Passwords from CSV - Options

You may force common password related settings to be applied to all users that you edit passwords for. You could do this via BulkEdit as well, however it’s provided here as a convienence since it may be desirable, for instance, to force all user’s to have to change their password at the next login if they are not already configured for that.

NOTE: By default none of the “Override value” check boxes are checked which means none of these settings will be touched – whatever the users are configured for currently is what they will have when the tool is done. Only if you select one or more of the “Override value” boxes (which enables the corresponding value that will be forced) will any changes be made.

Page 4: Update Passwords from CSV- Execute

You can select the “Reset” button at the top and observe progress output on this page.

When the tool is complete you will be given the opportunity to review the log file output and, if there was one or more errors during processing you will be given the opportunity to open and review the error entry output CSV file.

NOTE: The above shot shows a common error you may see in the output – the password or PIN length provided in the CSV file did not meet the minimum required by the corresponding authentication rules. You’ll want to make sure you adjust the authentication rules appropriately based on the values you’re importing.

Page 2: Generate Random PINs - Selecting a CSV File

This page allows you to select one or more users to get randomly generated PINs applied to their Connection account and have that information output to a CSV file for review and distribution to users.

Only users with mailboxes local to the Connection server are allowed to be selected on this page (i.e. you cannot change PINs for users that are homed on another Connection server this is networked with this one).

You can select users with the following search options:

· All Local Users

· Users in this class of service. Select a COS in the drop down box that shows up with this option and hit the “Add” button.

· Users in this extension range. Enter a starting and ending extension range and hit the “Add” button.

· Users in this CSV file. Select a CSV file that contains a column titled “EXTENSION” and or “ALIAS” and users with be searched for by one or both of those fields for selection.

· Users associated with this phone system. Select a phone system from the drop down that shows up with this option and all users assigned to that system will be added to the grid.

· Users with this string in their display name. You can any string and all users that contain all or part of that string in their display name will be added to the grid. The search is not case sensitive.

· Users in this public distribution list. Select a public distribution list and all users with mailboxes on the local Connection server in the top level of that list will be added to the grid. Note that this is NOT a recursive search meaning it will not look into members of other public lists included in the selected public list.

· Users in this search partition. Select a search partition and all users on the local Connection server assigned to that partition will be added to the grid.

· Users have MD5 hash for their PIN. Any user that has a PIN in the old MD5 hash style will be added to the grid. Users that were imported from an older Unity installation or that were in the system and upgraded to a later version of Connection and have never updated their PIN may have MD5 hash password styles. If implementing FIPS these PINs will no longer work and need to be updated to SHA1 style. This function is provided to make that easier on the administrator.

Once you’ve selected at least one user in the grid, you can hit the “Next” button move on.

Page 3: Generate Random PINs – Options

This page lets you select options for PINs that are generated for users selected on the previous wizard page. The length of the randomly generated PIN can be established here as well as some override PIN options applied to all selected users.

You may force common PIN related settings to be applied to all users that you randomly generate PINs for. You could do this via BulkEdit as well, however it’s provided here as a convenience since it may be desirable, for instance, to force all user’s to have to change their password at the next login if they are not already configured for that.

If you wish to have uniform length of your PINs make sure the minimum and maximum PIN lengths are set to match. The minimum PIN length is pulled from the default authentication rule for TUI and the maximum can be up to 20 digits long.

IMPORTANT: The Random PIN Length minimum is established by the “Recommended Voice Mail Authentication Rule” in the Authentication Rules section of the CUCA. If you are using a custom rule for your TUI authentication rules for your users then make sure the minimum PIN length is long enough to produce valid PINs for all rules users are associated with. The PIN application will fail if the length of the PIN is shorter than the applicable authentication rule – the Bulk Password Edit tool cannot override this behavior.

Page 4: Generate Random PINs – Execute

When you execute a random PIN generation task the first thing Bulk Password Edit will do is generate a CSV file for the output to go. This will default to using the name “BulkPasswordReset_” followed by the Connection server name followed by the date and time down to the minute followed by “csv” to help ensure uniqueness. This will go into the “CSV” folder under the installation directory for the tool. You can, of course, choose a different location and different file name if you prefer but the default settings should ensure unique file names for each run.

The output of the CSV file will look like this when the application finishes:

ALIAS, FIRST_NAME, LAST_NAME, EXTENSION, DISPLAY_NAME, PIN, CORPORATE_EMAIL

testGuy1,Test,Guy1,9001,Test Guy 1,958062, tguy1@lindborglabs.com

TestGuy2,Test,Guy2,9002,Test Guy 2,024915, tguy2@lindborglabs.com

The Corporate Email field is not a required field to be filled in so it may be blank for some users. This is the email address that users are checking email for (as opposed to voice mail) and is the only useful email address to output since the SMTP address of the Connection mailbox cannot be used for general email purposes and, of course, requires a login anyway.

The run of the PIN generation function looks like this:

You can select the “Reset” button at the top and observe progress output on this page.

Obtaining Updates

To check for updates to this tool, visit http://www.CiscoUnityTools.com or you can use the “Check for updated versions” link found in the About dialog box of this application.

Revision History

1.0.14 – 6/29/2016

· Fixed issue searching by alias if an apostrophe appears in the alias.

· Fixed handling searches with missing alias correctly when falling back on extension only.

· Updated Infragistics binaries to ver 15.2

Version 1.0.0.13 – 1/21/2016

· Fixed issue with CSV parsing when randomly generating PINs for users

Version 1.0.0.12 – 1/1/2016

· Updated installation to allow Windows 10 deployments

Version 1.0.0.11 – 11/12/2013

· Added new option for email random PIN changes out to users’ corporate email addresses

Version 1.0.0.9 – 1/20/2013

· Updating for Windows 8 installations

Version 1.0.0.7 – 4/18/2011

· Fixed a problem with resetting only Passwords and not PINs when importing changes via CSV.

· Add function to randomly generate PINs for users and construct a CSV file with the user data and new PIN included in it.

Version 1.0.0.3 – 9/27/2010

· Fixed a problem when one or more of the 4 CSV parameters were not passed in with bogus “object does not exist” errors during the CSV file parsing routines.

Version 1.0.0.2 – 7/22/2010

· Changed to qSetup platform.

· Updated installation to handle x64 installs properly

Version 1.0.0.1 – 3/18/2010

First beta release