Troubleshooting

This section is designed to assist members of implementation and support teams who are either installing or supporting the ServiceNow ERS Integration. The items listed here cover potential issues one may encounter when working with the integration, along with steps to take to investigate and alleviate those issues.

Throughout this section you'll see a reference to "ServiceNow application logs". This is referring the Application Logs in ServiceNow which can be found in System Logs > System Log > Application Logs.

ServiceNow has other logs which are also helpful. Those include:

  1. Transaction Logs, found at System Logs > Transactions
  2. All Logs, found at System Logs > System Log > All
  3. Warning Logs, found at System Logs > System Log > Warnings
  4. Error Logs, found at System Logs > System Log > Errors

This troubleshooting guide assumes the audience has a base knowledge of both ServiceNow and Remote Support.

The Load Issues Button is not Working

If you get an error stating, "Something went wrong while attempting to load issues", most likely something on the Secure Remote Access Appliance record in ServiceNow is not configured properly. Check the following:

  • Ensure the Hostname field is correct.
  • Ensure the OAuth Client ID field is correct.
  • Ensure the OAuth Client Secret field is correct. You will have to generate and copy a new client secret in Remote Support /login, save the API configuration, then paste the new value in the OAuth Client Secret field in ServiceNow. It's very common that this OAuth Client Secret value is copied to the clipboard, but the API Account record is never saved in Remote Support /login. It's recommended that you copy the value and immediately save the API Account, then paste the value in the Secure Remote Access Appliance record in ServiceNow.
  • Ensure the Integration Enabled checkbox is checked.

If you get an error stating, "Unknown host", this is essentially a communication issue from ServiceNow to the Secure Remote Access Appliance, unless the hostname is set incorrectly on the Secure Remote Access Appliance configuration.

Double-check the hostname on the Secure Remote Access Appliance configuration in ServiceNow. If that looks good, then recommend the customer involve their network team to determine if there is a network block in place such as a Firewall or network rule.

Support Sessions Are Not Being Written to ServiceNow

If support sessions aren't being written in ServiceNow, there could be a communication issue. First check to ensure communication is open from Remote Support to ServiceNow.

Login to the Remote Support /login interface and ensure Support Session End is checked on the HTTP Recipient for the Outbound Event. If Support Session End is not checked, check the box, save the HTTP Recipient, then run another support session and see if the record is written to ServiceNow.

If the Outbound Event looks good, login to the Secure Remote Access Appliance /appliance interface and run a TCP test to the hostname of the customer's ServiceNow instance on port 443. If the TCP test yields a non 200 response, recommend the customer involve their network team to determine if there is a network block in place such as a Firewall or network rule.

If the TCP test yields a 200 response, then start another session from ServiceNow, end the session, then open the ServiceNow transaction logs and filter by records that are Created on Today (or Last 15 minutes for fewer results) AND URL starts with /x_bmgr_support_ent_bomgar_post.do. If you don't see a record for the session you just ran, then there is a communication issue from Remote Support to ServiceNow and you'll want to recommend the customer involve their network team to determine if there is a network block in place such as a Firewall or network rule.

If you see the transaction record in the Transaction Logs, then double-check and reset the OAuth Client ID and OAuth Client Secret fields on the Secure Remote Access Appliance record in ServiceNow. It's very common that this OAuth Client Secret value is copied to the clipboard, but the API Account record is never saved in Remote Support/login. It's recommended that you copy the value and immediately save the API Account, then paste the value in the Secure Remote Access Appliance record in ServiceNow. Run another support session. If the Support Session record still does not show up in ServiceNow, check the ServiceNow application log to see if there are any errors that may shed light on why the record isn't being written.

Data is Missing from the Support Session in ServiceNow

If data is missing from the Support Session record, it's possible the Remote Support event types have not been updated or only a subset of the event types have been set to be imported for each support session record that is written to ServiceNow.

Identify which pieces of data are missing, then check the Events To Import field under the Miscellaneous tab under the Secure Remote Access Appliance configuration in ServiceNow to see if a subset of the events are set to be imported. If you don't see any events, it's possible the Update Event Types menu item under the BeyondTrust Remote Support menu was never clicked, as outlined in theUpdate BeyondTrust Session Event Types section of this guide.

Session Key Button is not Showing on the Incident Form

If the Session Key button is not showing on the Incident form, there are few things that can be checked.

Check to see if there were any adjustments or customizations made to any of the integration's UI Actions. Because these UI Actions render the buttons, it is not recommended that these be edited.

If no customizations to the UI Actions were done, ensure the Secure Remote Access Appliance configuration is named "Default", with matching case and no whitespace. Any name other than Default will cause the Session Key button to be hidden.

If the name of the appliance is Default, take a look at the customer's Incident States (see Configure Incident States ). and ensure that the Condition field in the UI Action is showing the button for the proper incident states. Note that there are four Session Key UI Actions, two for Task records and two for New Call records, described below. Only one button will show per record type.

  • Session Key for Task Record and Remote Support Command API
  • Session Key for Task Record and Remote Support Scripting API
  • Session Key for New Call Record and Remote Support Command API
  • Session Key for New Call Record and Remote Support Scripting API

Session Key Button Gives an Unknown Host Error

If you get an error stating, "Unknown host", this is essentially a communication issue from ServiceNow to the Secure Remote Access Appliance, unless the hostname is set incorrectly on the Secure Remote Access Appliance configuration.

Double-check the hostname on the Secure Remote Access Appliance configuration in ServiceNow. If that looks good, then recommend the customer involve their network team to determine if there is a network block in place such as a Firewall or network rule.

Requested Support Representative is not Available at This Time

If you get an error stating, "Requested support representative is not available at this time", this means the Use Rep Console for Session Keys is unchecked in the Secure Remote Access Appliance configuration AND the representative that is mapped to the ServiceNow user who generated the session key is not logged into the representative console.

Have the representative log into the representative console OR check the Use Rep Console for Sessions Keys checkbox. This will launch the Representative Console, if it is installed on the representative's workstation.

Error Validating Parameter 'queue_id': The Representative Could Not be Found

If you get an error stating, "Error validating parameter 'queue_id': The representative could not be found", this means the ServiceNow user, who is trying to generate a session key, is not mapped to a Remote Support user. Typically, customers will use an LDAP store for both ServiceNow and Remote Support, which means the usernames in each system will match exactly.

If an LDAP store is not used and the usernames between ServiceNow and Remote Support do not match exactly, you'll have to manually map the usernames so that when a session key is generated, a Remote Support user can be found.

For more information on this issue, please see the section titled Configure Remote Support Username and Authentication in this guide.

Sessions are not Associated with Records in ServiceNow

If a customer is using the feature where a record number is being manually entered into the External Key field during a session, but the session isn't getting associated with that record when the support session is written to ServiceNow, they may be using a record that is unsupported or they have customized the number prefix for the record type they are using. The supported types include Incident, Change Request, Service Catalog Request, and Problem. The corresponding record number prefixes include: INC, CHG, REQ, and PRB.

Ensure the customer is entering a record number format which is supported. Examples include INC0010074, CHG0000036, REQ0010001, or PRB0000101.

Another reason a support session may not be getting associated with a record in ServiceNow is that the custom field which links the support session to the ServiceNow record is never getting set on the support session. This can happen when a session starts outside of ServiceNow or with a custom component within ServiceNow.

Ensure the support session is starting from within ServiceNow and the customer is using out of the box components.

Invalid Custom Field Code Name

An "invalid custom field code name" error can occur when there is an attempt to generate a session key, but a custom attribute with that code name doesn't exist in the system. This can happen if a step is missed in the initial integration configuration.

Create the missing custom field and try to start another support session from ServiceNow.

Error Validating Parameter 'snow_task_id': The Session Attribute is Invalid

An "error validating parameter 'snow_task_id': The session attribute is invalid" error can occur when there is an attempt to generate a session key, but a custom attribute with that code name doesn't exist in the system. This can happen if a step is missed in the initial integration configuration.

Create the missing custom field and try to start another support session from ServiceNow.

Chat Dialogue or System Information not Showing in Session Record in ServiceNow

The chat dialogue or system information for a support session can be missing if ServiceNow hasn't been configured to allow the integration to write to the Journal Entry (named sys_journal_field) table.

Ensure the Journal Entry table Application Access is configured for Can create and Can update and accessible from All Application Scopes.