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 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 refers to 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:
- 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
This troubleshooting guide assumes the audience has a basic 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. 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 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 appliance, 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 being written in ServiceNow, there could be a communication issue. First check to ensure communication is open from Remote Support to ServiceNow.
- Log in 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, 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, it is advisable to involve your 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 /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.
- 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 the Update 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 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.
- 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 Unknown host error, this 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
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 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 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 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.