Knowlege base
Home / Imagicle UC Suite for Cisco UC / User Management / Synchronize Users against Cisco Webex Control Hub

Synchronize Users against Cisco Webex Control Hub

Article ID: 902
Last updated: 29 Nov, 2023

Imagicle UCX Cloud Suite can import users from Webex Control Hub, thanks to available Cisco Webex (XSI) APIs for this purpose.

Provided Webex APIs allow to import users from multiple Webex Organizations, if required.

Before configuring such import connector, please mind below-listed requirements:

  • Imagicle UC Cloud Suite must be in place, with a valid license subscription.
  • Imagicle UC Cloud Suite must be authenticated against Imagicle Cloud Services, as described in this article.
  • A Full Admin user belonging to Webex customer organization 

OAuth2 token for UCX Suite integration with Webex Calling Users' Synch

Customer must authorize Imagicle Webex Cloud Integration application called Imagicle Users Synchronization Connector to access own Webex organization data. The following permissions are granted to the Imagicle Webex Calling Integration application:

  • spark-admin:people_read
  • spark-admin:organizations_read
  • spark-admin:locations_read
  • spark-admin:telephony_config_read
  • spark-admin:xsi

These are the minimum permissions required to retrieve basic user information and read organizations information. Without granting such permission, we cannot provide the feature.

Procedure

Please connect to the Imagicle Onboarding Web Portal for Webex Calling MT and enter customer's data, including above mentioned Full Admin Webex user.

Once customer data has been entered, please proceed to next page and authorize the following application highlighted in red:

Please note that other tokens might be required for Webex Calling Native Call Control and to retrieve presence status from Webex Control Hub. Please consult relevant KB articles.

Once you have authorized all required tokens, please click on "COMPLETE REQUEST" to trigger the Imagicle internal process to enable the tokens.

Remarks

Imagicle apps authorization requires Webex apps integrations to be enabled by default. If not, you might get the following error message:

In this case, you can selectively authorize Imagicle applications by accessing Webex Control Hub ⇒ Apps ⇒ Integrations and locate Imagicle apps by Integration ID:

  • Imagicle UCX Suite Users' Synch from Control Hub:
C89a4ba3aa80c33dd80bfc17a1572c5026049234c0aa90b7793b47dac37d7fa6c
  • Imagicle Attendant Console Webex Presence Retrieval:
C1468e046a54f78620ca6d1b16eda8096165d0f960078c8e38c5ac09fb7f7f120
  • Imagicle Attendant Console Call Control:
C143958d8c8645673914400fbf4b06fa022da2a7caeac67b5eb48d062709cf24e
  • Imagicle Call Analytics CDRs retrieval from Control Hub:
C2b09ee9cb8a3ae94ae0e6417d7dcf7e33351ae00bbb22fb9937a79796a8371b5

Please consult relevant Cisco documentation here.

Admin User Authorizer

The authorization process involves a Full Admin user from the customer that, through his/her Webex account, authorize Imagicle Integration. The above mentioned authorization may automatically expire as soon as the authorizing user change his/her password. Once the authorization is removed, UCX Suite will no more be able to retrieve events related to that authorization (Webex users data). To recover the feature, a new authorization process must be executed. 

This limitation does not apply if the SSO for Webex is enabled.

If SSO in not enabled, a user password by default expires after five years, as per Cisco documentation (and an admin user can be created without requiring additional licenses).

This limitation is related to the authentication flow implemented by Webex, namely OAuth2 Authorization Code flow, that implies impersonating a user while accessing the Webex APIs. We are working with Cisco to remove this limitation.

The token is invalidated also in these two cases:

  • Authorizing Webex user is deactivated
  • Full Admin privileges are removed from the authorizing Webex user

Enabling Webex Users' Synch from Imagicle Web Portal

Once above OAuth2 token has been issued, you can proceed with actual Webex Cloud users' synch enablement.

Please access to Imagicle UC Suite web portal as Administrator and go to ADMIN ⇒ User Management ⇒ Synchronize users with an external data source » ⇒ Configure Data Sources >>

Select "Cisco Webex" and flag relevant entry, as per below screenshot:

If the "STATUS" indicator goes green, then it means Imagicle UCX Cloud Suite can reach Webex Cloud. Otherwise, please check below table for most typical error messages appearing underneath the red STATUS indicator:

Issue

Error message

ClientID/secret wrong configured

Client ID or Client Secret are misconfigured

Suite not enabled on Imagicle Cloud to users sync

UC Suite is not enabled in the Imagicle Cloud to synchronize users. Check OAuth2 token enablement.

the Imagicle Cloud is not reachable (on-prem UC Suite only)

Imagicle Cloud unreachable

Other

An unexpected error occurred while checking Imagicle Cloud connection

Proxy Support

If your Imagicle UCX Suite can reach Internet through a proxy, please configure it by following this KB article. Webex import connector supports proxy configuration.

Configuring Synchronization Rules

Please access to Imagicle UCX Suite web portal as Administrator and go to ADMIN ⇒ User Management ⇒ Synchronize users with an external data source » ⇒ Configure Synch Rules >>

Select "Cisco Webex", as per below screenshot:

The sync service uses the Webex Calling user's email as primary key. The username included in the email address populates the Active directory username field, while the domain (after @) populates the Domain field.

For all other users' fields, they are imported from a fixed Webex field or you can choose from which Webex field to populate them. See below table including Webex specific field mapping:

UCX Suite Display Name Mapping criteria Synched from Example Value
Active Directory username Import every time from source username coming from Email field john.smith
Domain Import every time from source domain coming from Email field company.com
First Name Import every time from source firstname John
Last Name Import every time from source lastname Smith
User PIN Only when adding, set this value 1234
Single Sign-On Id
  • Use the mail address field
  • Keep existing value
 Webex Mail john.smith@company.com
Conversational AI Username
  • Use the mail address field
  • Keep existing value
 Webex Mail john.smith@company.com
First extension number*
  1. Import every time from Webex field:
  • "ESN or Phone Number" 
  • "Phone Number or ESN"
  1. Keep existing value

ESN = location.routingPrefix + webexCalling.extension

Phone Number = webexCalling.countryCode + webexCalling.number

33 + 6623 or

+447259856623
First extension number Alias*
  1. Import every time from Webex field:
  • "Extension or Phone Number"
  • "Phone Number or Extension"
  • "ESN or Phone number" 
  • "Phone number or ESN"
  • "Work Phone"
  1. Use the email address field
  2. Keep existing value

Extension = webexCalling.extension

Phone Number = webexCalling.countryCode + webexCalling.number

ESN = location.routingPrefix + webexCalling.extension

Work Phone = workPhone

email = Webex Mail

6623 or

+447259856623 or

33 + 6623 or

+44984664564 or

john.smith@company.com
Device name
  • Import every time from source
  • Keep existing value
 webexCalling.nativeUserId jsmith
Preferred Device name
  • Import every time from source
  • Keep existing value
 webexCalling.nativeUserId jsmith
PBX Username
  • Import every time from source
  • Keep existing value
 webexCalling.nativeUserId

jsmith
Email
  • Import every time from source
  • Keep existing value
 Webex Mail john.smith@company.com
Department
  1. Import every time from:
  • "Organization Name" 
  • "Location Name"
  1. Keep existing value

Organization Name = organization.name

Location Name = location.name

 ACME Inc.
Recording Group name
  1. Import every time from:
  • "Organization Name" 
  • "Location Name"
  1. Keep existing value

Organization Name = organization.name

Location Name = location.name

 ACME Inc.
Cost Center
  1. Import every time from:
  • "Organization Name" 
  • "Location Name"
  1. Keep existing value

Organization Name = organization.name

Location Name = location.name

 Paris
Office Location
  1. Import every time from:
  • "Organization Name" 
  • "Location Name"
  1. Keep existing value

Organization Name = organization.name

Location Name = location.name

 France
VoiceMail Number
  • Import every time from source
  • Keep existing value

*55 + ESN (location.routingPrefix + webexCalling.extension)

 *55 + 33 + 6623
VoiceMail Address
  • Import every time from source
  • Keep existing value - None
 Webex Mail john.smith@company.com
Home Phone
  • Import every time from source
  • Keep existing value
 workPhone +44984664564
Mobile Business Number
  • Import every time from source
  • Keep existing value
 mobilePhone +44702465646
Fax Number
  • Import every time from source
  • Keep existing value
 faxNumber +44984664564
Fax Group Username
  1. Import every time from:
  • "Fax Number"
  • "Organization Name" 
  • "Location Name"
  1. Keep existing value

Fax Number = faxNumber

Organization Name = organization.name

Location Name = location.name

 France
Fax Company Name
  • Import every time from source
  • Keep existing value
 organization.name ACME Inc.
Fax to email address
  • Import every time from source
  • Keep existing value
 Webex Mail john.smith@company.com
Rich Presence SIP URI
  • Use the email address field
  • Keep existing value
 Webex Mail john.smith@company.com
Microsoft URI
  • Use the email address field
  • Keep existing value
 Webex Mail john.smith@company.com
Webex URI
  • Use the email address field
  • Keep existing value
 Webex Mail john.smith@company.com
Picture
  • Import every time from source
  • Keep existing value
 AvatarURL** Max 200KBytes size (default)

* Imagicle supports overlapping extension numbers by selecting to import ESN instead of Extension Number. ESN includes a location prefix + Webex Calling Extension, so Imagicle Advanced Queuing can transfer calls to overlapping operators' internal numbers, without having to leverage +E.164 Phone Numbers.

** AvatarURL points to a server on Webex Cloud, which should be reachable by Imagicle UC Suite to retrieve each picture through a http request. User images can be in the most common formats, e.g. png, jpg, jpeg and bmp.

Note: If Webex user's email is changed, at the next synchronization relevant UCX Suite user is removed and another UCX Suite user is created with the new Active directory username and Domain values.

Article ID: 902
Last updated: 29 Nov, 2023
Revision: 23
Views: 697
Print Export to PDF Subscribe Share
This article was:  
Prev   Next
Sync Users with CuCM     Contact Pictures Display on Jabber clients