Directory Sync Overview

Directory sync ensures that Webex for Cisco BroadWorks users can use the Webex directory to call any calling entity from the BroadWorks server. When this feature is enabled, the full calling directory from the BroadWorks server gets synced to the Webex directory. Users can access the directory from the Webex App and place a call to any calling entity from the BroadWorks server.

Directory sync includes the syncing of both user calling information as well as phone lists. Synced phone list records get written to one of two contact types within the Webex directory:

  • Organization Contacts—These contacts are stored against an organization and are available to every user in the organization.

  • User Contacts—These contacts are stored against a user and are available only to the user who owns the contact.


Webex for Cisco BroadWorks provisioning includes a default sync of messaging users and their associated calling information from the BroadWorks server to the Webex directory. However, the default provisioning sync omits non-messaging users and non-user entities (for example, a conference room phone, fax machine or hunt group number). Turning on Directory sync ensures that all calling entities get added to the Webex directory.

Directory Sync Conditions

  • Partner administrators must turn the feature on 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 complete 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 that sync was scheduled or triggered manually with Sync Now.

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

  • The sync ignores users who do not 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 is more detailed than the Control Hub display and can help in troubleshooting, analytics and auditing.

  • User contacts are stored in an encrypted format with only the user who owns the contact having access to the decryption key.

  • This feature syncs the following phone list types from the BroadWorks server:

    • Enterprise Common Phone Lists

    • Group Common Phone Lists (Service Provider Groups or Enterprise Groups)

    • Personal Phone Lists

Directory Sync and Contact Maximums

Following are the maximum number of contacts for each Webex contact type:

  • 500 Organization contacts

  • 2000 User contacts (1500 synced contacts + 500 manual contacts)

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

  • If an organization exceeds the maximum allowed contacts for the sync (500 organization contacts or 1500 synced user contacts), directory sync excludes entries above the maximum threshold . There is no particular order applied to synced or omitted contacts.

  • We recommend that if one of your customer organizations exceeds the maximum allowed number of contacts in either category, 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 are not included in the sync.

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

Table 1. Directory Sync Maximums and Source

Webex Contact Type

Contact Source

Maximum

Synced from BroadWorks...

API used for sync

Organization contacts

Directory sync

500 contacts

Enterprise Common Phone Lists

/directories/enterprisecommon

Group Common Phone Lists (for a Service Provider group)**

/directories/groupcommon

User contacts

Directory sync

1500 contacts

Group Common Phone Lists (for an Enterprise group)**

/directories/groupcommon

Personal Phone Lists

/directories/personal

Manual

500 contacts

N/A

N/A


**Group Common Phone Lists are synced differently depending on whether BroadWorks is in Enterprise Mode or Service Provider mode. The value of the isBroadWorksEnterprise parameter (true or false) determines how the list syncs:

  • True—Sync as Organization contact

  • False—Sync as User contact

Updates

After a contact is updated on BroadWorks, the following outlines when the update displays in a user's Webex App:

  • Organization contact updates display in the Webex App after the user restarts the App, or after the App's local 72-hour cache timer expires.

  • User contact updates display in the Webex App for that user immediately.

Following is how the Webex directory handles updates:

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

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

Directory Sync Prerequisites

Toggle Requirements

The following feature toggles exist for this feature. Make sure to contact your Webex for Cisco BroadWorks representative to set these.

Feature Toggle

Applied to...

Descripton

webex-for-broadworks-phone-list-sync

Partner

Mandatory toggle. Enables phone list sync for all customer organizations under this partner.

Must be Enabled.

webex-for-broadworks-phone-list-sync-disable

Customer organization

Optional toggle. Disables phone list sync for a given organization, even if the feature is enabled at the partner level, and in the customer template.

Apply this toggle only if you want to disable phone list sync for a specific customer organization. Otherwise, you can leave it disabled.


 
For example, you should apply this toggle to any organizations that exceed the sync maximums.

hidden-personal-contacts-enabled-ga

User

Optional toggle. Hides personal contacts from directory searches completed by this user.

hidden-org-contacts-enabled-ga

User

Optional toggle. Hides organization contacts from directory searches completed by this user.

Preconfiguration Requirements

We recommend that you use the following settings:


The below examples assume that you are using an XSP server. For ADP servers, replace (XSP_CLI) with (ADP_CLI).
  • 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 the full list of patch requirements that form the minimum requirement for Webex for Cisco BroadWorks, see BroadWorks Software Requirements in the Solution Guide for Webex for Cisco BroadWorks.

Enable Directory Sync (New Template)

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.

Enable Directory Sync (Existing Template)

Partner administrators can complete the following steps to turn on Directory Sync within an existing Customer Template in order to enable the feature for the customer organizations that use the template.

1

Sign in to Partner Hub and choose Settings.

2

Scroll to BroadWorks Calling and click View Templates.

3

Select the appropriate customer template and scroll to BroadWorks Directory Sync.

4

To enable directory sync by default for new customer organziations that use this template:

  1. Set the Enable BroadWorks Directory & Phone List Sync for all new customer organizations toggle to On.

  2. Click Save.

5

To enable directory sync for existing customer organizations that use this template:

  1. Click Show list of customers sync status.

  2. Check the adjacent check boxes for each organization for which you want to turn the feature on.

  3. Click Enable Sync.


 

If you want to disable directory sync, follow the above procedure and:

  • In step 4a, set the Enable phone directory sync for all new customer organizations toggle to Off to disable directory sync by default for new customer organizations that use this template.

  • In step 5c, click Disable Sync to turn the feature off for existing organizations.

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.

Complete Immediate Sync

The Sync Now option lets partner administrator complete an on-demand sync for a given customer organization. This option can be selected for individual customer organizations only—there is no bulk option for Sync Now.

1

Sign in to Partner Hub (http://admin.webex.com) and choose Settings.

2

Scroll to BroadWorks Calling and click View Templates.

3

Select the appropriate customer template and scroll to BroadWorks Directory Sync.

4

Click Show list of customers sync status.

5

For the customer organization that you want to sync, click the three dots on the far right and select Sync Now.

6

Click Refresh to see the sync results.

Export Sync Records to CSV

Partner administrators can export detailed information on the last sync to a CSV file. The CSV contains a more detailed view of the sync record than the Control Hub GUI and can help in troubleshooting and analytics.

1

Sign in to Partner Hub (http://admin.webex.com) and choose Settings.

2

Scroll to BroadWorks Calling and click View Templates.

3

Select the appropriate customer template and scroll to BroadWorks Directory Sync.

4

Click Show list of customers sync status.

5

Check the adjacent check boxes for each organization that you want to include in the export.

6

Click Export results.

Public APIs for Directory Sync

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. There are four APIs:

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

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.

Sync Multiple Enterprises with API

Complete this procedure to use the public APIs to complete directory sync for multiple enterprises.

  • Directory sync lets you sync only a single enterprise at a time. If you attempt to sync more than one enterprise, you will receive a 429 error.

  • The time that it takes to complete a sync for a single enterprise varies depending on the size of the enterprise.

1

Run the List BroadWorks Enterprises API to generate a list of enterprises that you want to sync.

  1. Set startWith to the starting string of the enterprise or service provider identifier.

  2. Click Run.

2

Run the Trigger Directory Sync for an Enterprise API on the first enterprise in the list.

  1. Enter the enterprise id.

  2. Set syncStatus to SYNC_NOW

  3. Click Run.

    An immediate sync gets triggered for the enterprise. This sync counts against the one sync per instance limit.
3

Wait for a few seconds and then run the Get Directory Sync Status API to get sync status.

  1. Enter the enterprise id

  2. Click Run.

4

After the sync finishes, complete steps 2 to 4 on the next enterprise in the list. Repeat these steps until you have synced the entire list.

Error Codes for Directory Sync

The following error codes apply to Directory Sync.

Error Code

Error Message

600000

Broadworks External Directory User Sync unexpected error.

600001

Broadworks External Directory User Sync failed.

600002

Broadworks External Directory User Sync had to be terminated before completion.

600003

Broadworks External Directory User Sync only partially succeeded. Some Customer Organizations failed to sync.

600004

Broadworks External Directory User Sync is not enabled for the ConfigSet.

600005

Broadworks External Directory User Sync is in-progress for the ConfigSet.

600006

Broadworks External Directory User Sync threads are busy or shutting down, hence will not accept more sync request, try again later.

600007

The Identity Org of the CustomerConfig is not found.

600008

The CustomerConfig is not found in the partner org.

600009

Broadworks External Directory User Sync cannot be run as the broadworks cluster associated to the CustomerConfig is busy

600010

Broadworks External Directory User Sync cannot be run as there is no broadworks cluster associated to the CustomerConfig.

600011

Broadworks External Directory User Sync is not enabled for the CustomerConfig.

600012

Broadworks External Directory User Sync cannot be run as the Hybrid Directory sync is already enabled for the CustomerConfig.

600013

Broadworks External Directory User Sync failed to add users and machine accounts to identity store.

600014

Broadworks External Directory User Sync failed while trying to connect to Broadworks cluster. Error from Broadworks - %s.

600015

Broadworks External Directory User Sync didn't find any matching user in identity store.

600017

BroadWorks Phone List Sync failed to sync all user and enterprise/organization contacts.

600018

BroadWorks Phone List Sync failed for users in the enterprise/organization.

600019

BroadWorks Phone List Sync failed to sync enterprise/organization contacts.

Change History

The following table summarizes updates to this article.

Date

Revision

December 17, 2021

  • Minor edit to structure as TOC was not appearing.

December 16, 2021

  • Updated article with increased maximum values for User contacts.

December 08, 2021

  • Added section Directory Sync and Contact Maximums to provide more clarity on how the maximum number of Organization contacts and User contacts is derived.

  • Revised table formatting in Error Codes for Directory Sync for better readability.