Directory Sync in Webex for Cisco BroadWorks

Directory sync ensures that Webex for Cisco BroadWorks users can use the Webex directory from the Webex App to call any calling entity from the BroadWorks server. This feature syncs BroadWorks calling information that was not a part of user provisioning to the Webex directory.

Webex for Cisco BroadWorks user provisioning updates the Webex directory with calling details for Webex for Cisco BroadWorks users (primary phone number, mobile phone number, extension), but omits external calling records. However, when Directory sync is on, the feature also syncs the following calling records to the Webex directory.

• BroadWorks-only calling users (who are not onboarded to Webex)

• Non-user calling entities (e.g., a conference room phone, fax machine, hunt group number)

• BroadWorks Phone List entries

The following table summarizes BroadWorks calling records and shows how they get added to the Webex directory.

Directory Sync Conditions

• Partner administrators must enable the feature at the partner level. Partner administrators can turn the feature on or off for multiple customer organizations in a single operation.

• By default, the initial sync occurs one week following the enabling of the sync (the time chosen to start the sync is random). However, customer organizations can use the Sync Now option to bypass the one week waiting period and trigger an immediate sync for a given customer organization.

• By default, directory Sync runs weekly for each customer. Each sync occurs one week following the last sync, regardless of whether the last sync was scheduled or triggered manually with Sync Now.

• The maximum number of simultaneous syncs per BroadWorks cluster is two: one scheduled sync and one on-demand sync (via API or Partner Hub GUI). However, administrators can’t run two on-demand syncs at the same time from the same BroadWorks. This restriction exists irrespective of whether the sync was initiated via the API or via the Sync Now option in Partner Hub. In addition, Webex won’t schedule two scheduled syncs to run at the same time from the same BroadWorks.

• If a sync failure occurs, Webex reattempts the sync automatically every 24 hours until the next scheduled sync.

• The sync ignores users who don’t have a phone number.

• In Partner Hub, you can view sync status information for a given customer. In addition, you can export detailed information on the last sync to a CSV record. The CSV record provides more detail than the Control Hub display and can help in troubleshooting, analytics, and auditing.

• Webex stores user contacts in an encrypted format. Only the user who owns the contact has access to the decryption key.

• For BroadWorks-only calling users and non-user calling entities, this feature syncs the following phone number types from BroadWorks:

  • Primary Phone Number

  • Mobile Phone Number

  • Extension

  However, sync excludes BroadWorks-only calling users and non-user calling entities from the sync if neither a primary phone number or extension is present.

  BroadWorks user-level privacy service setting is not supported as part of directory sync.

BroadWorks Phone List and Contact Maximums

Directory sync also syncs BroadWorks phone list entries to Webex Contacts. Synced entries get added to one of the following contact types:

• Organization Contacts—Webex stores these contacts against an organization. Each user can access the organization contacts for their organization. The maximum is up to 30000 contacts.

• User Contacts—Webex stores these contacts against a user. Only the user who owns the contact can access the contact entry. The maximum is up to 2000 contacts (1500 synced contacts + 500 manual entry contacts).

The following table maps Webex contact types against the contact source (synced from a BroadWorks phone list or added manually):

The following conditions apply around how Directory Sync handles contact maximums:

• If an organization exceeds the maximum allowed contacts for the sync (30000 organization contacts or 30000 Group common contacts per group), directory sync excludes entries above the maximum threshold. There’s no particular order applied to synced or omitted contacts.

• If one of your customers exceeds the maximum allowed number of contacts in either category, we recommend that you raise a case with Cisco to have that organization excluded from directory sync.

• Manual contacts are contacts that a user adds manually on the Webex App. A user can add up to 500 manual contacts. Manual contacts fall within the larger User contact category on Webex, but aren’t included in the sync.

• The overall combined limit for organization contacts (30000) and group contacts (30000 per group) is 200000.

Updates

Following is how the Webex directory handles updates:

• If the contact name changes on BroadWorks, the existing contact gets deleted from the Webex directory and a new contact is created.

• If the contact number changes on BroadWorks, Webex updates the existing contact in the Webex directory with the new number.

After an admin updates a contact on BroadWorks, the following conditions outline when the update displays in a user's Webex App:

• If the update is to a BroadWorks-only calling user or a non-user calling entity, the update displays in a user’s Webex App immediately following the subsequent directory sync.

• If the update is to a BroadWorks phone list entry:

  • For user contacts—Updates display in the user’s Webex App immediately following the subsequent directory sync.

  • For group contacts - Updates display in the users Webex App immediately following the subsequent directory sync.

  • For organization contacts—The Webex directory gets updated at the subsequent directory sync, but users won’t see the change in the Webex App until they restart the Webex App or until the local 72-hour cache timer expires.

We recommend that you use the following settings:

• Rate Limiting Values—Set the following OverloadControl system properties (XSP_CLI/Applications/Xsi-Actions/OverloadControl):

  • userDirectoryTransactionLimit—Set to a null value.

  • globalDirectoryTransactionLimit—Set to a null value.

  It's recommended that you set userDirectoryTransactionLimit and globalDirectoryTransactionLimit to a null value. However, if you do decide to assign values, each must be set to at least five times the value of transactionLimitPeriodSeconds (which should be 1).

• Transaction Limits—Set the following values (XSP_CLI/System/CommunicationUtility/DefaultSettings):

  • userTransactionLimit—Set to at least 100.

  • transactionLimitPeriodSecs—Set to 1.

• Paging Values—Set the Paging system properties (XSP_CLI/Applications/Xsi-Actions/Paging):

  • defaultPageSize—Set to 50

  • availableUserMaxLimit—Set to 100

• CTI Interface—Make sure to upload that Webex CA certificates to the CTI interface trust store and to enable client authentication on the CTI interface.

In addition, depending on your BroadWorks release, we recommend that you apply the following system patches to BroadWorks deployment before you enable this feature:

• For R22: AP.as.22.0.1123.ap368517

• For R23: AP.as.23.0.1075.ap368517

• For R24: no patch required

Partner administrators can enable Directory Sync for a customer template while creating the new template. Any new customer organizations that get assigned to that template will have directory sync enabled. For details, see "Configure your Customer Templates" in Configure Your Partner Organization in Partner Hub within the Solution Guide for Webex for Cisco BroadWorks.

What to do Next

Make sure that your users know that they must click the Contacts tab on the Webex App at least once in order to turn on the feature on the Webex App. This needs to be completed once only.

Public APIs are available on developer.webex.com that allow partner administrators to update Directory Sync settings for the customer organizations that they manage, to trigger an immediate sync, or obtain sync status information. The directory sync methods are grouped under BroadWorks Enterprises:

• List BroadWorks Enterprises—Use this API method to obtain a list of enterprises under a given Service Provider and each enterprise's id. You must enter the spEnterpriseId as assigned in provisioning.

• Update Directory Sync for a BroadWorks Enterprise—Enter the enterprise id to update the directory syc status for that enterprise, enabling or disabling directory sync.

• Trigger Directory Sync for an Enterprise—Use this API method if you want to trigger an immediate sync for a given enterprise id. For the syncStatus, enter the SYNC_NOW command.

• Get Directory Sync Status for an Enterprise—Enter the enterprise id and run in order to get a status and trackingId of the latest sync. You can use the trackingID to run additional analytics via tools such as Kibana and Grafana.

In addition, administrators can use the Trigger Directory Sync for a Single User API to trigger an on-demand directory sync for a single user.

For detailed API documentation, see https://developer.webex.com/docs/api/guides/webex-for-broadworks-developers-guide.

You need to sign in to read the API specification at https://developer.webex.com/docs/api/v1/broadworks-subscribers.

The following error codes apply to Directory Sync.

The following table summarizes updates to this article.