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/api/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:

ℹ️

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

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

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.

ℹ️

Note

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

Updated 5 days 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.