Bulk Provisioning Overview
Bulk provisioning functionality in the Cisco Voice Provisioning Tool allows you to add or modify a large number of users or a large number of phones/device profiles (and the corresponding configuration settings). Before you perform any bulk operations, review the "Overview of the Comma Separated Value (CSV) File" section, which describes the CSV file format and caveats for the CSV file.
Caution
Because bulk operations typically take a long time to complete and because bulk operations may adversely affect processing performance, we recommend that you perform bulk operations during off-hours. If you want to do so, you can schedule the bulk operation to occur at a time when the system will be minimally impacted.
This chapter contains information on the following topics:
•Overview of Bulk Provisioning Privileges
•Overview of Bulk Import Operations
•Overview of Bulk Export Operations
•Overview of Bulk Provisioning States
•Overview of the Comma Separated Value (CSV) File
•Related Bulk Administration Tasks
–Downloading the Bulk CSV File
–Deleting a Bulk Operation
–Aborting a Running Bulk Operation
–Viewing Bulk Operations
–Reviewing the Bulk Operation Logs
•Where to Find More Information on Bulk Provisioning
Tip This chapter does not provide procedures on how to perform bulk import and export operations. For information on these procedures, see the "Where to Find More Information on Bulk Provisioning" section.
Overview of Bulk Provisioning Privileges
For information on bulk provisioning privileges, see the Cisco Voice Provisioning Tool Release Notes.
Overview of Bulk Import Operations
Caution
If you schedule a bulk operation and do not have the appropriate privileges, the bulk operation fails. The Cisco Voice Provisioning Tool does not validate that you have the appropriate privileges when you perform a bulk operation.
Bulk imports rely on a valid CSV file that contains the data you want to import into the database. Before you schedule a bulk import operation, perform the following tasks:
•Update the CSV file.
•Save the CSV file to a location that you remember.
•Ensure that the CSV file meets the guidelines that are described in the "Overview of the Comma Separated Value (CSV) File" section.
On the Manage Bulk Tasks page, you can modify a bulk import operation that exists in the Scheduled, Pending, Finished, or Aborted state. You cannot modify bulk import operations that exist in the Running state, but you can view import operations in the Running state.
By using the bulk provisioning functionality in the Cisco Voice Provisioning Tool, you can perform the following bulk import operations:
User Import Operations
•Apply User Template(s) to a User
After you specify a Cisco Voice Provisioning Tool user template in the CSV file, the product system setting in the CSV file becomes optional. You can specify additional product systems as long as you specify a product system type that is not used by the Cisco Voice Provisioning Tool template. For example, if you apply a Cisco Voice Provisioning Tool template that supports Cisco CallManager, you can apply a Cisco Unity product system for the product system setting. However, you cannot apply a template for Cisco CallManager and then add another Cisco CallManager product system to the product system field.
Any information that you specify in the CSV file automatically overwrites the settings that you specify in the Cisco Voice Provisioning Tool template.
•Add Users
During bulk add operations, the Cisco Voice Provisioning Tool automatically applies default values from the Cisco Voice Provisioning Tool GUI if you leave the setting blank.
•Modify Users
The Cisco Voice Provisioning Tool does not apply default values during bulk modify operations unless you specify the default setting.
•Associate a User with the Phone
You can associate a phone/device profile with a user in the CSV file. When you perform this task, you must specify the product system, user ID, user last name, user password, user PIN, and the device name or profile.
To generate the device name for phones, the Cisco Voice Provisioning Tool prepends the letters SEP to the beginning of the MAC address. When you enter names of the associated devices, make sure to enter the entire device name, including the SEP prefix; for example, enter SEP123456665432.
If you associate a device profile with a user, enter the user device profile name exactly as it displays in Cisco CallManager Administration or the Cisco Voice Provisioning Tool.
Because the tool does not support additions and updates in the same CSV file, you cannot add a phone/device profile and associate the phone/device profile to an existing user by using the same CSV file. You must use two CSV files, one for adding the phone/device profile and another to associate the phone/device profile to the existing user. The addition of the phone/device profile supports bulk add operations for phones/device profile, and the association of the phone/device profile to the user supports the bulk modify operations for users.
Tip A single CSV file supports both phones and device profiles.
Timesaver Before you associate a user to the phone/device profile, ensure that the phone/device profile exists in the Cisco CallManager database. Verifying that the phone/device profile configuration exists before the association minimizes the number of tasks that you must perform for bulk operations. For example, if you want to add two phones, add a new user, and associate the phones with the users, you must create one CSV file for the phones and another for the users. When you schedule the bulk operations, always schedule the phone/device profile operation first and then follow it by the user operation.
Phone Import Operations
•Apply a VPT Phone Template to a Phone
If you apply a template in the CSV file, leave the product system setting blank.
Any information that you specify in the CSV file automatically overwrites the settings that you specify in the Cisco Voice Provisioning Tool template.
•Add Phones
During bulk add operations, the Cisco Voice Provisioning Tool automatically applies default values from the Cisco Voice Provisioning Tool GUI if you leave the setting blank.
With bulk administration functionality, you cannot add a phone that already exists for the phone system that you specify. If you attempt to do so, the operation for the phone fails.
•Modify Phones
The Cisco Voice Provisioning Tool does not apply default values during bulk modify operations unless you specify the default setting.
With bulk administration functionality, you cannot modify a phone that does not exist for the phone system that you specify. If you attempt to do so, the operation for the phone fails.
•Add or Update Lines for a Phone
You can configure line settings in bulk add or modify operations. When you perform either operation, the line that you configure automatically is added to the phone if the line does not exist for another phone in the Cisco CallManager database. If the line does exist, the phone that you specify in the CSV file is associated with the line that exists (shared line). Likewise, any line settings that you specify in the CSV file are automatically applied to the existing line.
If you add or update a line during a bulk modify operation, you must specify the extension number in the CSV file; otherwise, the tool ignores the settings when the bulk operation runs. The tool only updates line settings that you specify in the CSV file. All other line settings retain the configuration that you specify on the Add or Manage Phone/Profiles configuration pages.
If you want to disassociate a line from a phone during a bulk modify operation, enter vpt_clear in the ccm_lineX_entension number column; specifying this information does not delete the line from the Cisco CallManager database.
Device Profile Import Operations
•Apply a VPT Profile Template to a Device Profile
If you apply a Cisco Voice Provisioning Tool template in the CSV file, leave the product system setting blank.
Any information that you specify in the CSV file automatically overwrites the settings that you specify in the Cisco Voice Provisioning Tool template.
•Add Device Profiles
During bulk add operations, the Cisco Voice Provisioning Tool automatically applies default values from the Cisco Voice Provisioning Tool GUI if you leave the setting blank.
•Modify Device Profiles
The Cisco Voice Provisioning Tool does not apply default values during bulk modify operations unless you specify the default setting.
With bulk administration functionality, you cannot modify a device profile that does not exist for the phone model that you specify. If you attempt to do so, the operation for the device profile fails.
•Add or Update Lines for a Device Profile
You can configure line settings in bulk add or modify operations. When you perform either operation, the line that you configure automatically is added to the phone if the line does not exist for another phone in the Cisco CallManager database. If the line does exist, the phone that you specify in the CSV file is associated with the line that exists (shared line). Likewise, any line settings that you specify in the CSV file automatically are applied to the existing line.
If you add or update a line during a bulk modify operation, you must specify the extension number in the CSV file; otherwise, the tool ignores the settings when the bulk operation runs. The tool only updates line settings that you specify in the CSV file. All other line settings retain the configuration that you specify on the Add or Manage Phone/Profiles configuration pages.
If you want to disassociate a line from a phone during a bulk modify operation, enter vpt_clear in the ccm_lineX_entension number column; specifying this information does not delete the line from the Cisco CallManager database.
Overview of Bulk Export Operations
Caution
If you schedule a bulk operation and do not have the appropriate privileges, the bulk operation fails. The Cisco Voice Provisioning Tool does not validate that you have the appropriate privileges when you perform a bulk operation.
If you want to do so, you can export users, phone, and device profiles that exist in product system database(s) to a CSV file. You can export only one record type, for example phones/device profiles or users, but not both at the same time. You must export at least one item, even if you export an empty file.
On the Manage Bulk Tasks page, you can modify a bulk operation that exists in the Scheduled, Pending, Finished, or Aborted state. You cannot modify bulk operations that exist in the Running state, but you can view operations in the Running state.
When you export users, the phone and device profile association information automatically is exported as part of the user record, but the other phone and device profile configuration information is not exported.
For security reasons, the Cisco Voice Provisioning Tool does not export passwords or PINs.
For phone and device profiles, you can check up to 36 lines in the attributes settings pane that displays during the bulk export configuration.
Overview of Bulk Provisioning States
By using the bulk provisioning functionality in the Cisco Voice Provisioning Tool, an administrator with the appropriate privileges for the product system(s) can provision many users at the same time by creating a CSV file and importing the file into the Cisco Voice Provisioning Tool.
The Cisco Voice Provisioning Tool supports one bulk operation at a time, but each operation exists in one of the following states:
•Scheduled—Operation will run at a specified time in the future.
•Pending—Operation is scheduled to run at the current time, but another bulk operation is already in progress.
If you schedule several operations to execute at the same time, the tool queues the operations in the order that you specified, moves the pending operation to the Pending state, and completes the operation that is already in progress.
•Running—The bulk operation is in progress.
•Finished—Operation is complete, and a log file exists. A message displays that indicates whether the operation succeeded or failed.
•Aborted—The administrator canceled the bulk operation, and the Cisco Voice Provisioning Tool creates a log file.
Overview of the Comma Separated Value (CSV) File
When you use the bulk administration functionality to import phone configuration information into the Cisco Voice Provisioning Tool, you must use a comma separated value (CSV) file that uses an ASCII or Unicode (UTF8 encoded) file format. A standard text editor or spreadsheet application that handles CSV files, for example Microsoft Excel, allows you to create a row for each record that you want to add or modify. The CSV file categorizes data into column sets, which are predefined, related sets of data. The phone/device profile CSV file, which is specific to the device type, contains a column set for the phone configuration settings and a column set for each line that is configured for the phone. You can combine multiple phone systems into a single CSV file.
The CSV file must contain either all additions or all updates; it cannot contain a combination of both operation types.
You cannot perform bulk operations for phones/device profiles and users at the same time, but you can perform bulk operations for phones and device profiles at the same time. You must use a CSV file to import phones/device profiles and a different CSV file to import users. Likewise, you cannot configure bulk export operations for phones/device profiles and users at the same time.
Not all settings that display in the CSV file are considered required settings.
You can combine phone/device profile configuration settings with line configuration settings in the same CSV file.
The Cisco Voice Provisioning Tool does not validate the format of the file. If the file format is corrupt or does not match the file encoding that you specify in the Cisco Voice Provisioning Tool, the bulk operation fails and reports the reasons for failure in the log file.
In addition to the previous information, consider the following guidelines when you create the CSV file:
•The order of the columns does not matter in the CSV file.
•The order of rows is important, because the tool adds or modifies the configuration based on the order that you specify for the rows.
•Make sure that all column header names are unique. If you repeat a header name, the information in the column on the left side of the file is overwritten by the information in the column on the right side of the file.
Caution
The bulk provisioning functionality ignores the case for the following parameters that you specify in the CSV file: On/Off, Disabled/Enabled, True/False, and options that display in drop-down list boxes; that is, it does not matter to the tool whether you enter upper case or lower case letters in the CSV file. For example, you can enter either "On" or "on."
The bulk provisioning functionality requires that you match the case for fields where you enter specific information for the configuration: for example, the user ID or user last name in the CSV file must match the configuration that displays in the GUI. If the case does not match for fields where you enter a specific configuration, the operation may fail.
•You can complete some optional fields and leave other optional fields blank. For example, if you want to specify the device security mode for a Cisco IP Phone model 7970 but you do not want to specify the mode for a different 7970, the tool accepts the configuration because the field is considered optional for the device.
•Any errors that are encountered for a row of data result in the row failing; if the row fails, the bulk operation continues with the next row.
•Any setting that you leave blank in the CSV file is not changed from its current value.
•If a setting allows or requires multiple values, enter a semicolon (;) between the values to separate the data.
•For all check boxes that display in the GUI, enter either true or false in the CSV file. The word "true" equals checked, and the word "false" equals unchecked.
•For all settings in the GUI, use the same terminology in the CSV file; for example, if you want to configure Cisco Extension Mobility for the phone, enter Enabled in the cell, just as you would choose Enabled from the drop-down list box on the specific Add or Manage Phone/Profiles configuration pages.
•For some settings, you can delete the configuration by entering vpt_clear in the cell. If you enter vpt_clear for a setting that cannot be cleared, the row fails during the import operation.
•Do not use the comma (,) in column cells because the tool uses the comma to separate rows. Instead, use the tilde (~). The tool converts the tilde to a comma when you import or export the data. If you want the tool to use the tilde character instead of converting it to a comma, enter a forward slash (/) before the tilde; for example, /~. The tool recognizes that you want to use the tilde character and not the comma, and the tool removes the forward slash during the operation.
•If you use Microsoft Excel as your text editor, consider the following information:
–Microsoft Excel removes leading zeroes from any field in the CSV file when it loads the CSV file. After you save the file, the leading zeroes are not saved, which may corrupt the data if the leading zeroes are important.
–If you perform a bulk export operation and specify UTF-8 encoding during the configuration, Microsoft Excel does not load the file correctly if you click the hyperlink and choose the option for opening the file with Excel. Therefore, for UTF-8 files, you must first save them to disk before you open them with Microsoft Excel.
–Microsoft Excel converts long numbers into scientific format when it loads the CSV file, for example, MAC addresses, long directory numbers, and so on. After you save the file, the scientific notation is stored as is, which corrupts the CSV file. To alleviate this problem, make sure that you change the format of the columns with long numbers before you save the file; for example, consider using a decimal number format with zero decimal places.
–Be aware that Microsoft Excel limits the number of columns in the CSV file to 256. If the file contains more columns than can fit into a single Excel worksheet, you can spread the configuration across worksheets within the Excel workbook; then, you can save each worksheet as a CSV file and use a utility such as csved to merge the files into a single CSV file that you can import.
For example, workbook1 contains worksheet1, worksheet2, and worksheet3. Worksheet1 contains basic and advanced phone configurations and phoneline1, phoneline2, phoneline3 configurations; worksheet2 contains phoneline4, phoneline5, phoneline6 configurations; worksheet3 contains phoneline7, phoneline8, phoneline8 configurations.
You can save worksheet1 as a CSV file, worksheet2 as a CSV file, and worksheet3 as a CSV file.
After you save all worksheets, you can use a utility such as csved to merge worksheet2 and worksheet3 to worksheet1. You can then import this new file by using the bulk import functionality in the Cisco Voice Provisioning Tool.
–For additional information about Microsoft Excel, see the Microsoft documentation for the application.
Related Bulk Administration Tasks
Bulk import and export operations are the main provisioning tasks that you perform in the Cisco Voice Provisioning Tool; for information on these tasks, see the "Overview of Bulk Import Operations" section and the "Overview of Bulk Export Operations" section.
In addition to bulk import and export operations, you can perform the following bulk administration tasks for users, phones, or device profiles:
•Download the bulk CSV file—Downloading the Bulk CSV File
•Delete a bulk operation—Deleting a Bulk Operation
•Abort a running operation—Aborting a Running Bulk Operation
•View bulk operations—Viewing Bulk Operations
•Review the bulk operation logs—Reviewing the Bulk Operation Logs
Downloading the Bulk CSV File
When the bulk operation exists in the running state, you cannot download the CSV file. After the bulk operation completes, you can download the bulk import file for import operations or the bulk export file for export operations.
To Download the Bulk CSV File
Step 1 Choose Voice Provisioning > Bulk Provisioning > Manage Bulk Tasks.
Step 2 On the Manage Bulk Tasks page, click the CSV file that you want to download.
Step 3 Choose the location on the client machine where you want to download the file.
If the file is not available for download, an error message displays.
Deleting a Bulk Operation
Because the tool does not remove bulk operations, you must delete operations that you no longer use. You can delete operations that exist in any state, except for the running state. Deleting the operation removes all associated files, including the import or export CSV file and the log files.
To delete the bulk operation, you must have the appropriate provisioning privileges for the product system(s) for which you plan to perform the task.
To Delete a Bulk Operation
Step 1 Choose Voice Provisioning > Bulk Provisioning > Manage Bulk Tasks.
Step 2 On the Manage Bulk Tasks page, check the check boxes for the operations that you want to delete.
Step 3 Click the Delete button or choose Action > Delete.
Step 4 A confirmation dialog box displays. Click OK.
Step 5 You can view the audit log output as described in the "Reviewing the Bulk Operation Logs" section.
Aborting a Running Bulk Operation
You can abort bulk operations that exist in the running state only. After you abort the operation, you may modify it, save the updates, and run the operation at a later time. If you choose to update and save the operation after you abort it, the tool discards the files for the aborted operation and creates a new log file for the update.
To Abort a Running Bulk Operation
Step 1 Choose Voice Provisioning > Bulk Provisioning > Manage Bulk Tasks.
Step 2 For the running bulk operation that you want to abort, click the Abort button.
Step 3 After the confirmation dialog box displays, click Yes.
Step 4 The page refreshes and indicates that the operation exists in an aborted state. You can click the link to modify the operation or download the log file.
Step 5 If you want to view the audit output log, see the "Reviewing the Bulk Operation Logs" section.
Viewing Bulk Operations
To view bulk operations (including running, pending, scheduled, completed, and aborted operations) by accessing the Manage Bulk Tasks page, you must have the appropriate provisioning privileges for the product system(s) for which you plan to perform the task. Although you cannot search for specific operations, you can specify the number of rows that you want to display on a single page or specify the page that you want to view. When you view bulk operations, the following information displays per operation:
•Bulk operation name, as provided by the administrator
•Bulk operation description, as provided by the administrator
•Name of the CSV file, which is either the import or export file name, depending on the type of operation that you performed
•Status of the operation; for example, Scheduled, Pending, Running, and so on
If the operation status equals Running, the Abort button displays under the word, Running, in the cell. If the operation status equals Finished, the words, Successfully or With Failures, display under the word, Failed, in the cell.
•Log file with the .log extension
•Date/Time
This column supports all operation types. For example, if you scheduled an operation that has not occurred, the information reflects the date and time when you scheduled the operation.
•User ID for the administrator that initiated the operation
Tip You can delete any of the bulk operation rows that display by checking the check box next to the Bulk Name column and clicking the Delete button.
To sort a column in the table, click the column header at the top of the table.
Reviewing the Bulk Operation Logs
Each bulk operation, like other provisioning actions, produces an audit log that you can view by choosing VPT Administration > View Audit Log and then clicking the name of the CSV file that displays on the page. The bulk operation audit log shows who specified the operation, when it began, when it ended, and any warning or errors that got generated during the operation. For more information on audit logs, see the Cisco Voice Provisioning Tool System Management and Security Guide.
In addition to the audit log, each bulk operation produces a separate log file that contains all auditing output for that bulk operation. Immediately after the bulk operation is completed or aborted, you can download and view this log file, which is translated into the same language that you use to browse in the Cisco Voice Provisioning Tool. The log file contains the following sections:
•Summary
–The operation name
–Description
–Scheduled execution time
–Number of rows that were successful
–Number of rows that encountered problems
–Status of the operation; for example, running, aborted, and so on
–Total elapsed time for the operation
•Detailed
This portion of the log looks like the audit log output that the Cisco Voice Provisioning Tool provides after you click the audit CSV file link on the View Audit Log page. You can save the detailed log output and use a text editor to create a spreadsheet that you can modify.
Tip To access the log file that contains the auditing output for the bulk operation, choose Voice Provisioning > Bulk Provisioning > Manage Bulk Tasks. After the results display on the Manage Bulk Tasks page, locate the Log File column and click the hyperlink for the log that you want to view.
Where to Find More Information on Bulk Provisioning
•Performing Bulk Operations for Users
•Performing Bulk Operations for Phones and Device Profiles
•User Settings for Bulk Provisioning
•Phone Settings for Bulk Provisioning
•Line Settings for Phone Bulk Provisioning
•Device Profile Configuration Settings for Bulk Provisioning
•Line Settings for Device Profile Bulk Provisioning