Cisco Unity Connection add delete contacts via CUPI example

This is a sample of how to add and / or delete contacts in the Unity Connection database using the CUPI interface.

This was created using Python 3.6.2 and Cisco Unity Connection 12.5.

This script was created after finding Extension was a required field in the Unity Connection BAT process and needs to be unique, creating challenges in environments where single DNs may need multiple names associated with them.

Ultimately I found the Extension field in the BAT file can simply be left blank.

With that, I would suggest using the built in Unity Connection BAT process to manage contacts when possible.  

Unity Connection provides the ability to add contacts manually and via the Bulk Administration tool GUI but there are some limitations.

When adding Unity Connection contacts manually, only the Alias (unique) and the DisplayName is required. When adding Unity Connection contacts via Bulk Administration, an Alias (unique) and Extension (unique) is required. A problem arises when you only want to leverage Unity Connection contacts as additional directory entries, and where you might have multiple names or spellings for the same transfer destination.

Manually, you can add as many contacts as you require with variations of DisplayNames, all using the same TransferNumber, as the TransferNumber does not need to be unique. If you are managing thousands of DisplayName variations though (full names vs. acronyms vs. friendly names, etc.), manual entry is likely not acceptable.

Since BAT requires a unique Extension, if you enter it accurately you are required to still enter a TransferNumber, but now need to leverage multiple AlternateNames per contact to deal with name variations. This is undesireable as contact AlternateNames are not easily searchable via the GUI, and additionally User and Contact names can't be managed seperately if the extensions are the same.

For example, you may want need to manage directory entries for the President of the United Sates. Several years ago, the user BObama may have had extension 1111. This year, user DTrump may have the extension 1111. You might have historically had a directory entry (contact) with DisplayName POTUS with extension 1111. You might want a second directory entry (contact) with DisplayName P O T U S with extension 1111. You cannot add either contact with BAT, as a user already has that extension number. You can use AlternateNames in the User but when you delete and add a new user every four years, you need to remember to re-add all the asociated alternate names, which aren't searchable. If you choose to manage those more permanant AlternateNames in a contact and via BAT, you now need to create a bogus unique Extension for the contact and again manage unsearchable AlternateNames. If you want to be able to search for the AlternateNames, you need to BAT multiple contacts with multiple bogus Extesnsions and use the DisplayName in each instead.

None of this is perfect.

The CUC CUPI interface allows for bulk contact additions and deletions where Extension is not required.

This sample assumes your BAT file columns will be Alias, DisplayName, FirstName, LastName, TransferEnabled, TransferExtension and saved in UTF-8 format without BOM.

You can find my Github repository here: https://github.com/raymaslanka/Cisco-UCXN-CUPI-add-delete-contacts, or gist here:

Cisco CUACA Attendant Console Advanced Notes

Replication Issue:

Installing CUACA version 12.0.4.20-14 on Windows 2012 R2, SQL 2016 and using the CUACA High Availability (Resilient Installations) option.

I was presented with "Licensing information on publisher and subscriber servers is not in sync. Please validate replication configuration." after applying the correct Server, Sessions and Resilient Server licenses on the publisher.  Attempting to install replication via the CUACA GUI Replication drop down was a miserable failure.  A good visual of the steps required can be found here regardless: https://www.cisco.com/c/en/us/support/docs/unified-communications/unified-attendant-console-advanced/200513-Installation-of-Replication-for-CUAC-Adv.html 

Hostnames and FQDNS resolved, SQL servers were installed correctly, firewall exceptions were in order, sa passwords checked, administrator rights to servers were good, prerequisites were verified a dozen times, CUACA uninstalled and reinstalled with new DBs, etc. etc.

TAC finally found and supplied a DLL that needed to be replaced.  See CSCvp67232.  The DLL is DBComponent.dll, the modified date on the fixed version is Thursday, ‎May ‎23, ‎2019, ‏‎5:12:26 AM and it belongs in C:\Program Files (x86)\Cisco\Utilities\DB Component and C:\Program Files (x86)\Cisco\Attendant Admin\Web\Application\Bin.

Cool.  Replication still doesn't work. 

TAC insisted it was a firewall issue after they were unable to telnet to a port the servers were not listening on. That's not how that works, but you should probably double check yours anyway.

Ultimately I found a MS Application Error on the 2012 subscriber server in the cascading mess of errors indicating the local MS DTC detected that the MS DTC on has the same unique identity as the local subscriber server.  The error text indicates the servers were likely cloned in an unsupported method. This is not unlikely in this particular environment.

There is a brief reference to this in the latest troubleshooting guide but the link to Microsoft's website is broken and you do not need to reinstall CUAC.

The fix is running 'msdtc -uninstall' and 'msdtc -install' from a command line running as administrator on the subscriber server, reboot everything, uninstall and reinstall CUACA Replication and enjoy your day.

MS DTC error message

CUCM Synchronization Issue:

When defining a device to use as a template for CUAC Queue Devices, the Owner User ID on the CUCM template device appears to need a value.  If the Owner is left Anonymous in CUCM you will find an error code 9100 Function Parameter error in the CUCM Sync Report when the process is complete.  If you lucky enough to be synching lots of devices and impatient when running the report you might catch a better description of the culprit before it finishes.

Not a helpful description

Now this... this is a helpful description.

Transfer to voicemail:

In CUACA User Configuration | General Properties the Maximum internal device digit length needs to be long enough to include the DN length plus the voicemail prefix defined in the client under Options | Dialing.  For example, if are using +E.164 DNs and a prefix of 12345, you internal device digit length needs to be 18.

Find CUCM users that are LDAP inactive

Option 1: SQL via CUCM CLI

Note: status of 2 is inactive, 1 is active, and 0 is local

run sql select count(*) from enduser where status=2

run sql select userid, firstname, lastname from enduser where status=2

Option 2: simple lookup on newer CUCM versions

Note: not sure when this option was introduced

Find user where Is disabled local user 

Cisco CUCM BAT User Must Change at Next Login PIN option

Running 12.5.1.10000-22, you may need to change the end user credential option requiring "User Must Change at Next Login".  If you have a small subset of users that need to be changed and / or defaulting the PIN is not an issue, you can use  Bulk Administration | Users | Reset Password / PIN | Query.  The problem here is you need to enter a default PIN value to proceed, potentially creating issues for users that have already had documented PINs set for them in other bulk jobs.

End User Edit Credential

1. Bulk Administration | Import/Export | Export
2. Under User Data, check End User
3. Add Tar file name, check Run Immediately, do not Check Dependency, and Submit
4. Bulk Administration | Upload/Download Files
5. Find Tar file name above and download
6. Open enduser.csv in Tar file
7. Change PIN MUST CHANGE AT NEXT LOGIN 1 from t to f on rows required (can delete rows that are not required for faster processing)
8. Save enduser.csv but DO NOT SAVE AS UTF-8.  Excel will default to CSV (Comma delimited) (*.csv).  Although other jobs seem to require UTF-8 encoding, this particular job seems to fail if you save with Excel's CSV UTF-8 (Comma delimieted)(*.csv) option.

   

   Do NOT use UTF-8 here.

9. Add enduser.csv back into Tar file, overwriting existing copy.
10. Bulk Administration | Upload/Download Files
11. Add New, find Tar, choose Import/Export and Import configuration. 
12. Bulk Administration | Import / Export | Import
13. Choose Tar, then check End User, check Override the existing configuration, check Run Immediately and Submit.

BAT Job Scheduler Success Sample

BAT Job Scheduler Failure Sample

Cisco VG350 BAT to add or update lines

It's 2019 and whether you like it or not we still have to support analog endpoints.  Adding them manually in any sort of quantity is awful.

Cisco TAC has a nice write up on what's required here: https://www.cisco.com/c/en/us/support/docs/unified-communications/bulk-administration-tool/118882-config-vg-00.html  I suspect it's a matter of time before that link breaks though and I've added some detail to steps below that seems to trip everyone up.

Update the device and line level configuration of ports on an existing Cisco voice gateways via BAT

1. Navigate to your CUCM administration at https://YourServerName
2. Choose Bulk Administration | Import/Export | Export. 
3. Under Device Data, choose Gateway. 
4. Select a filename, Run Immediately and Submit
5. Choose Bulk Administration | Upload/Download files. 
6. Choose the .tar file you created above and download.
7. Make a backup copy.
8. Extract the .tar file using 7zip to a folder and open the .csv file.
9. The port and the DN configurations are to be entered under the section Entity:ANALOG.
1. Optional: If you want to avoid updating or overwriting existing gateway and port configurations, you can remove the gateways, inventory and ports from the gateway.csv that you want to ignore.
1. Remove all the gateways from Entity:GATEWAY except for those you are updating.
2. Remove all the inventory from Entity:SLOTCONFIGURATION except that related to the gateways you are updating, where GATEWAY NAME = DOMAIN NAME.
3. Remove all the ports from Entity:ANALOG except those you are updating or adding.

   

   CUCM Gateway BAT export and edited import file

10. All the columns need to be updated in this section.
1. You can increment the PORT NUMBER column within a slot and subunit
2. You can increment the last two ENDPOINT NAME characters in hex
3. The DESCRIPTION field should be 50 characters or less.
4. The LINE DESCRIPTION 1 field should be 50 characters or less.
5. Apostrophes in the LINE DESCRIPTION, ALERTING NAME, etc. will result in errors like 'AN695ABCDEFABCDEF' A syntax error has occurred. but seem to be accepted regardless.
11. Save the .csv file with the same name and in the same folder where you extracted the .tar file.
1. The gateway and header files should be encoded and / or saved as UTF-8 to allow for special characters in gateway names.
12. Use 7zip to create a new .tar file of this folder.  You can alternatively simply add the edited csv back into the original downloaded tar file.
1. The tar file should include a folder of the same name.  The header and gateway files should then reside in that folder.  They shouldn’t be in the root of the tar file.
13. Choose Bulk Administration | Upload/Download files | Add New. 
14. Choose the .tar file, choose the target as Import/Export, choose the Transaction Type as Import Configuration, and click Save.
15. Choose Bulk Administration | Import/Export | Import. Choose the .tar file uploaded above and then Next.
16. Under Device Data, choose Gateway and toggle "Override the existing configuration" as required. Run the job.