Managing Webex for BroadWorks

Provision Customer Organizations

In the current model, we automatically provision the customer organization when you onboard the first user through any of the methods described in this document. Provisioning happens only once for each customer.

Managing Users

To manage users in Webex for BroadWorks, remember that the user exists both in BroadWorks and in Webex. Calling attributes and the user's BroadWorks identity are held in BroadWorks. A distinct email identity for the user, and its licensing for Webex features, are held in Webex.

Provision Users

You can provision users in these ways:

  • Use APIs to create Webex accounts

  • Assign Integrated IM&P (flowthrough provisioning) with trusted emails to create Webex accounts

  • Assign Integrated IM&P (flowthrough provisioning) without trusted emails. Users provide and validate email addresses to create Webex accounts

  • Allow users to self-activate (you send them a link, they create Webex accounts)

Public Provisioning APIs

Cisco Webex exposes public APIs to allow Service Providers to integrate Webex for BroadWorks subscriber provisioning into their existing provisioning workflows. The specification for these APIs is available on developer.webex.com. If you wish to develop with these APIs, contact your Cisco representative to get Webex for BroadWorks.

Flowthrough Provisioning

On BroadWorks, you can provision users with the Enable Integrated IM&P option. This action causes the BroadWorks provisioning adapter to make an API call to provision the user on Cisco Webex. Our provisioning API is backwards-compatible with the UC-One SaaS API. BroadWorks AS requires no code change, only a configuration change to the API endpoint for the provisioning adapter.


Subscriber provisioning on Cisco Webex can take considerable (several minutes for the initial user within an enterprise). Webex performs the provisioning as a background task. So, success on flowthrough provisioning indicates that the provisioning has started. It doesn't indicate completion.

To confirm that users and the customer organization are fully provisioned on Cisco Webex, you must sign in to Partner Hub and look in your Customers list.

User Self-Activation

To provision BroadWorks users in Webex, without assigning the Integrated IM&P service:

  1. Sign in to Partner Hub, and find the BroadWorks Settings page.

  2. Click View Templates.

  3. Select the provisioning template you want to apply to this user.

    Remember that each template is associated with a cluster and your partner organization. If the user is not in the BroadWorks system associated with this template, the user cannot self-activate with the link.

  4. Copy the provisioning link and send it to the user.

    You may also want to include the software download link, and remind the user they need to supply and validate their email address to activate their Webex account.

  5. You can monitor the user's activation status on the selected template.

For more information, see User Provisioning and Activation Flows.

Change User ID or Email Address

User ID and Email Address Changes

Email ID and Alternate ID are the BroadWorks user attributes used with Webex for BroadWorks. The BroadWorks User ID is still the primary identifier of the user in BroadWorks. The following table describes the purposes of these different attributes, and what to do if you need to change them:

Attribute in BroadWorks Corresponding Attribute in Webex Purpose Notes
BroadWorks User ID None Primary identifier You cannot change this identifier and still link the user to the same account in Webex. You can delete the user and recreate if it’s wrong.
Email ID User ID

Mandatory for flow-through provisioning (creating Webex User ID) when you assert that you trust email

Not required in BroadWorks if you do not assert that you can trust emails

Not required in BroadWorks if you allow subscribers to self-activate

There is a manual process to change this in both places if the user is provisioned with the wrong email address:

  1. Change user’s email address in Control Hub

  2. Change Email ID attribute in BroadWorks

Do not change the BroadWorks user id. This is not supported.

Alternate ID None Enables authn of user, by email and password, against BroadWorks User ID Should be the same as the Email ID. If You cannot put the email in the Alternate ID attribute, users will have to enter their BroadWorks User ID when authenticating.

Change User Package in Partner Hub

1

Sign in to Partner Hub and click Customers.

2

Find and select the customer organization where the user is homed.

The organization overview page opens in a panel on the right of the screen.

3

Click View Customer.

The customer organization opens in Control Hub, showing the Overview page.
4

Click Users, then find and click the affected user.

The user details panel opens on the right of the screen.

5

In the user's Services, click Webex for BroadWorks Packages (Subscriptions).

The user's packages panel opens, and you can see which package is currently assigned to the user.

6

Select the package you want for this user (Basic, Standard, Premium or Softphone).

Control Hub shows a message that the user is updating.

7

You can close the user details and the Control Hub tab.


Standard and Premium packages have distinct meeting sites that are associated with each package. When a subscriber with administrtor privileges with one of these two packages moves to the other package, the subscriber shows up with two meeting sites in Control Hub. The subscriber’s host meeting capabilities and meeting site align to their current package. The previous package's meeting site and any previously created content on that site, such as recordings, remain accessible to the meeting site admin.

Reconfigure the System

You can reconfigure the system as follows:

  • Add a BroadWorks Cluster in Partner Hub—

  • Edit or Delete a BroadWorks Cluster in Partner Hub

  • Add a Customer Template in Partner Hub—

  • Edit or Delete a Customer Template in Partner Hub

Edit or Delete a BroadWorks Cluster in Partner Hub

You can edit or remove a BroadWorks cluster in Partner Hub.

1

Sign in to Partner Hub with your partner admin credentials at https://admin.webex.com.

2

Go to Settings and find the BroadWorks Calling section.

3

Click View Clusters.

4

Click the cluster that you want to edit or delete.

The cluster details display in a flyout pane on the right.
5

You have these options:

  • Change any details you need to change, and then click Save.
  • Click Delete to remove the cluster, then confirm.

     

    If a template is associated with the cluster, you can’t delete a cluster. Delete the associated templates before you delete the cluster. See Edit or Delete a Customer Template in Partner Hub.

The cluster list updates with your changes.

Edit or Delete a Customer Template in Partner Hub

You can edit or delete customer templates in Partner Hub.

1

Sign in to Partner Hub with your partner admin credentials at https://admin.webex.com.

2

Go to Settings and find the BroadWorks Calling section.

3

Click View Templates.

4

Click the template that you want to edit or delete.

5

You have these options:

  • Edit any details that you need to change, and then click Save.
  • Click Delete to remove the template, then confirm.

Setting

Values

Notes

Provisioning account name / password

User-supplied strings

You do not need to re-enter the provisioning account details when editing a template. The empty password/password confirm fields are there to change the credentials if you need to, but leave them empty to keep the values you originally supplied.

Prefill user email address in login page

On/Off

It can take up to 7 hours for a change in this setting to take effect. That is, after you enable it, users may still need to enter their email addresses at the login screen.

The cluster list updates with your changes.

Increasing Capacity

XSP Farms

We recommend you use the capacity planner to determine how many additional XSP resources you need for the proposed increase in subscriber numbers. For either of the dedicated NPS or dedicated Webex for BroadWorks farms, you have the following scalability options:

  • Scale dedicated farm: Add one or more XSP servers to the farm that needs extra capacity. Install and activate the same set of applications and configurations as the farm’s existing nodes.

  • Add dedicated farm: Add a new, dedicated XSP farm. You’ll need to create a new cluster and new templates in Partner Hub, so you can start adding new customers on the new farm, to relieve pressure on existing farm.

  • Add specialized farm: If you are experiencing bottlenecks for a particular service, you may want to create a separate XSP farm for that purpose, taking into consideration the co-residency requirements listed in this document. You may need to reconfigure your Control Hub clusters and DNS entries if you change the URL of the service that has a new farm.

In all cases, the monitoring and resourcing of your BroadWorks environment is your responsibility. Should you wish to engage Cisco assistance, you can contact your account representative, who can arrange professional services.

Managing HTTP Server Certificates

You must manage these certificates for mTLS authenticated web applications on your XSPs:

  • Our chain of trust certificate from Cisco Webex cloud

  • Your XSP’s HTTP server interfaces’ certificates

Chain of Trust

You download the chain of trust certificate from Control Hub and install it on your XSPs during your initial configuration. We expect to update the certificate before it expires, and notify you of how and when to change it.

Your HTTP Server Interfaces

The XSP must present a publicly signed server certificate to Webex, as described in Order Certificates. A self-signed certificate is generated for the interface when you first secure the interface. This certificate is valid for one year from that date. You must replace the self-signed certificate with a publicly signed certificate. It’s your responsibility to request a new certificate before it expires.

Troubleshooting Webex for BroadWorks

Subscribe to the Webex Status Page

First check https://status.webex.com when you experience an unexpected interruption of service. If you haven't changed your configuration in Control Hub or BroadWorks before the interruption, check the status page. Read more about subscribing for status and incident notifications at Webex Help Center.

Use Control Hub Analytics

Webex tracks usage and quality data for your organization and your customer’s organizations. Read more about the Control Hub Analytics on Webex Help Center.

Network Issues

Customers or users are not being created in Control Hub with flowthrough provisioning:

  • Can the application server reach the provisioning URL?

  • Are the provisioning account and password correct, does that account exist in BroadWorks?

Clusters are consistently failing connectivity tests:


The mTLS connection to authentication service is expected to fail when you create the first cluster in Partner Hub, because you need to create the cluster to get access to the Webex certificate chain. Without that, you cannot create a trust anchor on the authentication service XSPs, so the test mTLS connection from Partner Hub is not successful.

  • Are the XSP interfaces publicly accessible?

  • Are you using the correct ports? You can enter a port in the interface definition on the cluster.

Interfaces Failing Validation

Xsi-Actions and Xsi-Events Interfaces:

  • Check that the interface URLs are correctly entered on the cluster in Partner Hub, including the /v2.0/ at the end of the URLs.
  • Check the firewall allows communication between Webex and these interfaces.

  • Review the interface configuration advice in this document.

Authentication Service Interface:

  • Check that the interface URLs are correctly entered on the cluster in Partner Hub, including the /v2.0/ at the end of the URLs.
  • Check the firewall allows communication between Webex and these interfaces.

  • Review the interface configuration advice in this document, with particular attention to:

    1. Make sure you shared RSA keys across all XSPs.
    2. Make sure you provided AuthService URL to the web container on all XSPs.
    3. If you edited the TLS cipher configuration, check that you used the correct naming convention. The XSP requires that you enter the IANA name format for the TLS ciphers. An earlier version of this document incorrectly listed the required cipher suites in the OpenSSL naming convention.
    4. If you are using mTLS with Authentication Service, are the Webex client certificates loaded on your XSP/ADP trust store? Is the app (or the interface) configured to require client certificates?

    5. If you are using CI token validation with Authentication Service, is the app (or interface) configured to not require client certificates?

Client Issues

Verify the Client is Connected to BroadWorks

  1. Sign in to the Webex app.

  2. Check that the Calling Options icon (a handset with a gear above it) is present on the sidebar.

    If the icon is not present, the user may not yet be enabled for the calling service in Control Hub.

  3. Open the Settings/Preferences menu and go to the Phone Services section. You should see the status SSO Session You're signed in.

    If a different phone service, such as Webex Calling, is shown, the user is not using Webex for BroadWorks.

This verification means:

  • The client has successfully transveresed the required Webex microservices.

  • The user has successfully authenticated.

  • The client has been issued a long-lived JSON web token by your BroadWorks system.

  • The client has retrieved its device profile and has registered to BroadWorks.

Client Logs

All Webex app clients can Send Logs to Webex. This is the best option for mobile clients. You should also record the user email address and approximate time the issue occurred if you are seeking assistance from TAC. For more information, see Where Do I Find Support for Cisco Webex?

If you need to manually collect logs from a Windows PC, they are located as follows:

Windows PC: C:\Users\{username}\AppData\Local\CiscoSpark

Mac: /Users/{username}/Library/Logs/SparkMacDesktop

User Sign-In Issues

mTLS Auth Misconfigured

If all users are affected, check the mTLS connection from Webex to your Authentication Service URL:

  • Check that either the authentication service application, or the interface it uses, are configured for mTLS.

  • Check that the Webex certificate chain is installed as a trust anchor.

  • Check that the server certificate on the interface/application is valid, and signed by a well-known CA.

Known BroadWorks Misconfigurations

chainDepth too low

  • Conditions: You followed the procedure to copy the certificate chain to the XSP, and used it to create a trust anchor for validating Cisco Webex client connections. The XSP is running R21 SP1.

  • Symptom: In R21, XSP_CLI/Interface/HttpClientAuthentication/Trusts> get does not show all of the certificates that are expected in the issuer chain.

  • Cause: In R21 there is a chainDepth parameter which, if set too low, will prevent the whole certificate issuer chain from being added to the trust anchor.

  • Fix: /XSP_CLI/Interface/Http?ClientAuthentication> set chainDepth 3


    At the time of writing, the Webex client certificate chain has 2 intermediate issuers. Do not set this parameter below 2, especially if it is already higher. In the case that chainDepth is not below 2, these symptoms could indicate a corrupt chain file.

Support

Steady State Support Policy

The Service Provider is the first point of contact for the end customer (enterprise) support. Escalate issues that the SP can't resolve to TAC. BroadWorks server version support follows the BroadSoft policy of the current version and two previous major versions (N-2). Read more at https://xchange.broadsoft.com/php/xchange/support/maintenancesupport/softwaremaintenancepolicies/lifecyclepolicy/broadworksservers.

Escalation Policy

  • You (Service Provider/ Partner) are the first point of contact for end customer (enterprise) support.

  • Issues that cannot be resolved by the SP are escalated to TAC.

BroadWorks Versions

Self-Support Resources

  • Users can find support through the Webex Help Center, where there is a Webex for BroadWorks-specific page listing common Webex app help and support topics.

  • The Webex app can be customized with this help URL and a problem report URL.

  • Webex app users can send feedback or logs directly from the client. The logs go to the Webex cloud, where they can be analyzed by Cisco Webex DevOps.

  • We also have a Help Center page dedicated to administrator-level help for Webex for BroadWorks.

Collect Information for Submitting a Service Request

When you see errors in Control Hub, they might have attached information that can help TAC to investigate your problem. For example, if you see a tracking ID for a particular error, or an error code, save the text to share with us.

Try to include at least the following information when you’re submitting a query or opening a case:

  • Customer Organization ID and Partner Organization ID (each ID is a string of 32 hex digits, separated by hyphens)

  • TrackingID (also a 32 hex digit string) if the interface or error message provides one

  • User email address (if a particular user is experiencing issues)

  • Client versions (if the issue has symptoms noticed through the client)