Understanding Users and Contacts

Perform the new user synchronization from Control Hub, to migrate your users 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 or a Service number. The Personal contact is managed by an administrator.

The benefits of User 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 Control Hub 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.

  • 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.

Use the Migrate Users/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.


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 User/Contact Sync page, click Go to Settings under Prerequisites.

The Settings page appears.


Select the details from the following sections:

  • Rules to distinguish contacts from Unified CM end-users–Check all or 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. If any of the options is selected and is true, the tool classifies the Unified CM enduser record as a contact.


    Select at least one identification rule to proceed.

    • Not synced from LDAP server to Unified CM database.

    • Manager user ID is missing.

    • No device associated

    • Department ID is missing.

    • User ID contains a string.

    • Department ID contains a string.


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.