-
Bulk Administration Tool User Guide, Release 5.0(1)
-
Index
-
Preface
-
Introducing the Bulk Administration Tool (BAT)
-
Installing BAT
-
Working with IP Phones and Other IP Telephony Devices
-
Working with Users
-
Working with Cisco IP Manager Assistant
-
Working with User Device Profiles
-
Working with Gateways and Ports
-
Working with the Export Utility
-
Generating Reports
-
Working with the Tool for Auto-Registered Phones Support
-
Troubleshooting BAT and TAPS
-
Text-Based CSV Files
-
Table Of Contents
Introducing the Bulk Administration Tool (BAT)
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
Accessing Cisco CallManager Administration and BAT
Introducing the Bulk Administration Tool (BAT)
The Bulk Administration Tool (BAT), a web-based application, performs bulk transactions to the Cisco CallManager 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 CallManager Administration, each database transaction requires an individual manual operation, while BAT automates the process and achieves faster add, update, and delete operations.
You can use BAT to work with the following types of devices and records:
•
Add, update, and delete Cisco IP Phones including voice gateway chalice (VGC) phones, computer telephony interface (CTI) ports, and H.323 clients
•
•
•
•
•
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 Tool for Auto-Registered Phones Support (TAPS), further reduces the manual labor 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 TAPS directory number, follow the voice prompts, and download the correct user device profiles for their phones. For more information about the TAPS tool, see "Working with the Tool for Auto-Registered Phones Support."
Use the following topics to understand how to use BAT:
•
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 CallManager 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.
Related Topics
BAT Configuration Process
BAT uses a multistep process to prepare the bulk configuration transaction. BAT uses a wizard interface to guide you through the configuration tasks. The BAT process includes these tasks:
1.
2.
3.
4.
5.
Using the BAT Wizard
The BAT wizard provides step-by-step procedures for all the BAT tasks. When you start BAT, the main window displays with the following menu options at the top:
•
•
•
From the Configure menu, you can access the wizard window by choosing one of these device or configuration options:
•
•
•
•
•
•
After you choose a device or configuration option, the wizard displays a list of configuration tasks that is specific to that option. For example, when you choose Phones, the following list of tasks displays:
•
•
•
•
•
•
•
•
•
After choosing the configuration task, the wizard provides a list of steps that is specific to the task. For example, to guide you through the task, Insert Phones, the wizard displays the following steps:
Step 1: Add, view, or modify existing phone templates.
Step 2: Create the CSV data file.
Step 4: Validate phone records.
Step 5: Insert phones.
When you choose a step from the task list, you open a configuration window such as the Phone Template Configuration window. The configuration window provides the entry fields for defining a template.
Related Topics
•
•
•
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:
•
•
•
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 CallManager 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 CallManager Administration. You cannot use BAT to create new settings or button templates in Cisco CallManager 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 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.
Related Topics
•
•
•
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 (CFB) and Call Forward No Answer (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's 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's 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
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:
•
•
•
•
•
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.
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."
Related Topics
•
•
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 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 CallManager 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 Moving Records from one Cisco CallManager Server to Another, page 8-2
Related Topics
•
•
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 CallManager 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:
•
•
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:
NUMBER OF LINES,MAC ADDRESS,DESCRIPTION,LOCATION,USER ID,DIRECTORY NUMBER,DISPLAY,LINE TEXT LABEL,FORWARD BUSY DESTINATION,FORWARD NO ANSWER DESTINATION,CALL PICKUP GROUP,SPEED DIAL NUMBER, SPEED DIAL LABEL
1,1231123245AB,SEP1231123245AB,Dallas,johns,9728437154,9728437154,
Mike,9728437172,9728437196,9728437121/TollByPass,1230000000,HelpdeskNow, you can customize the file format for the CSV data file by using the 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:
•
•
•
Note
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
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.
NUMBER OF LINES,MAC ADDRESS,DESCRIPTION,DEVICE POOL,CSS,DIRECTORY NUMBER,LINE TEXT LABEL,PARTITION,
1,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.
Related Topics
•
•
•
•
•
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.
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
To copy the file to a local machine, use a floppy disk or a mapped network drive, and open the path C:\CiscoWebs\BAT\ExcelTemplate\ on the publisher database server. Copy the file BAT.xlt file to a local machine where Microsoft Excel is installed.
To use the BAT 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.
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 Update, 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
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 CallManager publisher database.
Note
The system saves the CSV formatted file as a text file to the C:\XLSDataFiles\ folder or to another 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 move the converted CSV data file (CSV format version) back to the Cisco CallManager publisher database server where BAT can access the CSV data file. Using a mapped network drive or floppy disk, copy the <tabname><timestamp>.txt file from the C:\XLSDataFiles\ folder to the appropriate folder under C:\BATFiles\ on the publisher server.
Related Topics
•
•
Validating the BAT Data Input File
In the next task in the BAT Wizard, 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 publisher database. These checks include the following items:
•
•
•
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, choose View Latest Log File 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 "Troubleshooting BAT and TAPS."
Related Topics
•
•
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 CallManager publisher 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.
After you click Insert, a message displays that advises you of approximately how long it will take to insert the records into the Cisco CallManager database. You can cancel the transaction if you feel that it may cause performance degradation.
Caution
If you clicked OK, a Transaction Status window displays. Click the Show Latest Status button to see the transaction in progress.
Note
When the transaction completes, Click View Latest Log File to see a log file that indicates 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 the "BAT Log Files" section.
When you start a BAT transaction and notice a degradation in Cisco CallManager performance, you can stop the transaction. For instructions on how to use the tool to stop a BAT transaction when it is in progress, see the "Stopping BAT Transactions" section.
Related Topics
•
•
Using the BAT Application
The following topics provide information about the BAT application and how to start and use it:
•
Specifications
The following specifications apply to BAT Release 5.0(x):
•
•
•
•
•
•
Only Cisco CallManager system administrators require access to BAT; however, end users can use TAPS when instructed to do so by the system administrator.
Related Topics
•
Accessing Cisco CallManager Administration and BAT
BAT, a web-based application, requires the use of a web browser. The Cisco CallManager Administration and BAT programs support the following Microsoft Windows operating system browsers:
•
•
Cisco recommends that you access the BAT and Cisco CallManager Administration programs from a PC that is not the same machine as the web server or Cisco CallManager server.
Caution
From any user PC in your network, you can browse into a server that is running Cisco CallManager Administration and BAT to log on with administrative privileges.
Note
Starting BAT
You can start BAT by using one of the following methods:
•
•
•
You can also access BAT by browsing into Cisco CallManager Administration from a remote PC. Open Cisco CallManager Administration and choose Application > BAT.
Logging On to BAT
When you start BAT, a prompt asks for user ID and password. Log on with a user ID and password that have administrator rights on the machine.
The BAT application does not depend on the Multilevel Administration (MLA) feature in Cisco CallManager Administration
Navigating in BAT
After you log on to BAT, the main window displays with the following menu options at the top:
•
•
•
The Configure menu gives you access to configuration tasks for the following device types and the TAPS tool, if installed:
•
•
•
•
•
•
The Applications menu gives you direct access to the following options:
•
•
•
•
The Help menu provides the following Help information:
•
•
•
Related Topics
Using Online Help
To access BAT online help, choose the Help menu. The Help menu provides two help features:
•
•
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.
Related Topics
Finding the BAT Version
To find the current version of BAT, choose Help > About Bulk Administration Tool > Details.
To find the current version of BAT from Cisco CallManager Administration, choose Help > Component Versions.
If BAT is not currently installed, you can find the version of BAT that is available with Cisco CallManager without installing it. To do this, download the BAT application from the Cisco CallManger Install Plugins window. Right-click the file BulkAdministrationTool.exe , choose Properties, and then choose Product Version.
Related Topic
Stopping BAT Transactions
BAT provides a tool to stop BAT transactions that are in progress. This capability can prove useful when you start a BAT transaction, then notice a degradation in Cisco CallManager performance, and want to stop the transaction. You can always run the BAT transaction later when there is less impact to Cisco CallManager performance. You might want to stop BAT if you realize that the wrong transaction has been started or if you need to make additional changes before running the transaction.
You can access the Stop BAT function only from the publisher database server.
To stop BAT, choose Start > Programs > Cisco CallManager 4.0 > Bulk Admin Tool > Stop BAT.
The BAT transaction halts.View the log file for details about how many BAT processed records passed or failed. See the "BAT Log Files" section for information on log files.
Note
Related Topics
