Understanding Users and Contacts

Perform the new user and Organizational Contact (Org contact) synchronization from Control Hub, to migrate your users or Org contacts in Unified CM. Use this migration tool when you are not using the existing Webex methods to provision users such as Cisco Directory Connector, adding users manually or using bulk import in Control Hub. For more information, see Ways to add Users to your Control Hub Organization .

Use this table to understand the definition of user in Control Hub:




Is a person within an organization. He has a phone or a soft client assigned to him. An administrator manages the User.


Is a public space. For example: lobby or cafeteria phone, conference room, etc, that has a device and/or a machine account. Workspace is within an organization and is managed by an administrator.

Service Number

Is a machine account for a feature with or without a device. For example: Hunt group, analog access, voice Portal, VXML, RP, Meet-Me Conference, Instant Group Call, Group Paging, Flexible Seating Host, Find-me/Follow-me, Call Center, Broad works Anywhere Portal. Service Number is associated to an organization and managed by an administrator.

Personal Contact

Refers to user, workspace, Service number or an Organizational Contact. The Personal contact is managed by an administrator.

Organizational Contact (Org Contact)

Is a person or a contact number that is not associated with the organization. However, the person or a contact number can be searched by users or devices within the organization. The Organizational Contact is referred as Labeled User and is managed by an administrator.

Use the Migrate Users/Contacts to Webex card on Control Hub to do the following:

  • Classify users found in Unified CM database into users and organizational contacts using configurable rules.

  • Synchronize organizational contacts from Directory service/LDAP to contact service.​

The benefits of User or Organizational Contact synchronization are:

  • Provides seamless user search experience. By synchronizing users and contacts to cloud, this feature helps Webex app to provide search functionality similar to Jabber.​

  • Automates the task of synchronizing users from Unified CM database into Webex. This feature facilitates synchronization and simplifies migration task as sync done manually is error prone and time consuming.​


This release does not support Contact synchronization.


Before you start synchronization of the users, make sure that you meet the following requirements:

  • Get familiar with Control Hub.

    Webex Control Hub is the management interface for the Webex platform. For more information, see Get Started with Webex Control Hub.

  • Access with full administrator privileges.

    With full administrator privileges, you can assign one or more roles to any user in your organization. Ensure to assign a user with administrator privilege so you can migrate the rest of your Unified CM users. For more information, see Assign Organizational Account Roles in Webex Control Hub.

  • Set your preferences for sync. Select Go to settings.

  • Onboard all the Unified CM clusters to Control Hub to enable importing the Common Identity (CI).

  • Use Bulk Administration Tool (BAT) to migrate users.

    Use the Import/Export menu in the Cisco Unified Communications Manager application, to migrate users. See the Import Users Using the Bulk Administration Tool (BAT) for detailed information.

Import Users Using the Bulk Administration Tool (BAT)

Use the Bulk Administration Tool (BAT) in Cisco Unified Communications Manager application to export users from Unified CM, and later import to Control Hub and Webex Users. Complete these steps to import the users:


Select Bulk Administration > Import/Export > Export to export the contact lists of the migrating users from the current home cluster.

The Export Data window displays.

Choose Select All in the Select items to Export section.


Choose a filename for the exported list data. In the Job Description field, enter the description that you want to provide for the job. Export Configuration is the default description.


Click Run Immediately or schedule the job to run later. Click Submit.


Monitor the status of the export job. Use the Job Scheduler option in the Bulk Administration main menu to schedule and/or activate this job.


Do not modify or update the tar file after you export the file from Unified CM application.


Download the export file and store it for use later when the user migration is complete. Choose Cisco Unified CM IM and Presence Administration > Bulk Administration > Upload/Download Files.

From the Upload/Download window select the tar file and click on Download Selected.


Un-tar the .tar file to any location on your machine using the tar -xvf command. Extract the .csv file to the specified location. See the Cisco Unified Communications Manager Bulk Administration Guide for detailed information.


If you receive an error similar to: BAT TAR Upload Failed. Error detected parsing the header or Import failed during BAT file upload, then you must manually modify the tar file. Follow these steps if there is an upload failure:

For Linux/Windows system
  1. Un-tar the .tar file to any location on your machine using the tar -xvf command.

  2. Modify the file manually and tar the files using standard tar utility.

  3. Import the file.

For a MAC system
  • Using gnutar in MAC:

    1. Install guntar in MAC using the brew install gnu-tar command.

    2. Untar the file using the guntar command.

    3. Use gtar -cvf <tarfilename.tar> <files_to_be_included_in_tar> to modify the tar file or the csv contents.

  • Using the “--no-mac-metadata” option with standard tar command.

    1. Create a tar file using the standard “tar” utility in MAC with tar --no-mac-metadata-cvf <tarfilename.tar> <files_to_be_included_in_tar> command.

Use Migrate Users or Contacts to Webex card to synchronize users from on-premise deployment to Webex Control Hub.

From the customer view in Webex Control Hub, go to Services > Migrations.

Select a use case depending on the type of configuration you have:

  • Usecase1- Directory connector is unavailable and CCUC agent is not installed.

  • Usecase2- Directory connector is available and CCUC agent is not installed.

  • Usecase3- Directory connector is unavailable and CCUC agent is installed.

  • Usecase4- Directory connector is available and CCUC agent is installed.


On the Migrate Users/Contacts to Webex card under Unified CM Upgrade Utilities, click Get started. The User/Contact Synchronization page appears.


Use User/Contact Synchronization to synchronize a maximum of 20k users at a time. If there are more than 20k users, you can synchronize them in batches.


From the Control Hub dashboard, Go to Updates and Migration.


Select the User/Contact Sync tile and click Go to Settings under Prerequisites.

The Settings page appears.


Configure either the Unified CM or the LDAP server for user synchronization function. Select the details from the following sections:

  • Unified CM end-user list—Configure rules for Control Hub to identify users in the Unified CM database into end users and contacts

    Field Name


    Rules to identify contacts and users

    Check any of the following check boxes to identify Org contacts from Unified CM. This option allows separating contacts from the users as the Unified CM users may contain both users and contacts. You can set rules to distinguish contacts from users:

    • Synchronize all records as contacts.

    • Synchronize all records as users.

    • Custom

    If the selected option is Custom, the tool provides options to classify the Unified CM end-user record as contact. Rest of the identities are considered as Users.


    Select at least one identification rule to proceed.

    • Not synced from the LDAP server to Unified CM database.

    • Manager user ID is missing.

    • No device is associated.

    • Department ID is missing.

    • Department ID contains a string.

    • User ID contains a string.


    Choose the toggle to enable or disable synchronization of contacts or users from Unified CM to Webex.

    • Import Users—This includes all records that are identified as users from the Unified CM end-user list. It's based on the rules set on the card.


      When the Directory Connector is enabled, the Import Users toggle is disabled. So, you cannot perform user synchronization.

      You can only sync users from one source either Unified CM or LDAP and the selection is final.

    • Import Contacts—This includes all records that are identified as contacts from the Unified CM end-user list. The contacts include lobby phones, hunt groups, organizational contacts that the administrator configures. It is based on the rules set on the card.

    Select the Cluster

    Choose a cluster to migrate the contacts or users.

    Periodic audit

    Allows to peridically audit Unified CM end users list and Webex data to make sure it synchronizes every 7 days.

    Set time—Use this field to change the default audit interval

    Any changes to users and/or contacts on Unified CM, updates to webex within a couple of hours.

  • LDAP server—Choose these settings to synchronize users and contacts from the LDAP server to Webex. You can Synchronize contacts from both Unified CM and LDAP server, but users could be synchronized from one source - Unified CM or LDAP server. Once this source is selected, it can't be changed for this Org.


    You can only sync users from one source either Unified CM or LDAP and the selection is final.

    Field Name


    LDAP Periodic sync

    Enable or disable synchronization from the LDAP server.

    Periodic synchronization

    Allows to periodically synchronize all users and/or contacts from LDAP server to Webex.

    Add Configuration

    Choose a cluster filter to synchronize contacts and/or users. Control Hub LDAP server supports multiple configurations for the clusters. Click Add Configuration to configure LDAP server related configurations. The Control Hub LDAP server uses the Unified CM LDAP search credentials connect to LDAP server.

    • Cluster name—Select the cluster name.

    • Configuration—Choose from the two modes - Customer Use Unified CM LDAP search. Use Unified CM LDAP search selection allow tool to pick up the Unified CM LDAP search configuration to sync users or contatcs. Custom configuration allows a user to define the synchronization settings.

      • LDAP system—Choose OpenLDAP or Microsoft AD as Source LDAP server.

        Open LDAP when we use metadirectory such as Recos.

      • Synchronization type—Select the type of sync either user or contact.


        If you have already selected users synchronization from Unified CM settings or User sync through Directory connector is configured, then User sync option will not be available here.

      • Custom Filter—Custom filter for users or contact synchronization.

      • LDAP Search Base—LDAP server search base for user or contact synchronization.

        An admin can add up to three search bases separated by "&&".

      • UC Directory Service Profile—Select one of the Unified CM configured UC Service of Type Directory.


Click Save and proceed. The Pending for sync section appears.

Displays the users or contacts that are imported using the BAT file from Unified CM enduser's list. This data is categorized based on the selected preference.


In the Pending for sync section, choose one of the following options:

  • Drag and drop the tar file.
  • Browse to the location of the tar file, select the file, and then click Open.

Note: The tar file contains a collection of CSV files.

After uploading the file successfully, the following identity details appear on the screen:



Total imported

Displays the total number of identities that are imported from the Unified CM using the BAT file. This identity displays active CM users.

Contact to be synced

Displays the total number of contacts that are pending to be synced to Webex. This identity count includes contacts that are removed from the review list or failed during sync.

Contact already in Webex

Displays the total number of contacts that are already synced to Webex.

Users to be synced

Displays the number of users that are pending to be synced to Webex. This identity count includes users that were removed from the review list or failed during synchronization.

Users already in Webex

Displays the total number of users that are already synced to Webex.


Click Import New Data to delete the imported file. If you have uploaded a wrong file or want to update the identity details, you can delete the imported file. See Import New Data for details.


Click Review for sync. The Review for sync page allows you to review the list of user and contact details before you start the synchronization. You can fix the flagged errors before the users are synchronized.

If you have uploaded the wrong file or want to update the identity details, you have an option to delete the imported file. You can also delete any pending migration tasks or delete failure report. After you delete the data, you can reupload the file and proceed.

To delete the imported data, click the Import New Data ellipsis icon displayed at the top on the Pending for Synchronization page. The Import New Data dialog box appears with the following options:

Ensure that you are aware of the consequences of your action. The action cannot be undone.

  • All previously imported data will be deleted.

  • All unsynchronized records will be deleted.

  • All synchronization logs will be deleted.


Check all the three options and then click Delete.


The Delete button is enabled only after you check all the options.


After you delete the data, upload the file with the updated data and then click Review for sync.

Review the data before you start the synchronization. Use the search field to search for the identities and sort them based on the filters.

From the Pending for Sync section, click Review for sync. The Review users before synchronization page appear.


Review the error details and fix the errors. The error classification is as follows:



Invalid Email

Invalid emails ID refers to incomplete ID or duplicate ID. Users with invalid email IDs cannot be synchronized. Fix the error in the email ID or you can remove the contact details. You can fix the invalid email IDs from the Summary page.

User Already exists in Webex

Users who are already in Webex and cannot be synchronized again. You must remove the details from the Summary page.

Missing Telephone number/Extension

Users without telephone number or extension cannot be synchronized and it is not mandatory to fix this error. You cannot add the missing telephone number or extension details from Control Hub and therefore remove these users.


From the View Users page, click Actions to perform the following tasks:

  • Export these rows: Choose this option to export all the available records.
  • Import updated file: Choose this option if you want to view the updated file details.
  • Reset user list : Choose this option if you want to clear the existing user list details and update it again on the Summary page.

Click Next. Displays the Review contacts before synchronization page.


If the display name is changed, you must update the Unified CM contact details. Use the export list of updated records from the Control Hub in Unified CM, to import the changes.


In the Review contacts before synchronization page, you can perform the same set of tasks such as Search, Sort, Edit Settings, and Change user/ Contact Rules.


Click Next.

The Summary page appears.

The Summary page lists the error and warning messages for the selected users and contacts. It also provides you with the necessary suggestions and solutions to resolve them. Resolve the errors before you proceed. However, you can ignore the warnings.

Note: You can also remove the identities (user or contact) with errors and proceed. The removed identities are added back to the unsynchronized list.

To resolve the user errors, click View Errors and select Remove from sync list.

When you use the Remove from sync list option to remove users from the Summary page, the User sync count on Control Hub is not updated.


You can view the count of these invalid identities:

  • Users with Invalid Email IDs.

  • User Already exists in Webex and they cannot be synced.

  • Users with Missing Telephone number/Extension.


The users and Org contact details in the review wizard is reverted when the Settings page is updated.

Export updated records- we recommend updating the Unified CM contact list for any changes made to the records. Click Expost list, to download the updated records and manually update them in Unified CM.


Click Start synchronization.

The Syncing identities progress bar displays during sync and you cannot perform any action till the sync completes. The Latest synchronization tab displays the user sync count after the sync operation completes.

The Logs page appears with the Synchronization summary.


View the status of the synchronization from the Logs page. This page displays the Users that are synced and also the reason for failure, if any.


Click Export csv, to download the user list.