Troubleshooting Webex for BroadWorks

This document is intended for technical people at service provider organizations who are supporting themselves and their customers. We anticipate you to have some familiarity with troubleshooting in general, reading logs, and working with subscriber cases.

The article is divided into three major sections:

  • Resources, which is a list of tools, reading material, logs, and contacts you may need.
  • Processes, which describes some of the actions you could take while troubleshooting a customer problem.
  • Specific Issues, which categorizes and lists issues that have been known to occur, how to spot them, and how you could potentially resolve them.


Starting in October 2020, we are migrating BroadSoft customer support to Cisco CX support processes and tools. This means that Webex for BroadWorks partners need to move from using Xchange for case management to using Support Case Manager (SCM).

We expect the migration run for approximately 3 months and through the end of calendar year 2020. The BroadWorks/UCaaS TAC team will start supporting cases in CSOne / Lightning instead of BroadSoft Jira when you are migrated over. You may need to refer to cases in both systems during the migration period.

See Legacy BroadSoft Support Transition for details.

Log name Source Useful for troubleshooting
PSLog Application Server Flowthrough provisioning
tomcat access_log XSP Teams login
XsiActionsLog XSP Teams login interactions with Webex IDP Proxy, client interactions for device profiles query
authenticationService log XSP Teams login (token validation and issuing)
XSLog XSP?

Mobile subscriptions for push notifications

Call signalling

Teams startup log

Windows: \Users\{username}\AppData\Local\CiscoSpark\current_log.txt

Mac:

/Users/{username}/Library/Logs/SparkMacDesktop/current_log

Mobile: Use Send Logs

Startup (sequence)

Entitlement checks for the user

BWC library initialization for connecting to BroadWorks

getUserProfile & JwT token fetch logging

BroadWorks calling Teams log

Client

Windows: \Users\{username}\AppData\Local\CiscoSpark\bwc\current_log.txt

Mac:

/Users/{username}/Library/Logs/SparkMacDesktop/bwc/current_log

Mobile: Use Send Logs

All SIP traffic for Registration and Calls

Keep Alive traffic to BWKS Backend

Mid call features that require signalling (Hold/Resume, Transfer, etc.)

Media (Webex Media Engine) log

Client

Windows:

\Users\{username}\AppData\Local\CiscoSpark\media\*.log

Mac:

/Users/{username}/Library/Logs/SparkMacDesktop/media/

Mobile: Use Send Logs

All Media logging

Codecs negotiated for a call

Mid Call features

After you have followed some of the troubleshooting guidance, you should have a reasonable idea of where the issue is rooted.

1

Collect as much information as you can from the systems related to the issue

2

Contact the appropriate team at Cisco to open a case (see Contacts section)

If you think you need to open a case or escalate an issue, collect the following information while troubleshooting with the user:

  • User identifier: CI email address or User UUID (this is the Webex identifier, but if you also get the user's BroadWorks identifier, that will help)

  • Organization identifier

  • Approximate time frame during which the issue was experienced

  • Client platform and version

  • Send or collect logs from the client

  • Record the tracking ID if shown on client

1

Sign in to https://admin.webex.com/helpdesk.

2

Search for and then click the user. This opens the user summary screen.

3

Click the user name to see the detailed user configuration.

Useful information in this view includes the user’s UUID, common identity (CI) cluster, Teams cluster, Calling Behaviour, BroadWorks account GUID.

4

Click Copy if you need to use this information in another tool, or attach it to a Cisco case.

1

Sign in to https://admin.webex.com/helpdesk.

2

Search for and then click the customer organization name.

3

Scroll down until you see Customer Portal View and click View CustomerName to see a read-only view of the Customer org – including users and configuration.

When troubleshooting desktop and mobile client issues it is important for Partners (and TAC) to be able to view the client logs.

1

Ask the user to Send Logs.

2

Ask the user to Export the Calling Environment send you the ced.dat file.

3

Get the client logs from Partner Hub or Help Desk (see below).

Partner Hub option:

  1. Sign in to Partner Hub and find the user’s Customer Organization.

  2. Select Troubleshooting.

  3. Select Logs.

  4. Search for the user (by email).

  5. View and download the client logs as a zip file.

Help Desk option:

  1. Sign in to Help Desk.

  2. Search for the organization.

  3. Click the organization (opens up the summary screen).

  4. Scroll down to click View customer.

  5. Select Troubleshooting.

  6. Select Logs.

  7. Search for the user (by email).

  8. View and download the client logs as a zip file.

1

Sign in to the Webex client.

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 traversed 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.
  • See the Resources section to find specific client logs on Teams desktop clients, or ask users to send logs.

  • Ask users of mobile clients to send logs, then you can get them via partner hub or help desk.


Send logs is silent. However, if a user sends feedback, it goes to the Cisco Webex Teams devops team. Be sure to record the user’s feedback number if you want to follow up with Cisco. For example:

Webex client logs are heavily redacted to remove personally identifiable information. You should export the Calling Environment Data from the client in the same session as you notice the issue.

1

In the client, click the profile picture, then click Help > Export Calling Environment Data.

2

Save the resulting file ced.dat for troubleshooting calling issues for this user.

Important: Logout from or restart the client clears the internal cache. If you export ced.dat after that, the exported data will not correspond with any logs that were sent before the cache.

1

On the client click Help > Health Checker.

2

Select Reset Database.

This triggers a full reset of the client and loads the Teams login screen.

Teams checks the following information to determine whether to register to BroadWorks:

  • User entitlement to broadworks-connector

  • Calling behavior for organization and user

Check a user’s calling behavior and connector entitlement

  1. Sign in to Help Desk (https://admin.webex.com/helpdesk) with your partner administrator credentials.

  2. Search for the user.

  3. Click on the user and check the Calling Behavior entry. It should be "Calling in Webex Teams".

  4. Click the user name to open the User Details screen.

  5. Scroll down to locate the entitlements section, and verify that broadworks-connector is included.


    A Webex for BroadWorks user should NOT have the bc-sp-standard entitlement if they are intending to use Webex for BroadWorks. This is the entitlement for “Webex Calling (Broadcloud)” which is Teams calling through a Cisco-managed cloud calling service.

Check the organization’s calling behavior

  1. Sign in to Help Desk (https://admin.webex.com/helpdesk) with your partner administrator credentials.

  2. Search for the organization.

  3. Click on the organization and check the Calling Behavior entry. It should be “Calling in Webex Teams”.

Use the Application Server’s PSLog to see the HTTP POST request to the provisioning bridge and the response from Webex.

In a correct working case, the response is 200 OK and after a few minutes you can see the user - and new Customer org if it is first user – has been created in Webex.

You can verify this by searching Help Desk for the email address you see in the POST.

Before you begin

Collect a PSLog from the Application Server during a flowthrough provisioning attempt with a test user.

1

The first thing to check is the HTTP response code:

  • Anything other than 200 OK is a user provisioning failure.

  • 200 OK could still indicate a failure if something about the subscriber profile does not work in the Webex services upstream of the provisioning bridge.

  • 400 may contain a message node in the response. The provisioning bridge could not process something in the subscriberProfile. There may be something wrong with the subscriber details, or incompatibility with a setting in the template.

  • 401 means the provisioning credentials entered on the AS do not match those entered on the template in Partner Hub.

  • 403 could indicate something misconfigured on Application Server. Check the target of the request. it should not be an IP address, it should be the provisioning bridge URL you can see on your template in Partner Hub.

  • 409 indicates a conflict between the supplied subscriberProfile and existing Webex data. There may be an existing user with that email address. Check the message in the response.

2

You can also check the original HTTP POST for any suspect values that could cause provisioning to fail.

The POST contains a subscriberProfile XML structure. Inside this, useful nodes to check are:

  • bwuserid: Use this to find the subscriber profile if you need to edit it in BroadWorks.

  • group: If the template is in "Service Provider mode", this is lowercased and becomes the name of the Customer org you see in Partner Hub.

  • serviceProvider: If the template is in "Enterprise mode", this is lowercased and becomes the name of the Customer org you see in Partner Hub.

  • primaryPhoneNumber: Must exist. Provisioning fails without it.

  • email: Becomes the user ID in Webex. Must be valid and unique to Webex, otherwise provisioning fails.


 

Ignore the services stanza: it is created by AS, and accepted but not used by Webex.

This flow describes BroadWorks Authentication mode. You can see the authentication mode on the BroadWorks Template, in Partner Hub. See Configure your Customer Templates in https://help.webex.com/en-us/z9gt5j/Webex-for-BroadWorks-Solution-Guide#id_137726.

The following ladder diagram shows the interaction between the user, client, Webex services, and BroadWorks system, when the user is doing BroadWorks authentication in Teams. Also, the connection between Webex and the XSP is secured by MTLS.

The discussion that follows explains what you can expect to see when investigating the logs for a successful login.

Figure 1. BroadWorks Authentication and Device Configuration

User interacts with client, client interacts with Webex services:

  • The user supplies their email address to Teams client (1 in diagram).

  • CI knows to redirect this user to enter their BroadWorks password (via UAP) (2 in diagram).

  • The IDP Proxy submits a get profile request to the Xsi interface on the XSP.

In the tomcat access_log:

  • Look for the GET request for the subscriber profile, from Webex towards the Xsi-Actions interface (2.1 in diagram). It has the Teams user ID. E.g.

    GET /com.broadsoft.xsi-actions/v2.0/user/webexuserid@example.com/profile

In the XsiActionsLog:

  • Look for the profile GET request from Webex (2.1 in diagram). It has the Teams user ID. E.g.

    GET /com.broadsoft.xsi-actions/v2.0/user/webexuserid@example.com/profile

    The headers include authorization: Basic and user-agent: broadworksTeamsClient

  • The XSP then does OCI-P Basic authentication against BroadWorks (AuthenticationVerifyRequest and AuthenticationVerifyResponse, like any other application doing basic authentication via Xsi) and also a UserGetRequest and ServiceProviderGetRequest to gather the subscriber information.

  • The Xsi response to Webex contains an XML Profile block containing the (BroadWorks) userId and other details (2.2 in diagram).

Client and Webex services interactions:

  • IDP proxy matches user profile received from BroadWorks and issues SAML assertion to client (2.3 in diagram)

  • Client exchanges SAML assertion for a CI token (3 in diagram)

  • The client checks that the signed in user has the broadworks-connector entitlement (4 in diagram). You can check user entitlements in Help Desk)

  • Client uses CI token to request a JSON Web Token (JWT) from IDP proxy (5 in diagram)

  • IDP proxy validates CI token at CI

  • IDP proxy requests JWT from authentication service

In the authenticationService log:

  • Look for the token request from Webex (5.2 in the diagram), e.g.:

    GET /authService/token

    which has http_bw_userid header and others.

  • The XSP does OCI-P UserGetLoginInfoRequest, to validate that the supplied user id corresponds to a BroadWorks user (5.3 in diagram). AuthService has established trust with Webex by virtue of the mTLS connection, so can issue LLT.

  • Look for the response (5.4 in diagram) from LongLivedTokenManager - Token generated, subject: bwksUserId@example.com, issuer: BroadWorks …

    and StatusCode=200 which you can associate with the original request using the trackingid: CLIENT… header.

In the XsiActionsLog:

  • The client is now able to present the long-lived token at Xsi-Actions interface to get its device profile (6 in diagram). E.g.:

    GET /com.broadsoft.xsi-actions/v2.0/user/bwksUserId%40example.com/profile/device

    With the headers authorization: Bearer token and user-agent: WebexTeams (variant/version)

  • The Xsi-Actions interface POSTs the token to the authservice (configured to be on the loopback interface) e.g.: 127.0.0.1:80 POST http://127.0.0.1:80/authService/token

    which you can correlate with the trackingid: CLIENT… header in the GET and the X-BROADSOFT-CORRELATION-ID : CLIENT… header in the POST.

In the authenticationService log:

  • The receipt of the POST from Xsi (loopback)

  • A StatusCode=200 back to Xsi

  • And a token validation response, having a "token" JSON block in the body.

  • Correlated using the trackingid: CLIENT…

In the XsiActionsLog:

  • Having received 200 OK from authservice, which validated the client’s token, the Xsi-Actions application now sends OCI-P request for UserPrimaryAndSCADeviceGetListRequest

  • Receives OCI-P UserPrimaryAndSCADeviceGetListResponse containing the accessDeviceTable XML structure.

  • The OCI-P response is encoded as Xsi response to client, including AccessDevices XML structure, which has the deviceTypes e.g. Business Communicator – PC and the urls where the client can retrieve the device configuration files.

Client continues as normal:

  • Selects a device entry and interacts with DMS to get device profile (6 in diagram)

  • Registers to BroadWorks via SBC retrieved in configuration from DMS (7 in diagram)

Administrator Cannot see Customer Organizations

As an administrator for your Partner organization in Webex, you should have the Full Administrator role. That role is used for managing your partner organization, including assigning administrative privileges to yourself and others. To manage customer organizations, you need to grant yourself (or other people) the Sales Full Administrator role or Sales Administrator role. See https://help.webex.com/fs78p5.

Integrated IM&P Errors for Specific Enterprises / Customers

If you have a mix of enterprises using different cloud collaboration services, e.g. UC-One SaaS and Webex for BroadWorks, you may have opted to modify the provisioning adapter on a per-enterprise basis.

To check what is configured for Integrated IM&P (default for enterprises, unless a more specific setting exists), run AS_CLI/Interface/Messaging> get. For a specific enterprise's provisioning parameters, open the enterprise and go to Services > Integrated IM&P.

Check that the Integrated IM&P configuration for that enterprise matches exactly what is shown in the Customer Template in Partner Hub. The following settings must match, or provisioning fails for all users in the enterprise:

BroadWorks Enterprise Integrated IM&P setting

Partner Hub Customer Template setting

Messaging Server URL

Provisioning URL

Messaging Server Username

Provisioning Account Name

Messaging Server Password

Provisioning Account Password, Confirm Password

Integrated IM&P Errors for Specific Users

This applies if you are using flowthrough provisioning, and assumes that provisioning is working for some/most users (so you can rule out a configuration issue).

If you are seeing Integrated IM&P errors in BroadWorks, for example, “[Error 18215] Provisioning error with Messaging server” and “[Error 18211] Communication error with Messaging server”, you should investigate the following potential causes:

  • The user’s email address could already exist CI. Search for the user in Help Desk to check if their email address is already there. This is not necessarily conclusive, because the user may exist in an organization whose data you are not permitted to see in Help Desk.

  • The user independently signed up to Teams, prior to being assigned the Integrated IM&P service. In this case, one option is to have the user delete their free account so that they can become a part of the Customer Organization you are provisioning. Instructions are at https://help.webex.com/5m4i4y.

  • The user does not have a primary phone number assigned to their profile (all Webex for BroadWorks subscribers must have a primary DID). See the topic on analyzing PSLog from AS.

User Provisioning Failures in Response from Provisioning Bridge

If users are not appearing in Control Hub, within a few minutes of assigning Integrated IM&P, have a look at the response codes from the provisioning bridge service. Run a PSLog to look at the HTTP response codes.

200 OK

A 200 OK response does not mean that the user is successfully provisioned. It means that the provisioning service received the request and successfully submitted the corresponding user creation request to upstream services.

The provisioning transaction is asynchronous by design. The service responds 200 OK because the user creation process can take several minutes and, for performance reasons, we do not want to receive multiple requests to create the same user.

However, if the user does not eventually appear in the Customer Organization after a 200 OK response, it could indicate that the user creation failed in the Webex services upstream of the provisioning service.

You need to escalate a provisioning failure that has a 200 OK response.

400 Bad Request

Check the HTTP response which should have more detail on potential issues that could cause this response from the provisioning service. Some examples of the <message> node:

  • “Can not trust BroadWorks email with legacy provisioning API.”

    The email address associated with the failing user provisioning request is not valid, or is mistyped, but you have asserted in the template that the email addresses can be trusted. Check the users’ profiles in BroadWorks, specifically the email id.

  • “Customer org is not found in database and also new org creation flag is not enabled.”

    This failed provisioning request should be creating a new Customer Organization in Webex, but your template is configured to prevent new Customer Organizations to be created. If you want to allow new organizations, for email domains that do not match existing customers in Webex, then you can reconfigure your template in Partner Hub and retest the provisioning request. However, if you are not expecting a new organization to be created for this user, perhaps the email address is mistyped (specifically the domain part). Check the user’s email id in BroadWorks.

403 Forbidden

The provisioning request has no chance of succeeding. You will need to investigate the request and response in this case. For example, if you see an IP address as the target of the provisioning request – instead of the appropriate provisioning bridge URL for your organization (see the firewall configuration topics in Solution Guide) – it could indicate that your Application Server is missing a required patch (ap373197).

Check that all required patches are applied to the Application Server, and that you completed the related configuration for successful flowthrough provisioning.

409 Conflict

The provisioning request cannot proceed because there is an existing user in Webex that matches the email address in the request.

User Already in CI

Get the subscriber email out of the HTTP POST request and search for it in Help Desk.

You may not see the user if you are not permitted, but you may also see that the user is in a ‘free’ organization e.g. “Consumer”.

You can ask this user to delete their free account, or you can use a different email address to provision them. See https://help.webex.com/ndta402.

User Activation Portal Does Not Load

The normal Webex for BroadWorks sign in flow includes a User Activation Portal where users enter their passwords. Sometimes this portal does not load after the user has supplied their email address in the Teams sign in screen.

This issue can be caused on client side or on the service side. On the client side, it is typically caused by the client’s native browser being incompatible in some way with the service.

Single Sign On failed

  • In BroadWorks, check that the user has been assigned the device types for Teams clients (see Device Profiles section in Prepare Your Environment section of the Solution Guide).

  • Check the user is using the correct password: If the template you used to provision the user’s Customer Organization (in Partner Hub) is configured for BroadWorks authentication, the user should be entering their BroadWorks “Web Access” password.

After a user has been provisioned in Webex and they successfully sign in to Teams, then Teams registers to BroadWorks. The following are the expected registration sequence and the resulting signs of a healthy registration (as seen from Teams):

Expected Registration Sequence

  1. Client calls XSI to get a device management token and the URL to the DMS

  2. Client requests its device profile from DMS by presenting the token from step 1

  3. Client reads the device profile and retrieves the SIP credentials, addresses, and ports

  4. Client sends a SIP REGISTER to SBC using the information from step 3

  5. SBC sends the SIP REGISTER to the AS (SBC may perform a look-up in the NS to locate an AS if SBC does not already know the SIP user.)

Expected Signs of Successful Client Registration

Calling Options icon appears in the Teams interface.

In the Teams phone services tab (e.g. Settings > Phone Services on Windows, Preferences > Phone Services on Mac), the message “SSO Session: You’re signed in” means the app registered successfully (to BroadWorks in this case).

Client has no Calling Icon

Most of the time this means the user does not have the correct license / entitlements.

Client Shows Phone Services Tab but no SSO Session

This is an unsuccessful registration. There are multiple reasons why a Teams client would fail registration with BroadWorks:

Multiple Calling Services Being Tested with Same Clients

This known issue can be caused by the client changing between different calling back ends. It is most likely to occur during trials of different calling services offered via (the same) Webex Teams clients. You can reset the client database (link) to remedy this issue.

Misconfiguration of Authentication Service

Check the XSP(s) hosting the authentication service against the Solution Guide (see Configure Services on your Webex for BroadWorks XSPs). Specifically:

  • The RSA keys (that you generate on one XSP) are copied onto all the XSPs

  • The authentication service URL has been provided to the web container on all XSPs, and entered correctly in the cluster in Partner Hub

  • External authentication by certificates is configured:

    XSP_CLI/System/CommunicationUtility/DefaultSettings/ExternalAuthentication/CertificateAuthentication>get
            
            allowUserApp = false
            allowClientApp = true
  • When using MTLS, you must upload the Webex client certificate to the XSPs (you can getthe certificate from Partner Hub, on the BroadWorks Settings page)

Misconfiguration of BroadWorks tags

Check that you have configured the required BroadWorks tags for Webex Teams (see BroadWorks Tags Required for Webex Teams section in Solution Guide) and that there are no conflicts or incorrect values.

Specifically, the %SBC_ADDRESS_WXT% tag should be the SBC towards your SIP registrar for Webex Teams clients.

Desktop Client Disconnects Phone Services After Successful SSO Connection

This issue can be caused by the same user signing in to multiple clients on the same platform type. For example, if a user signs in successfully to Teams on Windows, and then signs in to Teams on a different Windows machine, there is only an active SSO session on one of the machines. This is by design.

If you absolutely need to work around this issue, you can configure BroadWorks to have multiple instances of the same device type, but they must have unique SIP addresses. This configuration is outside the scope of Webex for BroadWorks.

Desktop Device not Provisioned for User

This signature is seen in the client (\bwc\) log:

<Error> [0x70000476b000] BroadWorksConfigDownloader.cpp:106 onAccessDeviceListSucceeded:BWC:SCF: ConfigDownload - the device profile 'Business Communicator - PC' is not found.

Self Care Button/Link Not Showing in Webex Teams

A different symptom of this issue is when the button/link is shown, but clicking it opens an external browser.

  • Verify the required client configuration template is deployed and CSW tags are properly set. (See the Call Settings Webview section in the Webex for BroadWorks Solution Guide).

  • Verify Webex Teams is registered for calling in BroadWorks.

  • Check that Webex Teams is a recent version that supports CSWV.

Blank Page or Error After Clicking Self Care Button/Link

Generally, this behavior in Webex Teams indicates a configuration or deployment issue with the CSWV application on BroadWorks XSP.

Collect details for further investigation, including CSWV logs, access logs, config-wxt.xml repository, and template file, and then raise a case.