The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Cisco Hosted Collaboration Solution supports Cisco Unified Communications Domain Manager 8.1(x) and Cisco Unified Communications Domain Manager 10.6(1). However, this document only applies to Cisco Unified Communications Domain Manager 10.6(1). For information regarding bulk provisioning on Cisco Unified Communications Domain Manager 8.1(x), see Bulk Loader Guide for Cisco Unified Communications Domain Manager 8.1.4.
The bulk loader tools let you quickly and easily manage system data using pre-populated Microsoft Excel spreadsheets. The system generates a spreadsheet template for any GUI or API resources in the system. Column headers specify the hierarchy, action, search criteria, and attribute names of the model where the data applies. Use a single sheet in the file to manage multiple templates by adding additional header rows and data under them. A file can include multiple sheets with one or more templates on each.
A loaded file can be processed immediately or scheduled for a later date and time. A scheduled bulk load file is listed on the Schedule list view as a Single Execution schedule type and with resource type of data/BulkLoad. Items on the Schedule list are deleted once they have been executed. After a scheduled bulk load has been executed, you will no longer see it in the list of schedules.
The system creates a single parent transaction for the entire bulk load. Unless a sheet is set to execute rows in parallel (at the same time), each row in the bulk load sheet results in a separate sub-transaction that is executed sequentially and synchronously. If a single sub-transaction fails, the bulk load transaction continues and does not roll back the earlier sub-transactions. In the case where a bulk load sub-transaction has other sub-transactions, for example, a provisioning workflow with multiple steps, if any step fails, the system rolls back all the steps in the bulk load sub-transaction.
If a sheet is set to process rows in parallel, then by default, 14 rows are processed in parallel.
If a file is processed and further files are loaded, they are processed at the same time. The system executes bulk load transactions in parallel, as with all transactions. Bulk load transactions are executed immediately.
Once the system starts the transactions, you cannot cancel them.
Data can be exported in JSON format and as MS Excel spreadsheets.
The system JSON file format is used to Export and Import various operations on model instances. The operations available via JSON files are: Add, Modify, Delete. This Import and Export task is carried out from the GUI or API using the file Export and Import functionality.
The JSON file format for the different operations is available from the Action button on the GUI form of the specific model and choosing JSON as Export format from the drop-down list on the Export menu. The API provides a request URL and parameter for this task. The export file format is a compressed JSON file. The import filename and format can be <filename>.JSON, <filename>.JSON.zip or <filename>.JSON.gz.
The Excel file format for data export of selected items can be carried out in the list or instance view of a model.
The commands are available from the Action button on the GUI form by choosing either Excel or Excel (formatted) from the drop-down list on the Export menu. The API provides a request URL and parameter for this task. The export file format is a MS Excel XLSX file.
The Cisco Unified Communications Domain Manager 10.6(1) multi-domain core supports the ability to generate an Excel format spreadsheet bulk load template for any of the resources in the system directly from the user interface. You can use a bulk load template spreadsheet from a model to create a template for the user interface. This template can be populated with data and loaded using the Bulk Load Administration tool.
Excel Bulk Load operations using spreadsheets support multiple (tabbed) worksheets that are loaded in tab sequence. Defined Configuration Templates on the system can be referenced in the sheets and applied during the Bulk Load operation.
The field-specific help of the product can be used to assist the user with populating the bulk loaders with the correct data.
An exported bulk load template is a workbook containing a single sheet and serves as the basis for bulk loading. You can also create a tabbed workbook, that contains more than one sheet. For tabbed workbooks, bulk load transactions are executed from the leftmost sheet or tab to the right. For example, if a site is to be added under a customer, the customer sheet tab should be to the left of the associated site.
The workbook or spreadsheet, is in Microsoft Excel .xlsx format and the maximum file upload size is 4GB. You can specify any name for the file and load the same spreadsheet multiple times, although the best practice is to use different names.
To bulk load data, first verify existing information on the sheet and determine what information is required to prepare the worksheet for the results you want.
A common generated bulk load sheet contains the following information:
Sheet name: any name can be provided for the tab or sheet name. If the sheet name is prefixed with a # on the tab, the sheet is ignored during loading.
Row 1 - Resource: the exported bulk loader template has the resource as target entity (model) as well as the hierarchy shown on the top row of the sheet. Verify the entity in the first row of an exported sheet. The reference data in the first row is:
entity: {entity name}; hierarchy: {hierarchy}; parallel: False; template: {config_template}
{entity name}: the name of the model, in the format {modeltype}/{model name}, for example data/User
{hierarchy}: the hierarchy, in the format {level1}.{level2}.{level3}, where {level1} is the first system level. Verify the hierarchy at which the bulk load should take place.
A column with the name # Hierarchy Node is also available so that individual rows of a sheet can be loaded to a specified hierarchy. If a hierarchy is specified in this column for the row, it takes precedence over the hierarchy in the first row. The format for the hierarchy in the row is the same as for the first row: the full hierarchy, with levels separated by dots.
parallel: True or False. By default, the value is False and rows are processed sequentially.
Sheet rows can be processed in parallel. The sheet should then not contain multiple, sequence-dependent models. If there are a large number of rows for complex models on the sheet, the duration of a bulk load transaction is significantly reduced by parallel processing.
By default, 14 rows are processed in parallel. Bulk loads are low priority transactions that are limited to 50% of the maximum allowed parent transactions, which are by default set to be 30 per unified node. The default value assumes that one slot is used by the parent bulk load transaction itself.
The maximum allowed parent transaction limit can be modified from the Command Line Interface (CLI) using the command:
voss workers <number>
template: The Configuration Template {config_template} that is associated with the user’s menu item for the {entity_name} from which the export was carried out. The exported sheet shows a row of values from the Configuration Template.
When a sheet is created to bulk load, the Configuration Template should be available on the target system and it will only apply to rows on the sheet that has create specified in the # Action column.
Comments: Any row that contains a # character in column A is considered a comment row and is ignored. Empty rows are also ignored. Column A - the first column - is also a # Comment column, so that any value entered in it is considered a comment. If all rows on a tab are commented, but the tab name itself is not commented, the tab sheet load fails.
Action: Any row that contains an action in the # Action column : create, delete, modify, execute or a custom action name, has the action carried out. The action values in the column are case insensitive. If no action is added, the add action is carried out. The list below shows the functionality for the values entered in the row. Also refer to the Search Fields entry below.
add or empty - the data in the attribute columns is added. Any values in the # Search Fields column are ignored.
delete - the row matching the unique criteria in the # Search Fields column is deleted.
modify - the row matching the unique criteria in the # Search Fields column is updated with values in the attribute columns. Refer to the Search Fields entry below.
execute - if the action is available for the model, the row matching the unique criteria in the # Search Fields column is executed, using any values entered in attribute columns.
custom action name - if the custom action is defined for the model, it is carried out for the row matching the unique criteria in the # Search Fields column.
Search Fields: The column applies to rows where the action is not add and consists of a colon-separated list of attribute names and values, for example, fullname:’John Smith’,username:jsmith.
delete - the search fields and corresponding attribute values uniquely identify the model instance to delete.
modify - the search fields and corresponding attribute values uniquely identify the model instance to modify, with the values to modify in the attribute columns.
execute - the search fields and corresponding attribute values uniquely identify the model instance to execute.
Device: The column is used when a sheet includes attribute columns that belong to a device model. This column then contains the comma-separated list of business keys of the device model, as well as its hierarchy. These values narrow the search for the device to which the data in the sheet applies. Examples of such sheets would contain device models or relations that have device model attributes in the left-hand association of the relation.
The format of the values in this column is:
<business_key1>,<business_key2>,...,<business_keyn>,<device_hierarchy>.
For example, if a Unified CM instance in a model data/CallManager has host and port as business keys, the value would be:
10.120.2.175,8443,sys.Varidion.InGen.Tokyo.
Network Device List: The column is used when a sheet includes attribute columns that belong to a device model. This column then contains the name (business key) of the Network Device List that includes the device attribute. If the Device column is also filled in, then the value in the Network Device List column overrides it.
CFT Template: If a row that contains a Configuration Template name that applies to the model, this template is applied to the row when it is loaded. Upon bulk loading, values in this column override any value for template in the sheet header.
Row 2 - Attribute names: Entity attribute names show as column header data in the spreadsheet. Columns can be in any order in a row. Nested object attribute names follow a dot notation.
Array objects are sorted, so that attributes with names such as filter_fields.<number>.xx is in sequence: filter_fields.0.xx, filter_fields.2.xx, and so on - before further ordering (represented by .xx here) is applied.
If a column header starts with a #, the column will not be loaded.
If a column header is blank, this indicates the end of the sheet header. Subsequent columns will not be loaded.
Attribute names are validated. This means that if a name is not valid, the bulk load will fail, and a validation error is displayed.
Row 3 - Group or description: The row provides a description of a column or else the group name of attributes that are grouped on the GUI: tabs on the detail or input form. This group is specified in the row by merging the group name across all the columns of the group. For attributes that are required and are not grouped in the GUI (or may be hidden in the GUI), the group name: Not Grouped Fields is given on the sheet. “Default” values of attributes in this group need to be removed from an exported sheet before the sheet is used to bulk load rows.
Row 4 - Title or Reference: The name of the reference for hierarchy, action, and so on, or the title that corresponds with the friendly name of the Column attribute as on the GUI and may be modified by a Field Display Policy.
Styles are applied to the exported sheet: dark colors for header rows, while mandatory fields have red title text headers. Optional fields are in white.
Although an attribute that has nested attributes may be optional, if this attribute has mandatory nested attributes, then the containing attribute becomes mandatory. If a field is mandatory, it is shown on the sheet regardless of any Field Display Policy instruction to hide it.
The Cisco Unified Communications Domain Manager 10.6(1) automation templates include a rich set of features that incorporate the use of configuration templates, customizable field display policies, and GUI rules that enhance the user experience of the user interface.
You can generate bulk load templates for resources that have limited ability to produce the same provisioning results obtained when using the user interface and require additional consideration.
An overview of these limitations is provided below:
You can use certain fields to link together different resources (for example, the name of the Cisco Unified Communications Manager remote destination links to the user ID of the user name).
These fields may not be exposed in the user interface or may, for some resources, be exposed as read only in the user interface. Such fields are currently exposed as mandatory fields in the generated bulk load templates. The fields and the specific conventions that are used in the template to link the fields together are highlighted in notes specific to the resource. For example, you can specify the value for remote destination name as RDP-<username>.
Certain fields are derived from other data in the system. The notes specific to the resource highlight where to get the possible values for such fields. Examples of this are key-value type fields of a phone’s vendor configuration settings.
Set a default value for a visible field (fixed value or derived from other data in the system). You should include this column and corresponding value in the loader for this to be provisioned.
Set a value for a hidden field - This column and corresponding value will have to be included in the loader for this to be provisioned. Note that this means that fields may be included in the loader that would not be visible in the user interface.
Make a field visible depending on some condition such as the value of another field (for example, a checkbox being selected). Include all necessary condition-defining columns and values in the loader.
A GUI Rule may disable input fields based on the state of a check box. On the spreadsheet, the selected check box is represented as TRUE in the column. The columns associated with the disabled fields should not be filled.
To overcome the complexities introduced by the above limitations, a set of sample bulk load sheets have been generated that enable users to get started quickly and to leverage the best practices developed by Cisco and partners.
Sample bulk loaders enable a quick start by providing working examples of the most frequently used loaders. These can be customized according to user requirements and data. Sample bulk load sheets incorporate best practices for using bulk loaders; ensuring rapid customer and subscriber on-boarding.
Note that the sample loaders are built according to the default Field Display Policies and Configuration Templates that are shipped with the product. Since these are configurable, the use of non-default Field Display Policies or Configuration Templates may result in a change of the sample loaders. For example, if an additional field is exposed by the Field Display Policy, it needs to be added if it is to be managed in the loader.
The latest sample bulk loaders can be obtained from your account team.
After you run a bulk load transaction, the transaction log is available on the user interface.
In the list view, the bulk load is shown in the Action column of the log. If the bulk load was scheduled, this is shown as a schedule with the detail column indicating it to be a bulk load.
The submitted, start, and stop time for the entire bulk load transaction is shown in the transaction detail.
In the list view, the Detail section displays the name of the file that is bulk loaded as well as the timestamp of the bulk load. For scheduled bulk loads, the detail section indicates the transaction as a “Bulkload”.
The system validates the user’s access profile, the provided hierarchy information, and data constraints for the bulk load transaction when updating the target models. The parent bulk load transaction will show the error message if this validation fails and no rows are loaded.
Where rows are loaded, each row in the bulk load spreadsheet appears as a sub-transaction within the bulk load transaction. The Message box shows the number of successful and failed rows loaded.
For each loaded spreadsheet, bulk load transactions are run in series for each row. Multiple bulk load spreadsheets can be loaded and these transactions will load at the same time.
Spreadsheet rows can be processed at the same time and should not contain multiple, sequence dependent models.
For each row of the bulk load sheet carrying out the default add action, a Create action is shown on the list of transactions. Sheet rows that led to a successful Create action have a Success status, while rows that failed show a Fail status. If a row fails, the load process continues. For failed actions, the transaction can be selected to show the error message.
If one or more rows of the spreadsheet failed to load, the Bulk Load action displays a Fail status, and the sub transactions status is Fail.
On the list of sub transactions, choose the transaction Link hyper-link to inspect the details of each sub transaction. For example, the submitted, start, and stop time for the bulk load sub transaction corresponding with a row on the bulk load spreadsheet is shown. In the case of a failed sub transaction, further information about the failure - such as the error message and row data - is shown in the sub transaction Link.
A canceled bulk load transaction means the processing spreadsheet sub transaction, and all sub transactions within the spreadsheet transaction in a processing or queued state, will fail.
For parallel transactions, multiple resource transactions may be in a Queued or Processing state. By default, 14 rows are processed in parallel. Refer to the Refer to the topic on Bulk Load Sheet Layout for more details. If a spreadsheet transaction fails as a result of bulk load transaction cancellation, subsequent spreadsheet tabs in the bulk load workbook will not be processed by the bulk loader.
You can download bulk loading templates from the Cisco Unified Communications Domain Manager GUI using the Actions menu on the upper right-hand side of the screen. You can select Export Bulk Load Template to open the file in Excel or to save the file to your desktop or removable storage device.
The information in the first row of the bulk load templates shows the required hierarchy node and relation.
However, in the HCS Intelligent Loader (HIL), the administrator identifies the hierarchy node and selects the model to be used.
When using the standard bulk load templates in HIL, the administrator must edit the template and remove the first row or comment it out by using "#" as the first character in the first row.
You can also use the bulk load templates to override the selected hierarchy. The administrator can add the following row to the excel sheet: $hierarchy:<HIERARCHY_VALUE>. This ensures that the operations will be performed at the hierarchy specified in the spreadsheet.
You can download the latest BulkLoading Template Reference Set from the following links:
|
Mode of Operation |
Mapper |
Loader |
Description |
|---|---|---|---|
|
ADD/DELETE |
Day1 provisioning (customer, site, adding UC APPS, adding dial plans, DN, LDAP servers, and subscribers) |
||
|
EDIT |
This sheet is used for editing subscribers. |
||
|
DELETE
|
This Sheet is used for deleting sites. |
||
|
This sheet is used for deleting customers. |
Cisco Unified Communications Domain Manager 10.6(1) reference templates
Download the bulk load template reference set, containing both loader and the mapper files. Mapper files contain the mapping references to the corresponding loader files that are downloaded. Mapper files must be updated with the proper column headers to use a different loader file.
Mapper files can be edited using Microsoft Excel. You can remove the fields which you do not intend to use, or add additional fields, as long as they are in line with the target fields of CUCDM.
The first spreadsheet includes templates that cover a sample workflow starting from adding a Cisco Hosted Collaboration Mediation Fulfillment node, building out a provider, and progressing through to adding a customer, customer application nodes, and finally adding sites and dial plan elements.
The second spreadsheet includes templates that cover directory number allocation, subscriber provisioning, subscriber device provisioning, and subscriber service provisioning.
For all spreadsheets, sample data is provided, but administrators need to update the spreadsheet to match the requirements and details of the deployment. Many templates also have several samples to provision the same item to provide flexibility.
All the bulk loader sample templates correspond to menu items within theCisco Unified Communications Domain Manager 10.6(1) GUI. However, the bulk loader templates include fields that are not in the GUI. These fields are hidden in the GUI and are pre-populated based upon rules and macros. When using the reference bulk loader samples, these hidden fields must be explicitly defined by the administrator. As a result, extra fields are displayed in the sample loaders that are not observed in theCisco Unified Communications Domain Manager 10.6(1) GUI. However, the functionality of the template in the sample bulk loader is equivalent to the same template being used with the associated menu item from the Cisco Unified Communications Domain Manager 10.6(1) GUI.
The bulk loader templates are organized in a logical, sequential flow, and assume a blank Cisco Unified Communications Domain Manager 10.6(1) system. Starting with the Cisco Hosted Collaboration Mediation Fulfillment device template, the templates are provided in order of provisioning sequence.
Cisco Unified Communications Domain Manager 10.6(1) loads a specific bulk loader sheet serially. Starting with the top template defined in the first tab of a spreadsheet and continuing from top to bottom and left tab to rightmost tab.
For parallel loading, create a new spreadsheet with the template information you want and load it into Cisco Unified Communications Domain Manager 10.6(1). If a spreadsheet is currently processing, loading a new one causes the system to process the new spreadsheet at the same time as the spreadsheet that is currently processing.
A combination of bulk loading, provisioning the GUI, and provisioning via the Cisco Unified Communications Domain Manager 10.6(1) API is possible with bulk, GUI, and API provisioning occurring in parallel.
During the loading of a bulk loader template, you can use the Transaction menu item to check the status, progression, and also to check for any loading errors.
HcsHcmfREL
HcsProviderREL
HcsResellerREL
HcsCustomerREL
HcsCallManagerREL
HcsUnityConnectionREL
HcsPresenceREL
HcsNetworkDeviceListREL
HcsSiteREL
HcsLdapServerREL
HcsWebExREL
HcsDpManageCustomerREL
HcsDpManageSiteREL
HcsDpVmServiceREL
HcsDpAssociateVmSvcToCustomerREL
HcsDpVmPilotREL
HcsSipTrunkREL
SubscriberPhone
Subscriber
DirectoryNumber
CallPickupGroups
HuntGroupRelations
You can load completed .xls format Bulk Load spreadsheets into the system immediately. First ensure that any Configuration Templates referenced in the spreadsheets are available.
You can enter data in the bulk load template spreadsheet and then upload it with the Bulk Load Administration tool.
Feedback