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

Useful log files

Reading list

• Webex for Cisco BroadWorks Partner Knowledge Portal
• XSP Platform Configuration Guide (R23)
• BroadWorks Software Management Guide (R23)
• Cisco BroadWorks Device Management Configuration Guide (R23)
• Broadworks Xsp Command Line Interface Administration Guide
• Long-Lived Authentication Token Feature Description Release 23.0
• SAML Authentication integration guide, R23
• Cisco BroadWorks SSL Support Options Guide
• Cisco CI Support Feature Description
• Notification Push Server (Feature Description)
• Push Notification Support for Calls Feature Description Release 22.0
• Connect (Android) Migration to Firebase Method of Procedure
• Cisco BroadWorks Storage of Device Tokens for Push Notifications Feature Description Release 22.0
• Cisco BroadWorksSystem Capacity Planner (spreadsheet)
• Cisco BroadWorks Platform Dimensioning Guide
• Cisco Broadworks System Engineering Guide
• CI Authentication Support Requirements Document Version 1.0 MR-7136

Known issues and limitations

The Known Issues and Limitations article has up-to-date information about known issues that we've identified in the Webex for BroadWorks solution.

Serviceability Connector

The Webex Serviceability service increases the speed with which Cisco technical assistance staff can diagnose issues with the infrastructure. It automates the tasks of finding, retrieving and storing diagnostic logs, and information into an SR case. The service also triggers analysis against diagnostic signatures so that TAC can more efficiently identify and resolve issues with your on-premises equipment.

For details on how to deploy the Serviceability connector, see Deployment Guide for Cisco Webex Serviceability Connector.

Escalating an issue

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

Procedure

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.

What client information to collect

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

Check user details in Help Desk

Partner administrators who have Help Desk Administrator (Basic or Advanced) role privileges can use this procedure to check user details using Help Desk view.

Procedure

1. Sign in to Help Desk.
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, Webex app 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.

View customer organization in Help Desk

Partner administrators who have Help Desk Administrator (Basic or Advanced) role privileges can use this procedure to view customer organization details in Help Desk view.

Procedure

1. Sign in to Help Desk.
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.

Retrieve user logs from Partner Hub

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

Procedure

1. Ask the user to Send Logs. For help, see: Webex App | Report an issue.
2. Ask the user to Export the Calling Environment and send you the ced.dat file.
3. Get the client logs from Partner Hub or Help Desk .

   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.

How to find client version

Procedure

1. Share this link with the user: https://help.webex.com/njpf8r5
2. Ask the user to send you the version number.

Client check for calling service

Procedure

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 Cisco BroadWorks.)

   This verification means:

   • The client has successfully traversed the required Webex microservices.
   • The user has successfully authenticated.
   • The client is issued a long-lived JSON web token by your BroadWorks system.
   • The client has retrieved its device profile and has registered to BroadWorks.

Get client logs or feedback

• See the Resources section to find specific client logs on Webex desktop clients, or ask users to send logs. For help, see: Webex App | Report an issue.
• 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 Webex App devops team. Be sure to record the user’s feedback number if you want to follow up with Cisco. For example:

  

Get calling environment data

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.

Procedure

1. On the client click Help > Health Checker.
2. Select Reset Database. This triggers a full reset of the client and loads the Webex app login screen.

Verify that Webex should register to BroadWorks

The Webex app 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 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".

   

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 Cisco BroadWorks user should NOT have the bc-sp-standard entitlement if they are intending to use Webex for Cisco BroadWorks. This is the entitlement for “Webex Calling (Broadcloud)” which is Webex app calling through a Cisco-managed cloud calling service.

Check the organization’s calling behavior

1. Sign in to Help Desk 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”.

Analyze PSLog for user provisioning issues

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.

Procedure

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

Analyze XSP Logs to troubleshoot subscriber log in

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 showsthe interaction between the user, client, Webex services, and BroadWorks system, when the user is doing BroadWorks authentication in the Webex app. 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.

User interacts with client, client interacts with Webex services:

• The user supplies their email address to the Webex app (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 Webex user ID. For example:

  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 Webex user ID. For example:

  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), For example: 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 able to present the long-lived token at Xsi-Actions interface to get its device profile (6 in diagram). For example: 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) For example: 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’stoken, 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. For example: 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).

Partner Hub issues

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. For details, see Assign organization account roles in Control Hub.

User provisioning issues

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 Cisco 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:

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 Webex, prior to being assigned the Integrated IM&P service. In this case, one option isto have the user delete their free accountso 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 Cisco 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 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 sign in issues

User Activation Portal does not load

The normal Webex for Cisco 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 Webex app 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 the Webex app (see Device Profiles section in Prepare Your Environment section of the Solution Guide).
• Check that the user is using the correct password. If the template that 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. The user may also need to enter their BroadWorks User ID if their email address is not configured as an Alternate User ID. Make sure the user has entered upper case and lower case characters correctly.

Calling configuration and registration issues

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

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 Webex interface.

In the Webex app 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.

This is an unsuccessful registration. There are multiple reasons why a Webex app 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 app 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 Cisco 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 get the certificate from Partner Hub, on the BroadWorks Settings page).

Misconfiguration of BroadWorks tags

Check that you have configured the required BroadWorks tags for the Webex app. Refer to the Webex for Cisco BroadWorks Configuration Guide for information on configuration tags. Make sure that there are no conflicts or incorrect values. Specifically, the %SBC_ADDRESS_WXT% tag should be the SBC towards your SIP registrar for Webex app 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 the Webex app on Windows, and then signs in to the Webex app 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 Cisco BroadWorks.

Desktop device not provisioned for user

This signature is seen in the client log:

<Error> [0x70000476b000] BroadWorksConfigDownloader.cpp:106

onAccessDeviceListSucceeded:BWC:SCF: ConfigDownload - the device profile 'Business Communicator - PC' is not found.

Call settings webview issues

Self Care button/link not showing in Webex app

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 Cisco BroadWorks Solution Guide).
• Verify the Webex app is registered for calling in BroadWorks.
• Check that the Webex app is a recent version that supports CSWV.

Blank page or error after clicking Self Care button/link

Generally, this behavior in the Webex app 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.

Domain claim issues

User registration errors can occur as a result of errors that are made in claiming domains. Before you claim any domains, make sure that you understand the following:

• ServiceProviders should not claim the domains of customer organizations that they manage. They should claim only the domains of those users that are in the Service Provider's internal organization. Claiming the domain of users in a separate organization (even one that the Service Provider manages) can result in registration errors for the users in the customer organization as user authentication requests get routed through the Service Provider rather than the customer organization.
• If two customer organizations (Company A and Company B) share the same domain and Company A has claimed the domain, registration for Company B users may fail due to the fact that user authentication requests are routed through the organization that has the domain claimed (Company A).

  If you claim any domains in error and need to remove a claim, refer to the Manage Your Domains Webex article.

End user error codes

The following table outlines end user error codes that may be seen in the client user activation portal.

Error codes for Directory Sync

The following error codes apply to Directory Sync.