Guest

Cisco Unified Communications Manager IM & Presence Service

CUPS User Contact Lists Import with BAT Configuration Example

Document ID: 116226

Updated: Jun 21, 2013

Contributed by Tray Stoutmeyer, Cisco TAC Engineer.

   Print

Introduction

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.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

  • CUPS Version 8.x
  • Cisco Unified Communications Manager (CUCM) Version 6.x

Components Used

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.

Configuration

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

User ID

This mandatory parameter refers to the user ID of the CUPS user. It can have a maximum of 132 characters. 

User Domain

This mandatory parameter refers to the Presence domain of the CUPS user. It can have a maximum of 128 characters.

Contact ID  

This mandatory parameter refers to the user ID of the contact list entry. It can have a maximum of 132 characters.

Contact Domain

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

Nickname 

This optional parameter refers to the nickname of the contact list entry. It can have a maximum of 255 characters.

Group Name

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

  1. Provision the users on CUCM.
  2. Ensure that the users are licensed and assigned to CUPS.

Note: The default contact list import rate is based on the server hardware type. You can change the contact list import rate if you choose Cisco Unified Presence Administrator > System > Service Parameters > Cisco Bulk Provisioning Service. However, if you increase the default import rate, it results in higher CPU and memory usage on CUPS.

Complete these steps in order to import user contact lists into CUPS:

  1. Check the maximum contact list size.
  2. Upload the input file with BAT.
  3. Create a new Bulk Administration job.
  4. 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.

Note: You only need to check the maximum contact list size on those clusters that contain users for whom you wish to import contacts. When you change the Presence settings, the changes are applied to all nodes in the cluster; therefore, you only need to change these settings on the CUPS Publisher node within the cluster.

Upload the Input File with BAT

This procedure describes how to upload the CSV file with BAT.

  1. Choose Cisco Unified Presence Administration > Bulk Administration > Upload/Download Files.
  2. Click Add New.
  3. Click Browse in order to locate and choose the CSV file.
  4. Choose Contact Lists as the Target.
  5. Choose Import Users' Contacts - Custom File as the Transaction Type.
  6. 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.

  1. Choose Cisco Unified Presence Administration > Bulk Administration > Contact List > Update.
  2. From the File Name drop-down list, choose the file to import.
  3. In the Job Description field, enter a description for this Bulk Administration job.
  4. Choose one of these options:
    • Run Immediately executes the Bulk Administration job immediately.
    • Run Later schedules a time to execute the Bulk Administration job.
  5. Click Submit. If you chose to run the job immediately, the job runs after you click Submit.

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.

  1. Choose Cisco Unified Presence Administration > Bulk Administration > Job Scheduler.
  2. Click Find and choose the job ID of the contact list import job.
  3. 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.

  1. Choose Cisco Unified Serviceability > Trace >  Configuration.
  2. Choose the Cisco Unified Presence server, and click Go.
  3. Choose Database and Admin Services from the Service Group drop-down list and click Go.
  4. Choose the Bulk Provisioning Service from the Service drop-down list and click Go.
  5. Click Trace On.
  6. In the Trace Filter Settings, choose the Debug Trace Level. If you want to enable debug level on the traces, click Debug.
  7. Click Save.

Verify

There is currently no verification procedure available for this configuration.

Troubleshoot

There is currently no specific troubleshooting information available for this configuration.

Related Information

Updated: Jun 21, 2013
Document ID: 116226