Document ID: 116226
Updated: Jun 21, 2013
Contributed by Tray Stoutmeyer, Cisco TAC Engineer.
This document provides information on the use of the Cisco Unity Connection Bulk Administration Tool (BAT) in order to import user contact lists into Cisco Unified Presence Server (CUPS). BAT allows you to prepopulate contact lists for new CUPS client users or add to current contact lists. In order to use BAT, you must provide it with an input file that contains the user contact lists.
Cisco recommends that you have knowledge of these topics:
- CUPS Version 8.x
- Cisco Unified Communications Manager (CUCM) Version 6.x
This document is not restricted to specific software and hardware versions.
The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.
In order to import user contact lists, you must provide BAT with an input file that contains the user contact lists.
The input file must be a comma-separated value (CSV) file in this format:
<User ID>,<User Domain>,<Contact ID>,<Contact Domain>,<Nickname>,<Group Name>
This is a sample CSV file entry: userA,example.com,userB,example.com,buddyB,General
This mandatory parameter refers to the user ID of the CUPS user. It can have a maximum of 132 characters.
This mandatory parameter refers to the Presence domain of the CUPS user. It can have a maximum of 128 characters.
This mandatory parameter refers to the user ID of the contact list entry. It can have a maximum of 132 characters.
This mandatory parameter refers to the Presence domain of the contact list entry. These restrictions apply to the format of the domain name:
- Must be less than or equal to 128 characters
- Must contain only numbers, upper- and lowercase letters, and hyphens
- Must not start or end with hyphens
- Must have a label length of less than or equal to 63 characters
- Must have a top-level domain of only characters with a minimum of two characters
This optional parameter refers to the nickname of the contact list entry. It can have a maximum of 255 characters.
This mandatory parameter refers to the name of the group to which the contact list entry is to be added. It can have a maximum of 255 characters.
Tasks to be Completed Before You Import
- Provision the users on CUCM.
- Ensure that the users are licensed and assigned to CUPS.
Complete these steps in order to import user contact lists into CUPS:
- Check the maximum contact list size.
- Upload the input file with BAT.
- Create a new Bulk Administration job.
- Check the results of the Bulk Administration job.
Check the Maximum Contact List Size
Before you import contact lists, Cisco recommends that you check the maximum contact list size and the maximum watchers settings in CUPS. If the contact list size is over the limit for a user, no contacts will be imported for that user. In order to ensure that the contact list size does not exceed the limit, you can increase the maximum contact list size setting or change it to unlimited. An unlimited setting ensures that all contact lists are fully imported to CUPS.
The system default value for both maximum contact list size and maximum watchers is 200.
Upload the Input File with BAT
This procedure describes how to upload the CSV file with BAT.
- Choose Cisco Unified Presence Administration > Bulk Administration > Upload/Download Files.
- Click Add New.
- Click Browse in order to locate and choose the CSV file.
- Choose Contact Lists as the Target.
- Choose Import Users' Contacts - Custom File as the Transaction Type.
- Click Save in order to upload the file.
Create a New Bulk Administration Job
This procedure describes how to create a new Bulk Administration job in CUPS Administration.
- Choose Cisco Unified Presence Administration > Bulk Administration > Contact List > Update.
- From the File Name drop-down list, choose the file to import.
- In the Job Description field, enter a description for this Bulk Administration job.
- Choose one of these options:
- Run Immediately executes the Bulk Administration job immediately.
- Run Later schedules a time to execute the Bulk Administration job.
Check the Results of the Bulk Administration Job
When the Bulk Administration job is complete, the CUPS BAT tool writes the results of the contact list import job to a log file. The log file contains this information:
- The number of contacts that were successfully imported.
- The number of internal server errors that were encountered when the contacts were imported.
- The number of contacts that were not imported (ignored). The log file lists a reason for each ignored contact at the end of the log file.
These are the reasons why a contact would not be imported:
- Invalid format - invalid row format, such as a missing or empty required field
- Invalid contact domain - the contact domain is in an invalid format; see the Contact Domain section for the valid format of the contact domain
- Cannot add self as a contact - you cannot import a contact as a user if that contact is the user
- User contact list is over the limit - the user has reached the maximum contact list size and no more contacts can be imported for that user
- User is not assigned to local node - the user is not assigned to the local node
- The number of contacts in the CSV file that were unprocessed due to an error that caused the BAT job to finish early. This error rarely occurs.
Complete this procedure to access the log file.
- Choose Cisco Unified Presence Administration > Bulk Administration > Job Scheduler.
- Click Find and choose the job ID of the contact list import job.
- Click the Log File Name link in order to open the log.
If you require further detail on any BAT job, see the Bulk Provisioning Service debug logs. You can access these logs at this location: /var/log/active/cm/trace/bps/log4j/bps000*.txt
You can enable debug logging for the Bulk Provisioning Service on the Cisco Unified Serviceability GUI.
Configure BAT Provisioning Service Logging on CUPS
This procedure describes how to configure BAT Provisioning Service logging on CUPS.
- Choose Cisco Unified Serviceability > Trace > Configuration.
- Choose the Cisco Unified Presence server, and click Go.
- Choose Database and Admin Services from the Service Group drop-down list and click Go.
- Choose the Bulk Provisioning Service from the Service drop-down list and click Go.
- Click Trace On.
- In the Trace Filter Settings, choose the Debug Trace Level. If you want to enable debug level on the traces, click Debug.
- Click Save.
There is currently no verification procedure available for this configuration.
There is currently no specific troubleshooting information available for this configuration.
The Cisco Support Community is a forum for you to ask and answer questions, share suggestions, and collaborate with your peers.
Refer to Cisco Technical Tips Conventions for information on conventions used in this document.