Cisco Unified Communications Manager Bulk Administration Guide, Release 8.0(1)
Overview
Downloads: This chapterpdf (PDF - 442.0KB) The complete bookPDF (PDF - 11.47MB) | Feedback

Overview

Table Of Contents

Overview

Bulk Administration Installation

BAT Data Input Files

BAT Configuration Process

Using BAT Templates

Master Phone Templates

Working with CSV Data Files

CSV Data Files for Adding New Devices

CSV Data Files to Update Existing Devices

Customizing File Formats for CSV Data Files

Using the BAT Spreadsheet for Gathering Data

Validating the BAT Data Input File

Inserting the BAT Data Input File

Using the BAT Application

Accessing Cisco Unified Communications Manager Administration and BAT

Using Online Help

Finding the Cisco Unified Communications Manager Version

Related Topics


Overview


The Cisco Unified Communications Manager Bulk Administration Tool (BAT), a web-based application, performs bulk transactions to the Cisco Unified Communications Manager database. BAT lets you add, update, or delete a large number of similar phones, users, or ports at the same time. When you use Cisco Unified Communications Manager Administration, each database transaction requires an individual manual operation, while BAT automates the process and achieves faster add, update, and delete operations.


Note Be aware that the Bulk Administration menu is visible only on the first node of Cisco Unified Communications Manager server.


Bulk Provision Service (BPS) administers and maintains all jobs that are submitted through Bulk Administration menu of Cisco Unified Communications Manager administration. You can start this service from Cisco Unified Communications Manager Serviceability.

The BPS Server service parameter determines whether the service is activated on a particular server. You need to activate BPS only on the first node of Cisco Unified Communications Manager.

You can use BAT to work with the following types of devices and records:

Add, update, and delete Cisco Unified IP Phones including voice gateway (VG) phones, computer telephony interface (CTI) ports, and H.323 clients, and migrate phones from Skinny Client Control Protocol (SCCP) to Session Initiation Protocol (SIP)

Add, update, and delete users

Add, update, and delete User Device Profiles

Add, update, and delete Cisco Unified Communications Manager Assistant and Managers associations

Add, update, and delete ports on a Cisco Catalyst 6000 FXS Analog Interface Module

Add or delete Cisco VG200 and Cisco VG224 analog gateways and ports

Add or delete Forced Authorization Codes

Add or delete Client Matter Codes

Add or delete Call Pickup Groups

Update or export CUP/CUPC users

Populate or depopulate the Region Matrix

Insert, delete, or export the Access List

Export or import configuration

Insert, delete, or export Remote Destination and Remote Destination Profile


Note Cisco recommends that you limit the number of records when you perform a bulk transaction in Cisco Unified CallManager Bulk Administration to a maximum of 12,000 records. This applies when you insert, update, delete, or query any records using BAT.


You can also work with these devices in combination with the user information. For example, when you add CTI ports and users, BAT allows you to "Enable CTI Application Use." This saves time when you are adding users who have applications that require a CTI port, such as Cisco IP SoftPhone.

An optional component of BAT, the Cisco Unified Communications Manager Auto-Register Phone Tool, further reduces the time and effort that is involved in administering a large system. When you need to add a large block of new phones, you can use BAT to add the devices with dummy media access control (MAC) addresses instead of entering each MAC address in the data input file. After the phones are installed, the phone users or the administrator can call the Unified CM Auto-Register phone Tool directory number, follow the voice prompts, and download the correct user device profiles for their phones. For more information about the Unified CM Auto-Register Phone Tool tool, see Chapter 77, "Working with the Tool for Auto-Registered Phones Support (TAPS)."

Use the following topics to understand how to use BAT:

Bulk Administration Installation

BAT Data Input Files

BAT Configuration Process

Using the BAT Application

Bulk Administration Installation

BAT is installed as part of the Cisco Unified Communications Manager Administration. Refer to Cisco Unified CallManager Administration Guide for more details.

Additional Topics

See the "Related Topics" section.

BAT Data Input Files

Every device includes a multitude of individual attributes, settings, and information fields that enable the device to function in the network and provide its telephony features. Many devices have the same attributes and settings in common, while other values, such as the directory number, are unique to a user or to a device. To condense the BAT data input file contents, BAT uses templates for settings that devices usually have in common.

For bulk configuration transactions on the Cisco Unified Communications Manager database, the BAT process uses two components: a template for the device type and a data file in comma separated value (CSV) format that contains the unique values for configuring a new device or updating an existing record in the database. The CSV data file works in conjunction with the device template.

For instance, when you create a bulk transaction for a group of Cisco IP Phones, you set up the CSV data file that contains the unique information for each phone, such as the directory number and MAC address. In addition, you set up or choose the BAT template that contains the common settings for all phones in the transaction, such as a Cisco IP Phone 7960 template.

Additional Topics

See the "Related Topics" section.

BAT Configuration Process

BAT uses a multistep process to prepare the bulk configuration transaction. BAT uses Bulk Administration menu options to guide you through the configuration tasks. The BAT process includes these tasks:

1. Set up the template for data input.

2. Define a format for the CSV data file.

3. Collect the data for each device in the bulk transaction.

4. Upload the data files choosing the relevant target and function for the transaction.

5. Validate the data input files with the Cisco Unified Communications Manager database.

6. Submit jobs for execution.

7. Schedule jobs.

8. Execute jobs to insert the devices into the Cisco Unified Communications Manager database.

Using the BAT Menu

From the Bulk Administration menu, you can choose one of these device or configuration options:

Upload/Download Files

Phones

Users

Phones and Users

Manager/Assistants

User Device Profiles

Gateways

Forced Authorization Codes

Client Matter Codes

Call Pickup Group

Mobility

Region Matrix

Import/Export

Phone Migration

EMCC

Intercompany Media Engine

CUPS

TAPS

Job Scheduler

When you choose an option, the corresponding menu items display. For example, when you choose phones, the following list of menu items displays:

Validate Phones—Validate phones records.

Insert Phones—Add new phones.

Update Phones—Locate and modify existing phones.

Delete Phones—Locate and delete phones.

Export Phones—Locate and export specific phone records or all phone records.

Add/Update Lines—Add new lines to existing phones, and locate and modify lines on existing phones.

Reset/Restart Phones—Locate and reset or restart phones.

Generate Phone Reports—Generate customized reports for phones.

Migrate Phones—Migrate phones from SCCP to SIP.

When you choose a menu option from the Bulk Administration menu, the corresponding window opens, such as the phone Template Configuration window. The configuration window provides the entry fields for defining a template.

Additional Topics

See the "Related Topics" section.

Using BAT Templates

As the first task in the BAT configuration process, you set up a template for the devices that you are configuring. You specify the type of phone or device that you want to add or modify, and then you create a BAT template that has features that are common to all the phones or devices in that bulk transaction.

You can create BAT templates for the following types of device options:

Phones: All Cisco Unified IP Phones and Cisco ATA 186, Cisco VGC phones, CTI ports, and H.323 clients

Gateways: Cisco VG200 and Cisco Catalyst 6000 FXS Analog Interface Module

User Device Profiles: Cisco Unified IP Phone 7900 series and Cisco Softphone

Define a BAT template by specifying values in the template fields that will be common to all the devices in the bulk transaction. The BAT template fields require similar values to those that you enter when you are adding a device in Cisco Unified Communications Manager Administration.

Prior to creating the BAT template, make sure settings such as device pools, locations, calling search spaces, button templates, and softkey templates have already been configured in Cisco Unified Communications Manager Administration.

After you create a BAT template, you save it with a name. Later in the configuration process, you associate the template name with the CSV data file. The system stores the templates, so they are reusable for future bulk transactions. For example, you can configure a Cisco IP Phone 7960 template with a specific button template and calling search space and then configure another Cisco IP Phone 7960 template with a different button template and the Extension Mobility feature enabled. When you need to add a large number of phones with the same configuration, you can reuse the existing BAT template.

Master Phone Templates

When you are adding a group of phones that have multiple lines, you can create a master phone template that provides multiple lines and the most common values for a specific phone model. You can use the master template to add phones that have differing number of lines, but do not exceed the number of lines in the master phone template. For example, you can create a master phone template for a Cisco Unified IP Phone 7960 that has eight lines. You can use this template to add phones that have one line, two lines, or up to eight lines.

Additional Topics

See the "Related Topics" section.

Working with CSV Data Files

The CSV data file contains the unique settings and information for each individual device, such as its directory number, MAC address, and description. Make sure that all phones and devices in a CSV data file are the same phone or device model and match the BAT template. The CSV data file can contain duplicates of some values from the BAT template. Values in the CSV data file override any values that were set in the BAT template. You can use the override feature for special configuration cases.

Overriding Template Values Example

If you want most of the phones in the bulk transaction to be redirected to a voice-messaging system, you can set the Call Forward Busy (Internal/External) (CFB) and Call Forward No Answer (Internal/External) (CFNA) fields to the voice-messaging number. However, if a few phones in the bulk transaction need to be redirected to a secretary instead of to a voice messaging system, you can specify the secretary directory number in the Call CFB and CFNA fields in the CSV data file. Most of the phones will use the CFB and CFNA values from the BAT phone template, but certain phones will use the secretary directory number as specified in the CSV data file.

The CSV data file for phones can contain multiple directory numbers. Keep in mind that the number of directory numbers that are entered in the CSV data file must not exceed—but can be less than— the number of lines that are configured in the BAT phone template, or an error will result.

Use the following topics to understand the different types of CSV data files:

CSV Data Files for Adding New Devices

CSV Data Files to Update Existing Devices

Customizing File Formats for CSV Data Files

CSV Data Files for Adding New Devices

When you are adding new devices to the system, you can use the Microsoft Excel spreadsheet that was designed to use with BAT. The BAT spreadsheet assists you with the following features:

Data file templates with macros for the different devices

Customized file format definition

Support for multiple phone lines

Record error checking

File conversion to CSV format

When you are creating new records, use the BAT spreadsheet, which is named BAT.xlt, because the data gets validated automatically when you export to the CSV format. For more information about using the BAT spreadsheet, see "Using the BAT Spreadsheet for Gathering Data" section.


Note BAT.xlt validates data only for valid characters, data types, and field length for particular fields. For more information see the "Validating CSV Data File Phone Records" section on page 5-1.


For experienced BAT users who are comfortable with working in a CSV formatted file, you can use a text editor to create a CSV data file by following the sample text file that is provided on the device insert task window. For more information about text-based CSV data files, see Appendix A, "Text-Based CSV Files."

Additional Topics

See the "Related Topics" section.

CSV Data Files to Update Existing Devices

To modify or update existing phones and devices, you need to locate the records for these devices. BAT provides two methods for locating phones, gateways, and device profiles. You can search by using a customized query or by using a custom file.

Customized Queries

BAT provides a window for defining your query criteria. You can choose the specific device model and/or choose criteria from a list of device details and a list of line details. To locate all devices of a specific device model, such as Cisco IP Phone 7912, you choose the model but add no other criteria for the search. You get the records for all the Cisco Unified IP Phones 7912 that are configured in the database.

Custom Files

When no common attribute to use for a query exists, BAT provides the custom file option. A custom file includes device names or directory numbers. You can build a custom text file by putting each record on a separate line. The search gives you all the records that match the criteria.

Exported Files

When you need to move a group of phones, you can use the export utility. You use the export utility to extract existing records from the Cisco Unified Communications Manager database to move them into a CSV data file. When you move phones, use the option, Export Phones with the All Phone Details. This option generates an export file that contains records with all the information, including the device attributes, line attributes, and services, that is associated with that phone. You can also export phone records with specific details when phones have similar line configurations and you want to use a template. For more information about using the export utility to update devices, see Using Phone Export, page 9-1

Additional Topics

See the "Related Topics" section.

Customizing File Formats for CSV Data Files

CSV data files comprise a string of device attributes and information in a comma separated value (CSV) format. To insert data records into the Cisco Unified Communications Manager database, ensure that each data file is in the CSV format. In earlier releases of BAT, the CSV file had a fixed format with two options:

Default format—CSV files that have a fixed and limited number of attributes and settings for each device.

All details format—CSV files that are created by using the export utility and include all attributes and settings for each device.

The first row of every CSV data file shows the file format by displaying the name of each field that the CSV file includes. The file format information makes it easier to locate the entry for a specific field in the CSV data file. For instance, in the following sample CSV file, USER ID represents the fifth field in the header, and the fifth field in the CSV file for the phone shows "johns."

Sample CSV Data File with the Default File Format:

MAC ADDRESS,DESCRIPTION,LOCATION,USER ID,DIRECTORY NUMBER 1,DISPLAY 1,LINE TEXT LABEL 
1,FORWARD BUSY EXTERNAL 1,FORWARD NO ANSWER EXTERNAL 1,FORWARD NO COVERAGE EXTERNAL 
1,FORWARD BUSY INTERNAL 1,FORWARD NO ANSWER INTERNAL 1,FORWARD NO COVERAGE INTERNAL 1,CALL 
PICKUP GROUP 1,SPEED DIAL NUMBER 1, SPEED DIAL LABEL 1
1231123245AB,SEP1231123245AB,Dallas,johns,9728437154,9728437154,Mike,9728437172,9728437196
,9728437127,9728437154,9728437178,9728437189,9728437121/TollByPass,1230000000,Helpdesk
9728437127,9728437154,9728437178,9728437189,Marketing,1230000000,Helpdesk

Now, you can customize the file format for the CSV data file by using the Create Phone File Format Configuration window. You can add attributes to your file format that are also in the BAT template. This allows you to override the template entry with a specific attribute for a device. For instance, you can choose the route partition attribute for your file format and enter different partitions for each phone in the CSV data file.

From this window, you can choose specific attributes from Device fields and Line fields

The following device attributes always remain in each file format:

MAC Address

Description

The File Format Configuration dialog box makes it easy to choose the device attribute in the Device Field box and click an arrow to move the attribute into the Selected Device Field box. You can select multiple attributes at the same time by holding down the Ctrl key.

You can rearrange the order of the device attribute fields and line attribute fields in the file format by using the Up and Down arrows. You can select an attribute and then click the Up arrow to move the item closer to the first record or click the down arrow to move the item further away from the first record. You cannot move line attributes before device attributes or change the order of speed dials.


Tip You can customize a CSV file format, so it matches the arrangement of your employee phone information that is stored in another database. This method simplifies exporting data between a company database and the Cisco Unified Communications Manager database.


Sample CSV Data File with the Customized File Format:

Device fields—MAC Address, Description, Device Pool, Calling Search Space

Line fields—Directory number, Partition, Line Text Label (moved to position after directory number in file)

The File Format does not include speed-dial codes. Choose speed-dials by selecting the Include Speed Dials in the CSV Format check box.

MAC ADDRESS,DESCRIPTION,DEVICE POOL,CSS,DIRECTORY NUMBER,LINE TEXT LABEL,PARTITION,
2234900AEF01,SEP2234900AEF01,DP_1,CSS_Restricted, 
9725098827,Lobby Phone,Part1

Associating the File Format with the CSV Data File

When you are using a text editor to create a CSV data file, you can create a customized file format and then enter values in the same order as specified by that file format. Before inserting the text-based CSV data file that uses the customized file format, you must associate the file format name with the CSV data file. You can associate only one file format with a CSV data file.

Use the Add File Format window to choose the name of the CSV data file <CSVfilename>.txt from the File Name drop-down list. Next, you choose your file format from the File Format Name drop-down list. The data in the CSV data file must match the custom file format that you have chosen.

Additional Topics

See the "Related Topics" section.

Using the BAT Spreadsheet for Gathering Data

The BAT spreadsheet simplifies the creation of CSV data files. You can add multiple devices and view the records for each device in a spreadsheet format. It allows you to customize the file format within the spreadsheet and provides validation and error checking automatically to help reduce configuration errors. The BAT spreadsheet includes tabs along the bottom of the spreadsheet for access to the required data input fields for the various devices and user combinations in BAT.


Note BAT.xlt validates data only for valid characters, data types, and field length for particular fields. For more information, see the "Validating CSV Data File Phone Records" section on page 5-1.


The CSV data file works in combination with the BAT template. For example, when you choose the Phone tab in the BAT spreadsheet, you can leave Location, Forward Busy Destination, or Call Pickup Group blank. The values from the BAT phone template get used for these fields; however, if you specify values for Forward Busy Destination or Call Pickup Group, those values override the values for these fields that were set in the BAT phone template.


Tip When Cisco Unified Communications Manager is installed, the Microsoft Excel file for the BAT spreadsheet gets placed on the first node database server; however, you probably do not have Microsoft Excel running on the first node database server. You must download the file from the first node database server to the local machine on which you plan to work.


To download the file to a local machine, see Chapter 2, "Uploading and Downloading Files." Download the file BAT.xlt file to a local machine where Microsoft Excel is installed.

To use the BAT.xlt spreadsheet to create a CSV data file, locate and double-click the BAT.xlt file. You must choose to "enable macros" when you open the BAT spreadsheet.

The spreadsheet displays a set of columns with attribute headings that specify the BAT field names, whether the field is a required or optional, and the maximum number of characters that are allowed in the field.

Tabs for every device display along the bottom of the spreadsheet. When you click the tab for the type of device with which you want to work, the columns adjust to display all relevant fields for the chosen device. For example, to add phones and users all at once, click the tab that is marked Phones-Users.


Tip If the "enable macros" option does not display while you are opening the spreadsheet, a possibility exists that macro security on the Excel program is set to high. Ensure that Macro security is medium or low for the macros to run. To set the Macro security to medium, do the following task: choose Tools > Macro > Security from Excel menu. Set the security level to medium. Close the Excel program and open it again. This action should give you the "enable macros" option when you open the spreadsheet the next time.


Next, define the file format for the CSV data file by clicking the Create File Format button. You can use the Field Selection dialog box to choose items and their order in your CSV data file. When you click Create, the columns in the spreadsheet adjust to your new file format.

In the first row, enter data for a device in all mandatory fields and any relevant optional fields. You enter data in a new row for each device.


Note The system treats blank rows in the spreadsheet as "end of file" markers and discards subsequent records.


After all device records are completed, you export the BAT spreadsheet data to the CSV file format that BAT must use to perform the bulk transaction with the Cisco Unified Communications Manager first node database.


Note If you enter a comma in one of the fields, BAT.xlt encloses that field entry in double quotes when you export to BAT format.


The system saves the CSV formatted file as a text file to the a folder that you choose. The file name format follows:

<tabname><timestamp>.txt

where <tabname> represents the type of device input file that you created (such as phones, user device profiles), and <timestamp> represents the precise date and time that the file was created.

Next, you must upload the converted CSV data file (CSV format version) back to the Cisco Unified Communications Manager database server by using Upload/Download Files option in the Bulk Administration of Cisco Unified Communications Manager Administration. For more information, refer to Chapter 2, "Uploading and Downloading Files."

Additional Topics

See the "Related Topics" section.

Validating the BAT Data Input File

In the next task, you use the Validate File option. In this task, you choose the name of the CSV data file and the BAT template for the device or the model when you have a CSV data file with all details. You have these options for how records are validated:

Specific Details—For validating records that follow the Default or Custom file format.

All Details—For validating records from a file that was generated with the export utility by using the All Details option.

When you choose Validate, the system runs a validation routine to check for errors against the first node database. These checks include the following items:

Fields, such as description, display text, and speed-dial label that do not have a dependency on a database table, use valid characters.

BAT Validate transaction only validates data type, length and relational dependency.

Consider the following example:

MAC ADDRESS,DESCRIPTION,PARTITION

AABBCC112233,Lab Phone,Dallas

If the Partition does not exist, Validate displays an error saying "Dallas is not an existing PARTITION."

Number of lines that are configured on a device matches the device template. (Only for Specific Details)

Validation does not check for the existence of a user or for mandatory/optional fields that are BAT defined, such as the dummy MAC address.

After the transaction completes, click the Log File Name link in the Job configuration window to see a log file that displays the devices that could not be validated successfully and the error code. For more information on log files, see Chapter 80, "Troubleshooting BAT and TAPS."

Additional Topics

See the "Related Topics" section.

Inserting the BAT Data Input File

When the data input file has passed validation, you are ready to use the Insert window to add the device records into the Cisco Unified Communications Manager first node database. During this task, you choose the name of the data input file, the BAT template for the device, and the model, if applicable. You have these options for how records are validated:

Specific Details—For inserting records that use a customized file format.

All Details—For inserting records from a file that was generated with the export utility by using the All Details option.

Enter Job Information details and click submit. This creates a job that can be accessed by using the Job Scheduler Option in the Bulk Administration menu. Use the Job Configuration window to view the status and to schedule and activate the job.


Note If any line information for a phone record fails, BAT does not insert that phone record.


After the transaction completes, click the Log File Name link in the Job Configuration window to see a log file that displays the number of records that were added and the number of records that failed, including an error code. For more information on log files, see Chapter 80, "Troubleshooting BAT and TAPS."

Additional Topics

See the "Related Topics" section.

Using the BAT Application

The following topics provide information about the BAT application and how to start and use it:

Accessing Cisco Unified Communications Manager Administration and BAT

Using Online Help

BAT Configuration Process

BAT Data Input Files

A web browser, a resource-intensive application, can consume large amounts of system memory and CPU cycles. When the web browser takes resources away from Cisco Unified Communications Manager, it adversely affects call processing. Possible consequences of using the browser on the same machine as the web server and Cisco Unified Communications Manager include delayed dial tone and dropped calls.

Accessing Cisco Unified Communications Manager Administration and BAT

BAT, a web-based application, requires the use of a web browser. For more details and specifications, refer to Cisco Unified CallManager Administration Guide.

Additional Topics

See the "Related Topics" section.

Using Online Help

To access BAT online help, choose the Help menu. The Help menu provides two help features:

Contents and Index—Opens the BAT help file and allows you to browse for information or search the index.

For This Page—Opens the help directly for the window that you are currently viewing. You can still browse the remainder of the help or use the index.

Online help provides a multivolume system that allows you to access several different help systems, all from the same window. You can also access a comprehensive search engine and index.

Additional Topics

See the "Related Topics" section.

Finding the Cisco Unified Communications Manager Version

To find the current version of Cisco Unified Communications Manager, choose Help > About.

Additional Topics

See the "Related Topics" section.

Related Topics

BAT Data Input Files

BAT Configuration Process

Using BAT Templates

Working with CSV Data Files

CSV Data Files for Adding New Devices

CSV Data Files to Update Existing Devices

Customizing File Formats for CSV Data Files

Using the BAT Spreadsheet for Gathering Data

Validating the BAT Data Input File

Inserting the BAT Data Input File

Using the BAT Application

Accessing Cisco Unified Communications Manager Administration and BAT

Using Online Help

Finding the Cisco Unified Communications Manager Version