DocumentationRelease Notes
Log In
Documentation

ServiceNow ITSM Enterprise

Suggest Edits

⚠️

Important

You must purchase this integration separately for both your Remote Support software and your ServiceNow solution. For more information, contact BeyondTrust's Sales team.

Service desks and customer support organizations using ServiceNow can integrate with BeyondTrust Remote Support to improve service levels, centralize support processes, and strengthen compliance. Features of the BeyondTrust Remote Support and ServiceNow integration are summarized below. Full details, how to obtain and install the integration, and implementation instructions are covered in this guide.

  • Outbound Support Sessions: Technicians can launch Remote Support sessions from within ServiceNow incidents, problem records, change requests, service catalog requests, and call records, using the Generate Session Key button.
  • Session Updates: Remote Support session data is written back to ServiceNow tickets. The basic integration includes chat transcripts. The enterprise integration includes chat transcripts, file transfers, system information, session notes, customer and representative surveys, session recordings, and more details about each Remote Support session.
  • Customer-Initiated Sessions: Through the ServiceNow Employee Self-Service module, customers can initiate chat sessions with Remote Support representatives from within ServiceNow incident records.
  • Jump Sessions: Technicians can connect directly to remote Configuration Items using Remote Jump, Local Jump, RDP, Shell Jump, and/or vPro technology.
  • Auto-Create: Cases can be automatically or manually created or associated with an ongoing Remote Support session, and linked to the session for session updates after the session. By default, the auto-create functionality is disabled and not available to users of the integration. There is no additional cost to enable this feature.

ℹ️

Note

For information on how to enable the auto-create feature, see ServiceNow Remote Support ITSM Auto-Create Feature, below.

Requirements

Outlined below are requirements for the enterprise versions of the Remote Support ServiceNow integration. If any of the integration requirements are not yet met, they must be in place before starting the integration setup process unless the associated features of the integration are not required.

Base integration requirements

A current version of a ServiceNow release, including:

  • A working Service Desk application
  • A working email configuration

A current release of BeyondTrustRemote Support including:

  • At least one usable representative console capable of generating session keys
  • A functional Remote Support site through which users can connect to representatives

To configure network firewall rules for this integration, do the following:

  • Allow TCP 443 traffic from the B Series Appliance to the appropriate ServiceNow instance.
  • Allow TCP 443 traffic from the appropriate ServiceNow instance to the B Series Appliance.
  • Optionally, use ServiceNow MID Servers for this integration.

ℹ️

Note

For more information on MID Servers, see MID Server Configuration.

Additional integration requirements

The enterprise version of BeyondTrust's ServiceNow integration has additional features that require certain ServiceNow functions to be operational to work correctly. If these functions are not set up or actively used, the integration can still be installed and the basic features will work, but the enterprise features will not be usable until the necessary ServiceNow functionality is implemented. This can be done after the initial installation of the integration update set(s). The additional features should immediately be usable, assuming the appropriate setup steps are taken during the integration setup as described in this guide.

To successfully integrate the BeyondTrust Jump Client services with ServiceNow, the following requirements must also be met and reviewed:

  • A functional ServiceNow configuration management database (CMDB)
  • One or more ServiceNow configuration items on which BeyondTrust Jump Client services can be or have been installed
  • A working ServiceNow Employee Self-Service (ESS) application and portal

The CMDB is used to launch Remote Support sessions based on the hostname of the machine added to the Configuration Item field of an incident. If the CMDB is not populated with any available hosts, BeyondTrust Remote Support Jump Clients cannot be used to remotely access them through ServiceNow's interface. These hosts can be added after the initial setup without making any changes to the integration.

BeyondTrust Remote Support includes support for all the major modern versions of Microsoft, Apple, and Linux. One or more computers running one of these operating systems must be populated in ServiceNow's CMDB for BeyondTrust Remote Support Jump features to work through ServiceNow. As mentioned above, this can be done after the initial installation of the integration.

ServiceNow's ESS portal is leveraged by the integration to allow ServiceNow users of the portal to request remote support from logged-in Remote Support representatives. This is not always desired, so some administrators prefer not to use the ESS portal. This is acceptable for installation, and the ESS portal can be deployed after the integration setup to enable the associated Remote Support features.

Test the firewall

It is important to test all requirements of the integration before beginning setup. Most of these can be tested by the Remote Support and ServiceNow administrators within their respective systems, but to test the network firewall, the BeyondTrust admin should take the following steps to confirm that the necessary rules are in place.

  1. Log in to a machine either external to the B Series Appliance's network or in the same VPN as the ServiceNow instance, depending on how ServiceNow is connecting to the B Series Appliance's network.
  2. Log in to the B Series Appliance's /appliance interface.
  3. Browse to Support > Utilities :: TCP Connection Test.
  4. Enter the hostname of the ServiceNow instance, enter the port number of 443, and then click Test. A successful result is a Connected status message.

ℹ️

Note

Do not enter the protocol when entering the ServiceNow instance (https://servicenow.example.com, for example). Instead, use only the fully qualified domain name (servicenow.example.com). In most environments, BeyondTrust Remote Support resides in a DMZ network and has a public DNS address which ServiceNow contacts over the public internet. In some environments, Remote Support is not publicly accessible. In these cases, contact ServiceNow about implementing a VPN connection to your internal network for ServiceNow. For more information, see Virtual Private Network (VPN).

Configure Remote Support

All of the steps in this section take place in the BeyondTrust /login administrative interface. Access your Remote Support interface by going to the hostname of your B Series Appliance followed by /login (e.g., https://support.example.com/login).

Verify the API is enabled

The Remote Support integration requires the Remote Support XML API to be enabled. This feature is used from within the integrating software to communicate with the Remote Support APIs.

Go to /login > Management > API Configuration and verify that Enable XML API is checked.

Create a ServiceNow OAuth API account

  1. Go to /login > Management > API Configuration.
  2. Click Add to create a new API account. Name it ServiceNow or something similar.
  3. Set Command API to Full Access.
  4. Under Reporting API, check all options.
  5. The OAuth Client ID and OAuth Client Secret are used during the OAuth configuration step in ServiceNow. Make note of these and store them in a secure location.
  6. Click Save.

Set up session send

There are two ways to send sessions from Remote Support to ServiceNow: as Outbound events in Remote Support, or as scheduled jobs in ServiceNow. Outbound events send sessions as they end. Scheduled jobs pull sessions at specified intervals. The preferred option depends on your workflow preferences and session volumes. You can use only one method, but you can change methods by reconfiguring session sending.

Add outbound events for session import

Outbound events are used to notify ServiceNow that a Remote Support session has finished and is ready to be imported into ServiceNow.

  1. Go to /login > Management > Outbound Events.
  2. Click Add and name the new HTTP recipient ServiceNow Integration or something similar, depending on your ServiceNow instance.
  3. Enter the URL https://example.service-now.com/api/x_bmgr_support_ent/outbound_event/session_end, where example.service-now.com is the ServiceNow instance name.
  4. If using an outbound event token for added security, append outbound_event_token=YOUR-TOKEN to the end of the URL, so that the entire URL resembles https://support.example.com/x_bmgr_support_ent/outbound_event/session_end?outbound_event_token=YOUR-TOKEN. You must also store this token with the appliance configuration record in ServiceNow.
  5. Scroll to Events to Send and check the following events:
    • Support Session End
    • Customer Exit Survey is Completed
    • Representative Survey is Completed
  6. At the top of the page, click Save.

Set up schedule job for session import

Rather than using outbound events to notify ServiceNow that a Remote Support session is ready to be imported, you can use a mechanism in ServiceNow known as a scheduled job. Using a scheduled job, you can poll the Remote Support Reporting API for the latest sessions on any schedule you prefer. Scheduled jobs are configured in ServiceNow.

ℹ️

Note

For information on how to set up a scheduled job, see Set up Scheduled Job for Session Import.

Set up the custom link

Remote Support custom links can be configured to allow representatives to quickly access the ServiceNow incident that is associated with the session.

  1. Browse to Rep Console > Custom Links.

  2. Click Add to create a new custom link.

  3. Enter a name for the link, and then set the URL, according to the task view, where support.example.com is the ServiceNow instance name. If needed, you can use any of the available macros to customize the link according to your specifications. The options are:

    • Task - Standard View:

      https://example.service-now.com/nav_to.do?uri=task.do?sys_id=%SESSION.CUSTOM.SNOW_TASK_ID%

    • Task - Agent Workspace View:

      https://example.service-now.com/now/workspace/agent/record/task/%SESSION.CUSTOM.SNOW_TASK_ID%

    • Interaction - Standard View:

      https://example.service-now.com/nav_to.do?uri=interaction.do?sys_id=%SESSION.CUSTOM.SNOW_INTERACTION_ID%

    • Interaction - Agent Workspace View:

      https://example.service-now.com/now/workspace/agent/record/interaction/%SESSION.CUSTOM.SNOW_INTERACTION_ID%

ℹ️

Note

If the customer is using an external key to store the task sys_id, then use the macro %SESSION.CUSTOM.EXTERNAL_KEY% instead.

  1. Click Save to save the new link.

Create custom fields

Remote Support custom fields are used to map ServiceNow Tasks (incidents, change requests, problem records, and service catalog requests), call records, and configuration items to Remote Support sessions.

  1. Browse to Configuration > Custom Fields.
  2. Click Add to create a new custom field.
  3. Enter the following values:
    • Display Name: ServiceNow Task ID
    • Code Name: snow_task_id
    • Show in Rep Console: checked
  4. Click Save to save the new field.
  5. Repeat these steps for the following custom field values:
    • Display Name: ServiceNow Configuration Item ID
    • Code Name: snow_cmdb_ci_id
    • Show in Rep Console: checked
  6. Also for the following custom field values:
    • Display Name: ServiceNow Call ID
    • Code Name: snow_call_id
    • Show in Rep Console: checked
  7. And again for the following custom field values:
    • Display Name: ServiceNow Interaction ID
    • Code Name: snow_interaction_id
    • Show in Rep Console: checked

Configure ServiceNow

Unless otherwise noted, all of the steps in this section take place in the ServiceNow interface. We recommend that you initially use development or test instances of ServiceNow before installation in the production instance, so that the integration can be thoroughly tested.

Install BeyondTrust integration

The Integration must be purchased directly from BeyondTrust. After the purchase, it is installed via the ServiceNow Store. There is no mechanism to purchase the integration at the ServiceNow Store.
Follow the steps below to request and install the integration.

  1. Log in to your ServiceNow platform with your corporate account. Please contact your company Now Support (HI) admin if you do not have credentials.
  2. Search for BeyondTrust Remote Support Enterprise Integration, or go to the app's page.
  3. Click Request App.
  4. Request Remote Support with ITSM.
  5. Within a business day, BeyondTrust approves the request with a $0 purchase price, and sends a copy of these installation instructions to the requester.
  6. Once you receive the confirmation, return to the app's page in the ServiceNow store.
  7. Click Complete Purchase.
  8. Review the contract details.
  9. If you agree, check Accept the Site Terms of Use.
  10. Click Complete Purchase.
  11. The app is ready for installation on your ServiceNow instance(s).
  12. Repeat the steps below for each instance.
  13. Login to the ServiceNow instance on which you want to install the app.
  14. Navigate to System Applications > All Available Applications > All.
  15. Search for the app you want to install.
  16. Click Install.

📘

For more information on installing applications, please see ServiceNow's Help Page.

Create local update set

Local update sets are used in ServiceNow to capture configuration changes. They can be used to quickly transfer these configuration changes to other environments.

  1. Browse to System Update Sets > Local Update Sets and click the New button above the list of update sets to create a new local update set.
  2. In the Name field, enter BeyondTrust - ServiceNow Integration Configuration (or an equivalent).
  3. Click Submit and Make Current. This update set captures any changes you make during the configuration process. Just make sure that the BeyondTrust - ServiceNow Integration Configuration update set is selected in ServiceNow's update set dropdown for the following steps.
  4. Make sure the Application is set to BeyondTrust Remote Support Enterprise Integration. If it is not, use the settings cog in the upper right of the screen to switch to the aforementioned scope.
  5. After configuration is complete and tested, the local update set can be imported or promoted to new instances of ServiceNow (e.g., the production instance) to quickly replicate the integration. This must be done after transferring the BeyondTrust - ServiceNow retrieved update set.

📘

For more information, please see Transfer update sets.

Update BeyondTrust session event types

Event types are used to control which Remote Support events are processed with a Remote Support session import. This step updates the database with all the available event types.

  1. Browse to BeyondTrust Remote Support > Update Event Types.
  2. This loads all the available Remote Support session event types into the database, so that unwanted events can be filtered out in a subsequent step when setting up your appliance configuration record.

📘

Clicking the link again does not duplicate records and shows that zero event types were inserted.

Set up ServiceNow integration with Remote Support

To set up a ServiceNow integration with Remote Support, follow these instructions:

  1. Browse to BeyondTrust Remote Support > Appliances.
  2. Click New to add a new Remote Support appliance record and enter the following values:
    • Name: Must be Default.
    • Hostname: Hostname of the Remote Support deployment.
    • OAuth Client ID: The OAuth client ID that is used to authenticate to the Remote Support deployment. This is obtained in a previous step, Create a ServiceNow OAuth API account.
    • OAuth Client Secret: The OAuth client secret that is used to authenticate to the Remote Support deployment. This is obtained in a previous step, Create a ServiceNow OAuth API account.
    • Integration Enabled: Turns the integration on and off.
    • Import External Sessions: If checked, session reports for sessions that are started external to ServiceNow are imported into ServiceNow.
    • Outbound Event Token: The token that is used as an added security measure to confirm outbound events are coming from the Remote Support deployment that is sending the same token. If left blank, this outbound event token process is ignored. If a value is provided, however, the same value must be sent from all outbound events coming from BeyondTrust as a parameter named outbound_event_token.
    • Accepted IP Addresses: A comma-separated list of IP addresses from which this integration accepts outbound events.
    • Auto Associate With User: If checked, when the session report is imported, the integration attempts to associate a ServiceNow user with the session. The lookup is based on the session's primary representative username.
    • Use Rep Console for Session Keys: By default, session keys are provided by the Remote Support representative console through the use of BeyondTrust Representative Console Script (BRCS) files. If Use Web Console is checked, session keys are provided by the Remote Support web rep console.
    • Work Note Logging
      • Log Session Notes: If checked, session notes are logged to the task's work notes field.
      • Log Session End: If checked, a session end notice is logged to the task's work notes field.
      • Log Generate Session Key: If checked, a work note is logged each time a technician generates a session key.
      • Log Customer Initiated Sessions: If checked, a work note is logged each time a user starts a session with a technician from the employee self-service module.
    • Employee Self Service
      • Issues: A list of issues, each of which must match a Remote Support issue by code name, that is presented to customers in the employee self-service module. In a subsequent step, you have the option to load issues from the Remote Support deployment with the click of a button.
      • Self Service Enabled: If checked, a Get Support Now button is displayed on the incident form that customers in the employee see in the self-service module.
      • Session Start Type: Determines how to start a Remote Support session, either by click-to-chat or a full session, for customers requesting support in the employee self-service module.
      • Miscellaneous
        • Events to Import: A list of BeyondTrust session events to process when importing a BeyondTrust session.

📘

You cannot configure this setting until after the appliance configuration record has been saved.

Configure events to import

Event types are used to control which Remote Support events are processed with a Remote Support session import. This step defines which events are processed for each Remote Support session import.

  1. Browse to BeyondTrust Remote Support > Appliances.
  2. Click the name of your appliance configuration record in ServiceNow.
  3. Click the Miscellaneous tab.
  4. Click the Edit Events to Import button (the lock icon).
  5. Click the Add/Remove multiple button (the group of people icon) located on the right side of the field.
  6. Select the events you want from the Collection field on the left and use the arrows to move the events to the List field on the right.

📘

You can use CTRL+A to select all events.

  1. Click the Save button when you are finished.

Configure self-service issues

Issues are used to allow customers to select what type of issue they have when requesting a session with a Remote Support representative. These issues are mapped to Remote Support issues (configured in /login) and can be used to route Remote Support sessions.

  1. Browse to BeyondTrust Remote Support > Appliances.
  2. Click the name of your appliance configuration record.
  3. Click Load Issues in the Appliance title bar to auto-load the issues you want from the Remote Support deployment. You are alerted with a summary of how many issues were added and/or updated.
  4. Optionally, you can manually add Issues to the list by clicking the Employee Self Service tab, then double-clicking Insert a new row… at the bottom of the list. Double-click each column to set the value. Changes are immediately saved when you press Enter or click outside of the field.

Configure journal entry table

The Journal Entry table (sys_journal_field), which is used to log chat dialogue and session notes, must be set to allow other scopes to insert records.

  1. Browse to System Definition > Tables.
  2. Search by Label for Journal Entry.
  3. Click the link titled Journal Entry.

📘

If prompted to edit the record in Global scope, do so.

  1. Click the Application Access tab.
  2. Ensure that the Accessible From field is set to All application scopes.
  3. Ensure that Can Create and Can Update are checked.
  4. Click the Update button.

Configure Remote Support session related lists

Related lists are used to provide a list of Remote Support sessions that are associated with a task (incident, problem record, change request, or service catalog request), call record, configuration Item, or interaction.

Task configuration

  1. Browse to Incident.
  2. Click Open to see a list of open incidents.
  3. Select an incident by clicking the Incident Number.
  4. Right-click the Incident title bar and select Configure > Related Lists.
  5. Ensure that Support Session > Task has been moved to the Selected column.
  6. Click the Save button.
  7. The Remote Support Sessions list appears towards the bottom of the incident form once these steps are complete.

CMDB configuration

  1. Browse to Configuration > Servers.
  2. Click All to see a list of servers.
  3. Select a server by clicking the Name of a server.
  4. Right-click the Incident title bar and select Configure > Related Lists.
  5. Ensure that Support Session > Configuration Item has been moved to the Selected column.
  6. Click the Save button.
  7. The Remote Support Sessions list appears towards the bottom of the configuration item form once these steps are complete.

Call configuration

  1. Browse to Service Desk.
  2. Click My Open Calls to see a list of calls.
  3. Select a call by clicking the Number of a call.
  4. Right-click the Incident title bar and select Configure > Related Lists.
  5. Ensure that Support Session > Call has been moved to the Selected column.
  6. Click the Save button.
  7. The Remote Support Sessions list appears towards the bottom of the call form once these steps are complete.

Interaction configuration

  1. Browse to Interaction.
  2. Click Open to see a list of open interactions.
  3. Select an incident by clicking the Interaction Number.
  4. Right-click the Interaction title bar and select Configure > Related Lists.
  5. Ensure that Support Session > Interaction has moved to the Selected column.
  6. Click the Save button.
  7. The Remote Support Sessions list appears towards the bottom of the interaction form once these steps are complete.

📘

If using the Agent Workspace, the following views should also be configured to display the list of related Remote Support sessions.

Task configuration — agent workspace

  1. In Agent Workspace, browse to the Open Incidents list.
  2. Select an incident by clicking the Incident Number.
  3. Click the User Menu (context menu displayed when clicking the user icon in the upper-right corner) and select Configure Page > Related Lists.
  4. Ensure that Support Session > Task has moved to the Selected column.
  5. Click the Save button.
  6. When you refresh the Agent Workspace view, the Support Sessions list is available alongside the other related items.
  7. Repeat steps 1-6 for the other task types in use (problem change request, service catalog request).

Interaction configuration — agent workspace

  1. In Agent Workspace, browse to the Interactions list.
  2. Select an Interaction by clicking the Interaction Number.
  3. Click the User Menu (context menu displayed when clicking the user icon in the upper-right corner) and select Configure Page > Related Lists.
  4. Ensure that Support Session > Interaction has moved to the Selected column.
  5. Click the Save button.
  6. When you refresh the Agent Workspace view, the Support Sessions list is available alongside the other related items.

CMDB configuration — agent workspace

  1. In Agent Workspace, browse to a CMDB list.
  2. Select an item by clicking the Name.
  3. Click the User Menu (context menu displayed when clicking the user icon in the upper-right corner) and select Configure Page > Related Lists.
  4. Ensure that Support Session > Configuration Item has been moved to the Selected column.
  5. Click the Save button.
  6. When you refresh the Agent Workspace view, the Support Sessions list is available alongside the other related items.
  7. Repeat steps 1-6 for other types in use.

CMDB support session — agent workspace

  1. Navigate to https://support.example.com/nav_to.do?uri=%2Fslushbucket.do%3Fsysparm_referring_url%3Dx_bmgr_support_ent_support_session.do%26sysparm_view%3Dworkspace%26sysparm_list%3Dx_bmgr_support_ent_support_session%26sysparm_form%3Drelated_list, where support.example.com is the ServiceNow instance name.
  2. Ensure the following related lists are selected: Rep, Customer, Custom Attribute, Recording, Customer Exit Survey, Rep Exit Survey, Event, and Team. These should already be selected by default, but add any that might be missing.
  3. Even if no changes are necessary, click Save.
  4. Support Sessions now show all the related items within Agent Workspace.

Configure incident caller Jump macros

Remote Support Jump technology can be used for unattended access to devices.

  1. Browse to Incident and click Open to see a list of open incidents.
  2. Select an incident by clicking the Incident Number. Populate the Caller field by clicking the Magnifying Glass icon, and then selecting an item from the list.
  3. Once the Caller field is populated, click the Update button on the incident title bar. This returns you to the incident list. Again, click the name of the incident you just updated.
  4. Right click the Caller Label and click Configure Dictionary.
  5. Locate the Attributes field and take note of the part of the value that reads ref_contributions=task_show_ci_map.
  6. Add any of the values listed below as a semicolon-separated item in ref_contributions. For example, ref_contributions=x_bmgr_support_ent_bomgar_user_jump;task_show_ci;show_related_records.
  7. Click Update to save your changes.

Configure task CMDB Jump macros

Remote Support Jump technology can be used for unattended access to devices.

  1. Browse to Task and click Open to see a list of open incidents.
  2. Select a task by clicking the Task Number. Populate the Configuration Item field by clicking the Magnifying Glass icon, and then selecting an item in the list.
  3. Once the Configuration Item is populated, click Update on the task title bar. This returns you to the task list. Again, click the name of the task you just updated.
  4. Right click the Configuration Item Label and select Configure Dictionary.
  5. Locate the Attributes field and take note of the part of the value that reads ref_contributions=task_show_ci_map;show_related_records.
  6. Add any of the values listed below as a semicolon-separated item in ref_contributions. For example, ref_contributions=x_bmgr_support_ent_bomgar_jump_to;task_show_ci;show_related_records.
  7. Click Update to save your changes.

📘

If the macro icon does not display next to the Configuration Item field when the field is populated with a value, you must verify whether there is a Dictionary Override by following the steps below.

  1. Right-click the Configuration Item Label and click Configure Dictionary.
  2. Locate the Dictionary Overrides related list. Determine if there is an entry in this list for the type of task you are working with (e.g. change_request), and click the item if it exists.
  3. If the Override attributes field is checked, then the attributes are being overridden and you must add the macro to the Attributes field.
  4. Locate the Attributes field and take note of the part of the value that reads ref_contributions=task_show_ci_map;show_related_records.
  5. Add any of the values listed above as a semicolon-separated item in ref_contributions.

Configure service portal widget

  1. Browse to Service Portal > Service Portal Configuration.
  2. Click on the Designer pane.
  3. In the list of pages, find the page where you would like to place the widget . By default, the Home Page is the main landing page and this is indicated by a small house icon on the pane.
  4. Click the desired page to edit the design.
  5. In the page designer, find the widget titled Get Support Now.
  6. Drag and drop the widget into the desired area of the page.
  7. The widget can be placed on additional pages, if desired. Repeat the steps above for each additional page where the widget is desired.
  8. You can now use the widget from the Service Portal home page or any page where it was added. Service Portal users may select one of the loaded issues in order to initiate a session.

Set up scheduled job for session import

📘

If you have set up the integration using Add outbound events for session import, do not set up a scheduled job.

  1. Browse to System Definition > Scheduled Jobs and click New at the top of the list.
  2. Click the link titled Automatically run a script of your choosing.
  3. Provide the following values:
    • Name: Import Remote Support Sessions
    • Run: Periodically
    • Repeat Interval: 05 (representing 5 minutes)
    • Run this script: (new x_bmgr_support_ent.BomgarRemoteSupport()).pullPendingBomgarReports();
  4. Click Submit to save the job.

Activate the pull sessions module option

As a way to test the retrieval of Remote Support sessions and as a means to manually pull Remote Support sessions, we have a module which is inactive by default, but which can easily be activated and used.

  1. To activate the module, browse to System Definition > Modules.
  2. Search for text with the value Pull Support Sessions.
  3. Click the record titled Pull Support Sessions.
  4. Find the check box labeled Active, check the box, and click Update.
    The Pull Support Sessions link is now visible beneath the BeyondTrust Remote Support Integration menu. Clicking this link pulls only sessions that have occurred after the latest session imported into ServiceNow. If no sessions have been imported into ServiceNow, sessions which occurred over the past 24 hours are retrieved.

Configure incident states

Incident states are used in the Remote Support integration, specifically UI actions (like Generate Session Key) to control when the button shows up on incident forms.

  1. Browse to Incident.
  2. Click Open to see a list of open incidents.
  3. Select an incident by clicking the Incident Number.
  4. Right-click the label State and select Show Choice List.
  5. Filter the list by Table=incident. Take note of the different incident choices, specifically the value of incidents with a label of Resolved or Closed and any custom incident states for which BeyondTrust Session Key should not appear.
  6. Return to the incident and right-click the Session Key button located in the Incident title bar.
  7. Select Configure > UI Actions.
  8. In the UI Actions list, click BeyondTrust Session Key.
  9. Focus the Condition field and ensure current.incident_state is configured to include the IDs of the incident states for which the Session Key button should not appear.
  10. If the Resolved and Closed fields you took note of earlier have values of 6 and 7, then the Condition field mentioned above should include the code current.incident_state < 6 so as not to show a Remote Support Session Key button on resolved or open incidents. If there are custom incidents (e.g., Complete), then the condition field may require logic such as && current.incident_state != 8.For example, if the button should not appear for incident states 6, 7, and 10, while it should appear for states 1-5, 8, and 9, then the following can be used: gs.hasRole('itil') && current.incident_state != 6 && current.incident_state != 7 && current.incident_state != 10.

Configure Remote Support username and authentication

  1. Log in to your BeyondTrust /login interface with the same credentials as a ServiceNow user who is expected to use BeyondTrust.
  2. Download and install a BeyondTrust representative console from the /login > My Account tab.

Troubleshoot login failure

If the login fails, check the following:

  • Make sure that BeyondTrust and ServiceNow are checking credentials against the same LDAP server(s), if appropriate. Check the LDAP server in the BeyondTrust interface under /login > Users & Security > Security Providers.
  • If LDAP authentication is not being used, log in to ServiceNow. Select User Administration > Users, and then select the user to be used for testing and focus on the BeyondTrust Username field.
  • If this field does not exist while viewing a user, hover over the icon next to User on the title bar, and then select Configure > Form Layout and move the BeyondTrust Username field from the Available list to the Selected list. Once done, enter the name of a known-working BeyondTrust user account in this field and save.

📘

For more information on how to check the LDAP server for ServiceNow, please see LDAP Integration.

Configure email notifications

  1. Browse to System Notification > Email > Notification.
  2. Filter by Name=Bomgar, and then click Bomgar Notification.
  3. Verify that:
    • When to send > Send When equals Event is fired.
    • When to send > Event Name equals x_bmgr_support_ent.link.notification.
    • Who will receive > Users/groups in fields equals Caller.
    • Table equals Incident [incident].
  4. Customize the Message text under the section What it will contain. This defaults to the event.parm2 variable. By default, event.parm2 contains only the BeyondTrust session key URL, though this can be changed in the BeyondTrust Integration's Appliance settings.
  5. Browse to System Properties > Email Properties. Verify that the settings are correct for your network.

Assign users appropriate roles

Give ITIL users who provide technical support using this integration the x_bmgr_support_ent.itil role.

📘

You must elevate the admin's role in order to make the following change.

  1. Browse to User Administration > Users.
  2. Select a user.
  3. Find the Roles tab and click the Edit button.
  4. Add the x_bmgr_support_ent.itil role from the Collection list to the Roles list.
  5. Click Save.

Use ServiceNow MID server option

It is possible to avoid direct connection between ServiceNow and Remote Support by using a MID server for internal Remote Support deployments.
To configure the integration to use a MID server for API requests to a Remote Support site, specify the MID server to use on the individual outbound REST messages:

  1. In ServiceNow, navigate to System Web Services > Outbound > REST Message.
  2. Filter to show only messages for the BeyondTrust application being configured.
  3. Click the Name of one of the messages to edit its properties.
  4. In the HTTP Methods related list at the bottom, select the Name of the method (typically post).
  5. On the resulting form, select the HTTP Request tab and select your MID server in the Use MID Server field.
  6. Click Update to save the changes.

Repeat these steps for each outbound REST message that is a part of the application.

📘

For more information on MID servers, please see MID Server.

Use rep survey task association option

It is possible to associate Remote Support sessions with ServiceNow incidents by means of a field in the rep exit survey. Several things need to be configured to make this functionality work.

Configure rep exit survey in Remote Support

  1. In Remote Support /login, browse to Public Portals > Exit Surveys.
  2. Under Representative Survey, click the Add button and select Text Box.
  3. For Question Text, type Enter the task number. Make sure Question Name has the value of task_number and the Answer Required check box is checked.

Configure rep exit survey business rule in ServiceNow

  1. In ServiceNow, browse to System Definition > Business Rules, search by name for Associate Session via Rep Survey and click the business rule with the same name.
  2. In the Business Rule record, the Active check box is unchecked by default. Check this box and click Update to save the record.

Once these changes have been made, sessions started outside of ServiceNow are associated with a task record within ServiceNow. The representative pastes the number or sys_id of a task in ServiceNow to that which they want to associate the Remote Support session, at the end of the session.

Test integration

The following tests take place in ServiceNow and Remote Support and are provided to ensure that the integration is working properly. Troubleshooting suggestions are provided with each step in case of failure.

Test connectivity from ServiceNow and Remote Support

The Load Issues button is an effective and quick way to test connectivity from ServiceNow to Remote Support.

  1. Log in to ServiceNow as an administrator.
  2. Browse to BeyondTrust Remote Support and click Appliances.
  3. Select the Default appliance configuration record.
  4. Ensure the Hostname, OAuth Client ID and OAuth Client Secret fields are properly configured and the Integration Enabled check box is checked.
  5. Click the Load Issues button at the top of the form.

If connectivity is successful, a browser alert box shows the number of issues that were retrieved.

If connectivity is unsuccessful, a browser alert box shows a message stating Something went wrong while attempting to load issues, or Unknown host. If you receive one of these messages, 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 must 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.
  • Ensure the Integration Enabled check box is checked.

If the configuration appears to be correct, check the Application Logs under System Logs > System Log > Application Logs to see if there are any errors of note.

Ultimately, there might be something blocking network traffic somewhere between ServiceNow and Remote Support, like a firewall or network rule. If you suspect this is the case, we recommend you ask your network team to help identify the problem.

Test session key generation

  1. Log in to the Remote Support representative console, and then log in to ServiceNow with the same account. If Remote Support and ServiceNow use different authentication systems, manually assign your Remote Support user to your ServiceNow user as described in Configure Remote Support Username and Authentication.
  2. Open a closed incident in ServiceNow, open a resolved incident, and make sure the Session Key button does not appear for either of them.
  3. Open a test incident in ServiceNow. Confirm the State field matches one of the values for which the Session Key button should appear, and make sure the button appears as expected. Remember that the incident must be saved before the button will appear.
  4. Go to BeyondTrust Remote Support > Appliances > Default and check whether the Use Rep Console for Session Keys field is checked.
    • If Use Rep Console for Session Keys is checked, click the Session Key button. This launches the Remote Support representative console, subsequently opening the Session Key dialog box.
    • If Use Rep Console for Session Keys is not checked, click the Session Key button. It returns a window with a seven-digit session key, along with a session key URL and a button to email the key. In case of failure, make sure the following are true:
      • The ServiceNow user account is mapped to a Remote Support user account as described in this guide.
      • The ServiceNow API User Connection test completes successfully.
      • The Remote Support Hostname and OAuth Client fields are set correctly in ServiceNow under BeyondTrust Remote Support > Appliances > Default.

Test Remote Support session import

  1. Log in to ServiceNow as an ITIL user or an admin.
  2. Use the Session Key button as described above to start a Remote Support session.
  3. End the session from the representative console and close any surveys and/or session end messages on the representative and/or customer sides of the session.
  4. Refresh the ServiceNow incident from which the session key was generated, scroll to the bottom of the page, and check the Remote Support Sessions list. There should be an entry for the recent session. If not, make sure the following are true:
    • The API User Connection test works correctly as described above.
    • There are no Remote Support errors reported for your ServiceNow instance in the Remote Support Outbound Events list. Your Remote Support admin can check this in Remote Support from the /login web interface under Management > Outbound Events.
    • The IP address is set up correctly, following the steps below:
      • Log in to ServiceNow as an admin.
      • Browse to System Logs > Transactions, remove all existing filters, and add a URL filter of /api/x_bmgr_support_ent/outbound_event/session_end.
      • Click one of the results and make sure the originating IP address of the transaction is included in the IP Address field of the integration Appliance settings under BeyondTrust Remote Support > Appliances > Default.

Test Remote Support get support now (ESS)

  1. Log in to ServiceNow as a non-admin (non-ITIL) user, or use the key icon in the upper-left of the screen to switch to such a user if an admin is already logged in.
  2. Locate or create an incident that has an assigned non-ITIL caller and an assigned ITIL technician.
  3. Use the Impersonation key icon in the upper-left corner of the screen to impersonate the non-ITIL user for the above incident.
  4. Open the incident and click Get Support Now.
  5. If you do not see a Get Support Now button, make sure that Self Service Enabled is checked under BeyondTrust Remote Support > Appliances > Default > Employee Self Service.
  6. The customer is presented with the list of the issues configured as Active under BeyondTrust Remote Support > Appliances > Default > Employee Self Service.
  7. If the session does not start, then in the Remote Support deployment, go to /login > Public Portals > Public Sites and edit the public site for the configured site address under BeyondTrust Remote Support > Appliances > Default, and make sure Use Issue Submission Survey is enabled.

Test Remote Support Jump Technology

  1. Log in to the Remote Support representative console and search for a Jump Client that is currently running on a machine included in the ServiceNow CMDB. This ensures the Jump Client in question can be accessed using the configuration item (CI) in ServiceNow incidents.
  2. In ServiceNow, create or open an incident, assign the above host as the CI of the incident, and click the orange Jump to CI with BeyondTrust Remote Support button.
  3. Run the resulting BRCS file and make sure the representative console launches a session with the remote host in question.

Transfer update sets

The steps below are typically used after the integration has been imported and configured in a test/development instance of ServiceNow and is being transferred to a production instance. However, they are also applicable to transferring the integration between any ServiceNow instances.

  1. Follow the steps in the ServiceNow documentation to transfer the BeyondTrust - ServiceNow Integration update set(s) into the destination instance of ServiceNow.

ℹ️

Note

This is typically achieved by retrieving the update sets from the destination instance or by exporting the update sets from the original instance as XML files. For details, see ServiceNow's Export and Import XML files.

  1. Follow the same steps to transfer the BeyondTrust - ServiceNow Integration Configuration update set.

Configure production outbound event

  1. In the BeyondTrust interface, go to /login > Management > Outbound Events.
  2. Copy the URL of the event for the original ServiceNow instance.
  3. Click Add to create a new HTTP recipient.
  4. In the URL field, paste and replace the name of the original ServiceNow instance with that of the new one such that /api/x_bmgr_support_ent/outbound_event/session_end is preserved at the end. The result should be similar to https://example.service-now.com/api/x_bmgr_support_ent/outbound_event/session_end, as opposed to https://example-dev.service-now.com/api/x_bmgr_support_ent/outbound_event/session_end.
  5. Scroll to Events to Send and check the following events:
    • Support Session End
    • Customer Exit Survey is Completed
    • Representative Survey is Completed
  6. Scroll to the bottom and click Add Recipient.
  7. Locate the outbound event created during testing and click Edit.
  8. Check Disabled and save.

Configure custom link

  1. Browse to /login > Rep Console > Custom Links.
  2. Edit or add a link and update the ServiceNow URL to direct to the destination instance of ServiceNow. Be careful to preserve /nav_to.do?uri=task.do?sys_id=%EXTERNAL_KEY% at the end.
  3. Click Save.
  4. Test the integration setup in its new location following the same steps used to test the original instance.

ℹ️

Note

For more information, see Test the Setup of the BeyondTrust and ServiceNow Integration.

Auto-create

The ServiceNow Remote Support Auto-Create Feature allows you to provide automatic creation of records in ServiceNow as an optional feature of the ServiceNow Enterprise Integration.

This feature is part of the ServiceNow Remote Support ITSM application. By default, the auto-create functionality is turned off and is not available to the integration users. There is no additional cost to use the feature. To enable this feature, refer to the following sections:

  1. Configure BeyondTrust Remote Support for Auto-Create.
  2. Configure ServiceNow for Auto-Create.
  3. Test BeyondTrust and ServiceNow Auto-Create.

Configure Remote Support for auto-create

All of the steps in this section take place in the BeyondTrust Remote Support /login administrative interface. To access your Remote Support interface, append /login to the end of the hostname of your Remote Support instance (for example, https://support.example.com/login).

Create record request

Just as there are two ways to send session information from Remote Support to ServiceNow, there are two ways to create the record request: within Remote Support as an outbound event, and within ServiceNow as a custom link.

⚠️

Important

You cannot use Option 1 and Option 2 simultaneously. You must choose one or the other, based on their use cases and process. We recommend you use the same process as used for sending session information. For example, if you use outbound events to send information, you should use outbound events to create the record. For more information, see Set Up Session Send.

Option 1: add outbound events

Outbound events are used to notify ServiceNow that a representative has joined a Remote Support session and a create record request can be sent to ServiceNow.

  1. Go to /login > Management > Outbound Events.
  2. Click HTTP Recipient Add and name it ServiceNow Integration or something similar, depending on your ServiceNow instance.
  3. Set the URL to https://example/service-now/com/api/x_bmgr_support_ent/outbound_event/case?auto_create=true, in whichexample.service-now.com is the ServiceNow instance name.
  4. Scroll to Events to Send and check the following event: Someone Joins a Support Session.
  5. At the top of the page, click Save.

Option 2: set up custom link

Remote Support custom links can be configured to allow representatives to auto-create ServiceNow records from within the Remote Support representative console.

  1. Browse to Rep Console > Custom Links.
  2. Click Add to create a new custom link.
  3. Enter a name for the link, and then set the URL according to one of the following settings, where support.example.com is the ServiceNow instance name. If needed, you can use any of the available macros to customize the link according to your specifications.
  • To have the new item open in the standard view, enter: https://example.service-now.com/nav_to.do?uri=x_bmgr_support_ent_auto_create_link.do?lsid=%SESSION.LSID%%26username=%REP.USERNAME%%26auto_create=true
  • To have the new item open in the Agent Workspace view, enter: https://example.service-now.com/nav_to.do?uri=x_bmgr_support_ent_auto_create_workspace_link.do?lsid=%SESSION.LSID%%26username=%REP.USERNAME%%26auto_create=true
  1. Click Save to save the new link.

Configure custom fields

There are several custom fields available to use in an auto-create scenario. These fields can be used to populate values when the session starts, and then configured in ServiceNow to be mapped to record fields.

  1. Browse to Configuration > Custom Fields.
  2. Click Add to create a new Custom Field for each of the following custom field code names:
    • customer_email
    • customer_username
    • snow_task_id (this field may have already been created with the base ServiceNow Enterprise integration configuration).
    • snow_interaction_id (this field may have already been created with the base ServiceNow Enterprise integration configuration).
    • custom_field_1
    • custom_field_2
    • custom_field_3

ℹ️

Note

The Code Names must match, but the Display Name is arbitrary.

Configure ServiceNow for auto-create

Unless otherwise noted, all of the steps in this section take place in the ServiceNow interface. We recommend that you initially use development or test instances of ServiceNow before installation in the production instance so that the integration can be thoroughly tested.

Enable auto-create functionality

Follow these steps to enable auto-create:

  1. Browse to BeyondTrust Remote Support and click Appliances. Select the B Series Appliance you are configuring.
  2. Right-click on the title bar, and then select Configure > Form Layout.
  3. Drag the field labeled Auto Create Enabled from the Available list to the Selected list.
  4. Click the Save button.
  5. The Auto Create Enabled check box is displayed on the form. Check this box, and then click the Update button on the title bar. The form reloads.

Set up auto-record creation fields

A section labeled Auto-Record Creation is displayed just below the main (top) section of the form. This section contains the following fields:

  • Auto-Create For These Portals (comma-separated list): List public portals here to auto-create session for these portals.
  • Required Auto-Create Custom Fields (comma-separated list): List the mandatory custom fields that must be populated with a value to auto-create a record.
  • Auto-Create for Attended Sessions (check box): Check to auto-create sessions that are attended by a customer.
  • Auto-Create for Unattended Sessions (check box): Check to auto-create sessions that are not attended by a customer.
  • Auto Create Record Type: Select the type of record to auto-create. Options include:
    • Call: new_call
    • Incident: incident
    • Change Request: change_request
    • Service Catalog Request: sc_request
    • Problem: problem
    • Interaction: interaction

Review auto-record creation-related lists

The following Related Lists are located at the bottom of the form. These fields are used to configure additional auto-create functionality:

  • Static Record Fields
  • Dynamic Record Fields
  • Record Lookup Fields
  • Dynamic Record Lookup Fields

Update Remote Support record fields

Record fields are used when mapping static data or Remote Support data to ServiceNow record fields during auto-creation of records. This step updates the database with all the available event types.

Browse to BeyondTrust Remote Support and click Update BeyondTrust Record Fields. This loads all the available Remote Support Record Fields into the database, so that field mappings can be achieved.

Set up auto-create field mappings

Browse to BeyondTrust Remote Support and click Appliances. Click the B Series Appliance you are configuring. Scroll down to the related list section. There are four related lists, each representing a type of field mapping. They are detailed below:

  • Static Record Fields: Maps a static, default value to a ServiceNow record field.
  • Dynamic Record Fields: Maps a Remote Support Session value to a ServiceNow record field.
  • Record Lookup Fields: Maps a static, default value to a ServiceNow record lookup field.
  • Dynamic Record Lookup Fields: Maps a Remote Support Session value to a ServiceNow record lookup field.

Set up static record fields

Use this type of mapping when you want to assign the same static value to the same ServiceNow text field or option list for every record created.

✅

Example

For every record that is auto-created, the customer wants the State field to be set to Resolved. The record field for State is selected from the menu and the value for Resolved is 6, so the following values are set:

  • Record Field = State (selected from the menu)
  • Default Value = 6

Record Field Label is arbitrary.

  • Record Field Label: an arbitrary value used to identify the mapping.
  • Record Field: The record field that is populated upon auto-creation.
  • Default Value: The static value that is populated in the selected record field.

Dynamic record fields

Use this type of mapping when you want to assign a field from the Remote Support session to the same ServiceNow text field or option list for every record created.

✅

Example

For every record that is auto-created, the customer wants the Short Description field to be set to the value contained in the Remote Support session's External Key field. The record field for Short Description is selected from the Record Field menu and the Remote Support External Key field is selected from the Remote Support Field menu, so the following values are set:

  • Record Field = Short Description (selected from the menu)
  • BeyondTrust Field = External Key (selected from the menu)

Field Label is arbitrary.

  • Record Field Label: An arbitrary value used to identify the mapping.
  • Record Field: The record field that is populated upon auto-creation.
  • BeyondTrust Field: The Remote Support session value that is populated in the selected record field.

Record lookup fields

Use this type of mapping when you want to assign the same static value to the same ServiceNow field, which requires a lookup, for every record created.

✅

Example

For every record that is auto-created, the customer wants the Assigned To field to be set to a specific user, whose username is bob.ross. The record field for Assigned To is selected from the Record Field menu. The Lookup Table Id is set to the table to search and the Lookup Field Id is set to the field in the lookup table to compare the static value with. Default Value is the static value with which to lookup the user, so the following values are set:

  • Record Field = Assigned To (picked from the chooser)
  • Lookup Table Id=sys_user
  • Lookup Field Id = user_name
  • Default Value = bob.ross

Field Label is arbitrary

  • Field Label: A value used to identify the mapping.
  • Record Field: The record field that is populated upon auto-creation.
  • Lookup Table Id: The ServiceNow table where the value for this record field is looked up.
  • Lookup Field Id: The field in the lookup table that is searched on when looking up the value for this record field.
  • Default Value: The static value that is used when looking up the value for this record field.

Dynamic record lookup fields

Use this type of mapping when you want to assign a field from the Remote Support session to the same ServiceNow field, which requires a lookup, for every record created.

✅

Example

For every record that is auto-created, the customer wants the Caller field to be set to a specific user, whose username we will get from the Remote Support session. The record field for Caller is picked from the Record Field chooser. The Lookup Table Id is set to the table to search and the Lookup Field Id is set to the field in the lookup table to compare the Remote Support value with. BeyondTrust Customer Username field is picked from the BeyondTrust Field chooser, so the following values are set:

  • Record Field = Caller (selected from the menu)
  • BeyondTrust Field = Customer Username (selected from the menu)
  • Lookup Table Id = sys_user
  • Lookup Field Id = user_name

Field Label is arbitrary

  • Field Label: A value used to identify the mapping.
  • Record Field: The record field that is populated upon auto-creation.
  • Lookup Table Id: The ServiceNow table where we lookup the value for this record field.
  • Lookup Field Id: The field in the lookup table that is searched on when looking up the value for this record field.
  • BeyondTrust Field:The Remote Support session value that is used when looking up the value for this record field.

Common lookup fields

The following information is provided to help you when creating lookup field mappings. A Lookup Field is populated by looking in another ServiceNow table to retrieve a value.

For example, the Caller field on an Record is a lookup field. The ServiceNow table that is used is named sys_user. We could lookup a user by querying on the user_name field with a value of john.doe. This would populate the Caller field with the sys_user record for John Doe.

Below are some common ServiceNow record lookup fields that you might encounter in an auto-create scenario.

Record FieldRecord Field NameTableCommon Query Fields
Callercaller_idsys_usernameuser_name
email
Opened Byopened_bysys_userx_bmgr_support_ent_bomgar_usernamenameuser_name
email
Assigned Toassigned_tosys_userx_bmgr_support_ent_bomgar_usernamenameuser_name
email
Assignment Groupassignment_groupsys_user_groupname
Configuration Itemcmdb_cicmdb_ciname
Locationlocationcmn_locationname

Test auto-create

You can test the record creation with a URL similar to https://support.example.com/api/start_session?issue_menu=1&customer.name=Bob&customer.company=BobCoInc&customer.details=Credentials&codeName=issue_4&session.custom.customer_username=b.smith&c2cjs=1

If using the outbound event approach, then after the representative joins the session, a new record appears when you refresh the record list in ServiceNow. Additionally, the ServiceNow Task Id is populated in the representative console after a few seconds with the sys_id of the newly created record.

If using the custom link approach, then after the representative clicks the Create Record custom link, a new record appears when you refresh the record list in ServiceNow. Additionally, the ServiceNow Task Id is populated in the representative console after a few seconds with the sys_id of the newly created record.

Use cases

Service desks and customer support organizations using ServiceNow can integrate with Remote Support to improve service levels, centralize support processes, and strengthen compliance. Uses cases that are addressed by the Remote Support and ServiceNow integration are listed below.

Generate session key

Technicians can generate a session key from within an incident and give the customer the key to initiate a support session.

The integration provides support for incidents, change requests, new call records, catalog requests, and interactions.

Once the session ends, a detailed report of the session is imported into ServiceNow and associated with the incident from which the session key was generated.

Import Remote Support session data into a ServiceNow record

Once the Remote Support session ends, ServiceNow is automatically updated with information gathered during the session, including:

  • Chat Transcript
  • File Transfer Information
  • Session Notes
  • Customer System Information
  • Representative Involved
  • Customers Involved
  • Teams Involved
  • Session Recordings
  • Customer and Representative Survey Results

Jump to configuration item

Technicians can leverage Remote Support Jump Technology to access a configuration item associated with an incident directly from the incident. Additionally, this same technology can be leveraged directly from within a configuration item, even if it is not associated with an incident.

Once the session ends, a detailed report of the session is imported into ServiceNow and associated with the incident and/or configuration item record from which the session key was generated.

Customer-initiated chat from ESS

Customers can open incidents to which they are assigned as the caller and request a support session with a technician by clicking Get Support Now.

This functionality provides customers with an expedient path to resolution while also giving the technician the necessary context to effectively assist the customer.

Sessions initiated using Remote Support's click-to-chat functionality can be elevated to full support sessions if the technician deems it necessary.

Customer initiated chat from service portal

Customers can request a support session with a representative from a ServiceNow Service Portal where the Remote Support Get Support Now widget has been added. This includes any context within an incident, like the Incident or Ticket form, or any context outside the scope of an incident, like the SP homepage.

This functionality allows customers an expedient path to resolution, while also providing the technician with the necessary context to effectively assist the customer.

Sessions initiated using Remote Support's click-to-chat functionality can be elevated to full support sessions if the technician deems it necessary.

Access ServiceNow records from the Representative Console

Using Remote Support's custom links ability, a representative can access the associated ServiceNow record directly from within the representative console. This saves time searching for the record in ServiceNow and provides the representative with any available issue details, history, or other context to help quickly resolve the issue.

Associate sessions with ServiceNow records manually

Whether a representative has created an incident for the current session or has found an existing session, sessions originating outside the scope of a ServiceNow record can be manually associated with the appropriate item. This allows session details to be added automatically to the incident when the session ends.

To make this association, the representative enters the numeric ID of the incident, change request, new call record, catalog request, or interaction into the External Key field while in session.

Technicians can use the human-readable record number from ServiceNow to easily make this association.

Create incidents automatically

For customers who have applicable processes, the integration can be configured to automatically create a ServiceNow incident based on Remote Support sessions, either when the representative joins the session, or manually via a Remote Support rep console's custom link.

This process can simplify workflows and reduce the number of clicks needed for support representatives.

Troubleshoot

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

ℹ️

Note

Troubleshooting 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. Commonly, 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 into 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.

ℹ️

Note

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. Commonly, 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 any errors 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.

ℹ️

Note

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, a few things 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 a 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.

ℹ️

Note

For more information, 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.

ℹ️

Note

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.

ℹ️

Note

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.

ℹ️

Note

For more information on this issue, 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.

ℹ️

Note

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.

ℹ️

Note

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.

ℹ️

Note

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.

ℹ️

Note

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

Updated about 2 months ago

©2003-2025 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.