Troubleshooting

This section is designed to assist members of implementation and support teams who are either installing or supporting the ServiceNow integration with Remote Support. The items listed here cover potential issues you 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 refers to the application logs in ServiceNow, which can be found in System Logs > System Log > Application Logs.

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

  • Transaction Logs, found at System Logs > Transactions
  • All Logs, found at System Logs > System Log > All
  • Warning Logs, found at System Logs > System Log > Warnings
  • Error Logs, found at System Logs > System Log > Errors

Using this troubleshooting guide requires 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 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. Generate and copy a new client secret in Remote Support /login, save the API configuration, and 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. We recommend that you copy the value, immediately save the API account, and then paste the value in the appliance record in ServiceNow.
  • Ensure that the Integration Enabled box is checked.

If you get an error stating Unknown host, a communication issue from ServiceNow to the appliance likely exists, unless the hostname is set incorrectly on the appliance configuration.

Double-check the hostname on the 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 written in ServiceNow, there could be a communication issue. First check to ensure communication is open from Remote Support to ServiceNow.

  1. Log in to the Remote Support /login interface and ensure the Support Session End option 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.
  2. If the Outbound Event looks good, log in to the /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, involve your network team to determine if there is a network block in place, such as a firewall or network rule.
  3. 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 /api/x_bmgr_support_ent/outbound_event/session_end. 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 should recommend the customer involve their network team to determine if there is a network block in place such as a firewall or network rule.
  4. 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 appliance configuration 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. We recommend that you copy the value and immediately save the API Account, then paste the value in the appliance configuration 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 explain 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 appliance configuration record 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 Appliances menu was never clicked, as outlined in Update BeyondTrust Session Event Types.

Session Key Button is not Showing on the Incident Form

If the Session Key button is not displayed 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 appliance configuration record is named Default, with matching case and no white space. Any name other than Default will cause the Session Key button to be hidden.
  • If the name of the appliance configuration record is Default, look at the customer's 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 New Call Record and Remote Support Command API.
    • Session Key for New Call Record and Remote Support Scripting API.

For more information, please see Configure Incident States.

Session Key Button Gives an Unknown Host Error

If you get an Unknown host error, there is essentially a communication issue from ServiceNow to the Remote Support deployment, unless the hostname is set incorrectly on the appliance configuration record.

Double-check the hostname on the appliance configuration record in ServiceNow. If it looks correct, contact your 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

An error stating, Requested support representative is not available at this time means the Use Rep Console for Session Keys is unchecked in the appliance configuration record 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 in to the representative console OR check the Use Rep Console for Sessions Keys box. This launches the representative console, if it is installed on the representative's workstation.

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

An error stating, Error validating parameter 'queue_id': The representative could not be found means that the ServiceNow user trying to generate a session key is not mapped to a Remote Support user. Typically, customers use an LDAP store for both ServiceNow and Remote Support, which means the usernames in each system 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 Configure Remote Support Username and Authentication.

Sessions are Not Associated with Records in ServiceNow

If a customer is using the feature in which a record number is manually entered into the External Key field during a session, but the session isn't 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 that is supported. Examples include INC0010074, CHG0000036, REQ0010001, and 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.