HCS Intelligent Loader

HCS Intelligent Loader Introduction

The HCS Intelligent Loader (HIL) is used to perform bulk operations like bulk add, delete, and update on Cisco Unified Communications Domain Manager. Using the HIL, you can map the user data information to the Cisco Unified Communications Domain Manager information. When the data is loaded, HIL mapping is used to translate data between the source (user data) and destination (Cisco Unified Communications Domain Manager) formats. HIL validates the user data and corrects errors, if any.


Note

HIL relies on Cisco Unified Communications Domain Manager for user authentication. If a user is configured on Cisco Unified Communication Domain Manager, the same credentials are required to access HIL. In Cisco Unified Communications Domain Manager, users can only use Single Sign-On to access the GUI.


Note
To use HIL, the Cisco Unified Communications Domain Manager version you are using must support it.
Table 1 Common HIL Terminology

Term

Definition

Model

The models are derived from Cisco Unified Communications Domain Manager and conform to the customized display policies for the hierarchy.

Mapper

The mapper file is the bridge between the HCS Intelligent Loader column and the Cisco Unified Communications Domain Manager GUI field.

Loader

The loader file contains the data.

Hierarchy

The HCS Intelligent Loader uses the same hierarchy as Cisco Unified Communications Domain Manager. For more information, see Cisco Unified Communications Domain Manager, Release 11.5(1) Planning and Install Guide or Control Row.

Loader File Introduction

Control Column

The first column of the loader is the Control Column.

The control column can use the following values at the start of the column:

  • # - Comments out a row. You can have a dedicated control column, ideally the first column. When the row's first column has # or starts with #, HIL will consider it as commented row and does not validate nor load the row.

  • *<#> - Multiple rows are grouped together using * followed by an integer . The number next to * indicates the no of rows starting the current row, that needs to be grouped together. . This means the next rows (the number specified after *, minus one) will not be used for validation, but only for loading. The rows will be grouped together with the master row, and loaded as one transaction. For example:

    • *2 = group the current row with the next row.

    • *3 = group the current row with the next two rows.

    • *1 = only the current row.

Control Row

The control row can be any row after the column headers or titles. At each control row, HIL sets the hierarchy to the hierarchy designated in the control row. The data in the following rows is loaded to the hierarchy specified.

You can use the control row to load data to multiple hierarchies, for example $hierarchy:sys.hcs.provider.customer.

Primary Key Identification

Primary Key Identification is an unique key for each record. The key is automatically generated, when records are successfully loaded in Cisco Unified Communications Domain Manager.

Macro Support

The HCS Intelligent Loader supports macros in any column, except the columns headers or titles in the loader sheet.

  • If you prefix the data with "?", the Cisco Unified Communications Domain Manager macro value is evaluated and replaced with the result of evaluation, and then the replaced value gets loaded into the loader.

  • If you don't prefix the data with "?", then the Cisco Unified Communications Domain Manager existing macro value is loaded into the loader.

Set Up HCS Intelligent Loader

Set up the HCS Intelligent Loader platform through an HCM-F service.

Before You Begin

  • Ensure Cisco Hosted Collaboration Mediation Fulfillment is installed.
  • Ensure that the DNS and domain are set correctly on the HCMF node (APP/WS) where HIL is running, as HIL should be able to resolve the hostname of the CUCDM.

Procedure
    Step 1   Log in to the HCM-F CLI as admin.

    HIL can be run on the WS node or the APP node.

    Step 2   To activate the service, enter the command utils service activate Cisco HCS Intelligent Loader Service.
    Step 3   To configure the HIL to communicate with the CUCDM server, enter the command set hcs hil target config.
    Step 4   When prompted, enter the following details:
    Option Description

    target type

    CUCDM

    Target Server Hostname

    <cucdm-hostname>

    In case of Multi-Node deployment use the proxy node details, for example the same details you use to access the CUCDM user interface.

    IP Address

    <cucdm ip address>

    The IP address is selected by default based on the DNS settings, or you can also reenter the IP address.

    Would you like to update the node information [yes/no]?

    Yes

    The "Target successfully updated in the Properties File" message is displayed.
    Step 5   Verify that the target setup is complete by entering the show hcs hil target config command. The HIL Target Node Configuration Details are displayed.
    Step 6   (Optional) Set the HTTP timeout parameter by entering the set hcs hil target timeout command. The system then prompt you for a value between 90 seconds and 30 minutes.

    HIL performs synchronous transactions while waiting for one transaction to be completed before starting another. If the wait is beyond the timeout value that is configured, a timeout occurs and HIL marks that row/record as appropriate in the "trans_status" column for that row.

    Step 7   Navigate to the following URL: https://<hostname>/HIL.

    Use your Cisco Unified Communications Domain Manager credentials to log in.

    HCS Intelligent Loader Common Tasks

    This section describes common tasks used in HIL.

    HCS Intelligent Loader Provisioning Workflow

    The following workflow outlines the tasks for bulk-adding operations.

    Before You Begin

    Create at least one customer and site in the Cisco Unified Communications Domain Manager before you start using the HIL to create mappers.

    Procedure
      Step 1   Navigate to https://<host name>/HIL and sign in to HIL using your Cisco Unified Communications Domain Manager email id as your username.
      Step 2   Select the model from the menu on the left.
      Step 3   Select the required hierarchy at the top of the page.
      Step 4   Create mapper, see Create Model Mapper or Create Multi Model Mapper.
      Step 5   Add field values to source file by choosing one of these options:

      Option

      Description

      HIL Edit

      You can use the HIL interface to view or edit the source file.
      Note   

      Do not change the Primary Key Identification column, to avoid corrupting the data.

      Spreadsheet Edit

      You can edit the source file directly by following these steps:

      1. Download to desktop the source file.

      2. Add or Edit the values into the source file spreadsheet.

      3. Upload from desktop the source file back into HIL.

      Note    To edit a particular field, search for the field by using control rows. For more information, see Edit or Delete Using search_​field

      For more information, see Loader Tab Reference.

      Step 6   Validate the source file, see Validate a File. You must validate files before adding, editing, or deleting data in Cisco Unified Communications Domain Manager.
      Step 7   Submit the source file to Cisco Unified Communications Domain Manager, see Submit to CUCDM.

      HCS Intelligent Loader Updating Workflow

      The following workflow outlines the normal tasks with bulk updating.

      Procedure
        Step 1   Navigate to the following URL https://<host name>/HIL and login with your CUCDM credentials
        Step 2   Select the model from the menu on the left.
        Step 3   Select the required hierarchy at the top of the page.
        Step 4   Select the Loader tab.
        Step 5   Select the file in the table.
        Step 6   Edit field values to source file.

        Option

        Description

        HIL Edit

        You can use the HIL interface to View/Edit the source file.

        Spreadsheet Edit

        You can edit the source file directly by:

        1. Download to desktop the source file.

        2. Adding/Editing the values into the source file spreadsheet.

        3. Upload from desktop the source file back into HIL.

        For more information, refer to Loader Tab Reference.

        Step 7   Validate the source file, refer to Validate a File. You must perform validation before adding, editing, or deleting data in Cisco Unified Communications Domain Manager.
        Step 8   Submit to CUCDM, refer to Submit to CUCDM.

        Edit or Delete Using search_field

        The following table outlines how to specify a search_field in the Control Row.

        Options

        Description

        $search_field: field_name
        Field_name is the name of the field in the Cisco Unified Communications Domain Manager.
        Note   

        HIL sequentially searches the existing source file, defined in the search_field. If HIL finds multiple results for a search, then HIL marks it as a Record Not Found for that row.

        $search_field: userid

        HIL searches for the user ids and it compares with the user ids available in Cisco Unified Communications Domain Manager. When the user ids match, HIL retrieves the corresponding Primary Key Identifications and then you can edit or delete the matching record.

        $search_field: userid&lastname

        You can search for multiple field values using "&" between the field values.

        $hierarchy:sys.hcs.p1.c1; search_field: userid

        You can specify a search_field in the same Control Row along with other Control Row properties, using a semicolon (;) between the two properties.

        $hierarchy:sys.hcs.p1.c1

        $search_field: userid
        You can specify a hierarchy and search_field in separate Control Rows, that is, each property can reside in its own Control Row. The hierarchy can be specified in one row and the search_field can be specified in another row.
        Note   

        HIL allows you to use the latest search field, in case there are two different search_fields used in the Control Row.

        Order_by
        When Primary Key Identification and the search_field are not available (or the field specified in the search_field is not valid), then HIL uses the order_by field. Order_by field is used by Cisco Unified Communications Domain Manager to get the list of the source files.
        Note   

        In the case of a relation or subscriber, the default order_by field is userid.

        Create Model Mapper

        Procedure
          Step 1   Select the model from the menu on the left.
          Step 2   Select the required hierarchy at the top of the page.
          Step 3   Select the Mapper tab.
          Step 4   Click Create. The Create Mapper: <Model Name> window opens
          Step 5   Enter a Name and Description for the mapper.
          Step 6   Select a Source File, either by selecting Choose from uploaded files or Upload new file from desktop.

          You create the source file on the Loader tab, by performing an Import from CUCDM or Upload from Desktop prior to creating the map.

          The mandatory fields for the model selected load automatically. To load all fields click Map All or Add Row. If you add a row, you will need to select the Target Field and Default value.
          Important:

          • Source Fields: Populated by the first line of the import file / loader (can be any string).

          • Target Fields: The actual field as it appears in Cisco Unfiled Communications Domain Manager.

          • Default Values: This value will be used to populate the field in Cisco Unfiled Communications Domain Manager, if it is empty. If you want to override the value, select the checkbox.

          Step 7   Click Save Changes to save the changes or click Close to close without saving the changes.

          Example:When you create a mapper for subscriber model, by default, the mapper displays minimum mandatory fields that are required for adding a subscriber. If user adds any fields related to phone, the mapper will automatically populate, a set of dependent fields (phone) that are required to successfully add phone along with subscriber.

          • The mandatory fields that are populated automatically for mapping are not driven by the HIL's field values but by the field values of the Cisco Unified Communications Domain Manager. That is you may notice same source and target fields maps automatically. If there are any changes in the source field then you must select the field values from the drop-down list.



          Example:In Cisco Unified Communications Domain Manager Quick Add Subscriber, when you check the checkbox for voice, additional fields such as phone type and phones are displayed. In HIL, if you want to add voice, the fields voice, phone type, and phones must mapped manually. When you add a row for specific models, all the dependent fields appears in target field. While mapping them with the source field, you must select the fields values from the drop-down list.

          • For specific models, HIL mapper displays more fields than Cisco Unified Communications Domain Manager, because HIL does not hide the fields, while Cisco Unified Communications Domain Manager hides the fields with some default values. The hidden values from Cisco Unified Communications Domain Manager shows in HIL as default values.

          Create Multi Model Mapper

          Procedure
            Step 1   Select HIL Menus > Multi Model Mapper.
            Step 2   Select the required hierarchy at the top of the page.
            Step 3   Click Create. The Create Mapper: Multi Model Mapper window opens
            Step 4   Enter a Name and Description for the mapper.
            Step 5   Select a Source File, either by selecting Choose from uploaded files or Upload new file from desktop.
            Step 6   Select a Source Sheet.
            Step 7   Select a Model.
            Step 8   Click Load. The mandatory fields for the model selected load automatically. To load all fields click Map All or Add Row. If you add a row, you will need to select the Target Field and Default value.
            Important:

            • Source Fields: Populated by the first line of the import file / loader (can be any string).

            • Target Fields: The actual field as it appears in Cisco Unfiled Communications Domain Manager.

            • Default Values: This value will be used to populate the field in Cisco Unfiled Communications Domain Manager, if it is empty. If you want to override the value, select the checkbox.

            Step 9   Click Save & Close, to close the window, or Save & Continue, to load another mapper.

            Validate a File

            You must validate the source file before adding, editing, or deleting data in Cisco Unified Communications Domain Manager. Validation varies based on the operation:

            • When you add data into Cisco Unified Communications Domain Manager, HIL will validate all data in the selected source data sheet.

            • When you edit data in Cisco Unified Communications Domain Manager, HIL will validate the selected fields from the spreadsheets.

            • when you delete data from Cisco Unified Communications Domain Manager, HIL will validate only the selected fields from the spreadsheets.


            Note

            Add, edit, and delete operations are disabled or enabled based on the permissions in Cisco Unified Communications Domain Manager.

            Procedure
              Step 1   Select the model from the menu on the left.
              Step 2   Select the required hierarchy at the top of the page.
              Step 3   Select the Loader tab.
              Step 4   Select the file name you want to validate.
              Step 5   Click Validate, and then select the type of validation.
              Step 6   The validate window will open. Click Validate.
              Step 7   Click OK on the validation status window.
              Step 8   Check the File Status for validation status message.

              • VALIDATION IN PROGRESS: When validation of file is in progress (full or partial validation)

                Note   

                Full Validation: When all the fields of Excel spreadsheet are validated.

                Partial Validation: When some of the fields of Excel spreadsheet are validated.

              • VALIDATION ERRORS: When validation is complete and have errors (full or partial validation)

              • VALIDATION FAILED: When validation fails to kick off or exceptions (full or partial validation)

              • VALIDATION COMPLETED: When validation is complete successfully (full or partial validation)

              • VALIDATION PROLONGS: When validation status does not change withing 5 seconds. Click on Refresh Table icon to update the validation status

              Submit to CUCDM

              You can load the Excel spreadsheet into Cisco Unified Communications Domain Manager. You can perform add, edit, or delete functionality while submitting a file in Cisco Unified Communications Domain Manager.

              Before You Begin

              Files must be validated with the status "VALIDATION COMPLETED"

              Procedure
                Step 1   Select the Loader tab.
                Step 2   Select the file you want to submit.
                Step 3   Click Submit to CUCDM, and select one of the following:
                Option Description
                Add

                To add field values in CUCDM.
                Edit
                To edit field values in CUCDM.
                Note   

                While updating the subscriber you can add new services to the subscriber (such as EM, RDP, WebEx, VM etc..), when HIL detects a new service is being added to the subscriber, the new service is added through a separate child transaction and though this transaction fails, HIL does not capture the result of this transaction and only accounts the status of the parent transaction. For example; while updating a subscriber, if you add VM to the subscriber, along with modifying the subscriber itself, then adding VM will be a separate child transaction, and even if adding VM fails, and the update of Subscriber succeeds the "trans_status" in the loader file is shows as Success.
                Delete

                To delete field values in CUCDM.

                To delete a model, delete associated models in the reverse order of the Add operation.



                Example: To delete the associated SIP trunk, follow the order as mentioned:

                1. Disassociate the analog gateway from the site.

                2. Delete the analog gateway.

                3. Delete the SIP trunk.

                Note   

                Delete is disabled for Site Management and Customer Management, because they have Delete Site and Delete Customer options.

                Step 4   Select the sheets you want to submit.
                Step 5   Click Load.

                After the loading begins, an icon is displayed at the extreme right of the File Status message. You can click this icon to see the progress status of the file. When the file is loaded, a success message is displayed

                Graphical User Interface Reference

                This section describes the HCS Intelligent Loader.

                Cisco Unified Communications Domain Manager and HCS Intelligent Loader Models

                The HCS Intelligent Loader home page displays the various Cisco Unified Communications Domain Manager and HIL models. The models that are displayed are based on the user permissions and display policies that are associated with the administrator's account on the Cisco Unified Communications Domain Manager.

                The following table contains a sample model list:

                Cisco Unified Communications Domain Manager Models

                Customer Management

                Customers

                Delete Customer

                Network Device Lists

                Site Management

                Sites

                Defaults

                Delete Sites

                Device Management

                CUCM | Servers

                CUCM | SIP Trunks

                CUCM | Route Groups

                CUCM | Route Lists

                CUCM | Device Pools

                CUCM | Regions

                CUCM | Route Patterns

                CUCM | Translation Patterns

                CUC | Servers

                CUP | Servers

                WebEx | Servers

                Prime Collab | Servers

                IOS | IOS Devices

                IOS | Analog Gateways

                IOS | SIP Local Gateways

                IOS | Command Builder

                LDAP Management

                LDAP Server

                LDAP User Sync

                LDAP Schedule

                Entitlement

                Device Types

                Device Groups

                Catalogs

                Profiles

                User Management

                Users

                Provisioning Status

                Sync & Purge | LDAP Users

                Sync & Purge | CUCM Users, Lines, Phones

                Manage Filters | Define Filters

                Manage Filters | Filter Order

                Self Provisioning | User Profile

                Self Provisioning | Line Mask

                Self Provisioning | Universal Device Template

                Self Provisioning | Universal Line Template

                Move Users

                Manage Users

                Local Admins

                Dial Plan Management

                Customer | Dial Plan

                Customer | Add Directory Number Inventory

                Customer | Add E164 Inventory

                Site | Dial Plan

                Site | Class of Service

                Site | Short Code

                Site | Directory Number Routing

                Site | Sip Route Pattern

                Advanced Configuration | Dial Plan Schema

                Advanced Configuration | Dial Plan Schema Group

                Advanced Configuration | Associate Custom Dial Plan Schema Group

                Subscriber Management

                Lines

                Agent Lines

                Directory Number Inventory

                E164 Inventory

                E164 Associations ( N to DN )

                E164 Associations ( N to 1 DN )

                Phones

                Subscriber

                Quick Add Subscriber

                Quick Add Subscriber Groups

                Voicemail

                WebEx

                PLAR (Hotdial)

                Hunt Groups

                Call Pickup Groups

                Services

                Voice Mail | Voice Mail Service

                Voice Mail | Associate Voice Mail Service to Customer

                Voice Mail | Pilot Numbers

                Voice Mail | Associate Pilot Number to Site

                Contact Center | Servers

                Contact Center | Service

                HIL Models

                HIL Menus

                Multi Model Mapper

                Loader Tab Reference

                The following table outlines the functions available on the loader tab.

                Item

                Description

                Select Template

                Drop down to select the available mapper templates.

                Preview

                Displays a preview of the selected mapper template.

                Upload from desktop

                Allows the user to upload a file from their computer.

                Download to desktop

                Allows the user to download a file to their desktop. Users can then edit the spreadsheet and then upload.

                Delete

                Deletes the file from HIL.

                Rename

                Renames the file.

                Import from CUCDM

                Allows the user to select to import the content from CUCDM. The model schema will determine what information is available in the spreadsheet.

                Copy

                Copies the file

                View/Edit

                Allows the user to view and edit the file in HIL.

                Submit to CUCDM

                Allows the user to select to export the loader file into CUCDM. Users can select Add, Edit, Delete.

                Validate

                Allows the user to validate the content in the file before, and must be completed before submitting to CUCDM.

                Note   

                Add, edit, delete operations are enabled based on the permissions of the user.

                Search

                Allows the user to search for a file.

                File

                Displays the file name.

                Last Used Template

                Displays the mapper template last used for the loader file.

                File Status

                Displays the status of the last action performed with the file.

                File Status

                The following table describes the file status.

                Status

                Description

                FILE IMPORTED

                When data is imported successfully from Cisco Unified Communications Domain Manager.

                FILE IMPORT FAILED

                When file import from Cisco Unified Communications Domain Manager fails.

                FILE IMPORT IN PROGRESS

                When file import from Cisco Unified Communications Domain Manager is in progress.

                FILE MODIFIED

                When a file is modified from the View or Edit.

                LOAD COMPLETE WITH ERRORS

                When loading of a file is complete but record shows error in loading the file.

                LOAD FAILED

                Load failed due to network issues or exceptions.

                LOAD IN PROGRESS

                When load is in progress.

                LOAD SUCCESSFUL

                When load completed successfully without errors.

                NEW FILE

                When a new file is uploaded from desktop.

                NO STATUS FOUND

                When no status for the file is available.

                VALIDATION COMPLETED

                When validation is complete successfully (full or partial validation).

                VALIDATION ERRORS

                When validation is complete and have errors (full or partial validation).

                VALIDATION FAILED

                When validation fails to kick off or exceptions (full or partial validation).

                VALIDATION IN PROGRESS

                When validation of file is in progress (full or partial validation):

                • Full Validation: When all the fields of Excel spreadsheet are validated.

                • Partial Validation: When some of the fields of Excel spreadsheet are validated.

                VALIDATION PROLONGS

                When validation status does not change withing 5 seconds. Click on Refresh Table icon to update the validation status.

                Mapper Tab Reference

                The following table outlines the functions available on the loader tab.

                Item

                Description

                Create

                Opens the create window.

                Delete

                Deletes the file from HIL.

                Edit

                Allows the user to edit the file.

                Download to desktop

                Allows the user to download a file to their desktop. Users can then edit the spreadsheet and then upload.

                Upload from desktop

                Allows the user to upload a file from their computer.

                Copy

                Copies the file

                Rename

                Renames the file.

                View

                Allows the user to view the file.

                Name

                Displays the name of the file.

                Owner

                Displays the owner of the file.

                Modified

                Displays the date the file was last modified.

                Last Modified by

                Displays the name of the user that last modified the file.

                Config Tab Reference

                After you click the config tab, you can view or edit the configured target system's (Cisco Unified Communications Domain Manager) host name and host ID.

                Field

                Description

                Target System

                Displays the name of the target system (CUCDM)

                Target System Host

                Displays the name of the target system host

                Target System IP

                Displays the IP address of the target system