This article applies to customers with a Tensor subscription plan.
Overview
The Application Installation and Configuration Guide will be used to assist with the preparation of the customer’s instance in order to enable the application components to function properly. This document contains a clear, step-by-step process for any configuration steps that are required after installing the certified application from the ServiceNow Store. Additionally, it clearly calls out any application dependencies that exist.
Application Dependencies
- List all plugins required:
Configuration Instructions
When configuring the TeamViewer application, please take into account the points below:
- Set the Admin token provided by TeamViewer in the Administration -> Properties module
- Set which TeamViewer Invite Options are available to supporters to create. One of the following options can be set:
- Both Remote and Pilot
- Remote Only
- Pilot Only
- Configure the Unattended Access Feature in the Administration -> Unattended Access Setup module
- Set the Admin Token, provided by TeamViewer
- After the above field has been entered, click on the Verify button to verify that you have the right license for the TeamViewer’s Unattended Access feature.
- If you have the right license, on the form you will receive a message that the Unattended Access Parameters are verified successful and this step is completed
- If you receive an error message, please verify your inputs on the form and try again. If you still receive error messages, please contact TeamViewer Support for assistance.
- Register Unattended Devices in the Administration -> Unattended Devices
- For each Device Registration record, you must:
- Make sure each Device to be registered is online and have TeamViewer Application running
- Set the Configuration Item associated to the device that is going to be allowed to have unattended access.
- Set the following fields, which can be found on the Device’s file located in its TeamViewer installation folder:
- TeamViewer ID, and put an “r” at the beginning of the field. For example: r1756067272
- TeamViewer GUID
- TeamViewer ROK
- Click on Enable Unattended Access to register device in TeamViewer
- If the registration is successful, the record’s status field will be updated to Registered
- Else, the record’s status field will be updated to Invalid Registration. Please review the TeamViewer fields and try again. For further assistance, please contact TeamViewer Support
- Configure Configuration item[cmdb_ci] field on the Task table: update its Attributes field to include x_tvgh_enterprise_initiate_unattended_session attribute in order for the Initiate Unattended Session Button can be used; see Section 8.3.6 for details
- Update the Application Registry [oauth_entity] record: TeamViewer Enterprise OAuth
- In the record, update the field Redirect URL by replacing <instance> with the name of the instance that the application is installed on and update the record.
External System Connection
TeamViewer application integration components:
- Integration components required:
- Steps to create a dedicated integration user:
- Go to https://login.teamviewer.com and click Sign Up to create a TeamViewer account that is needed to use the TeamViewer WebAPI. For the TeamViewer REACH API usage, the account created requires having a Tensor License.
Testing the configuration
There is no requirement to test the connection. If access to the TeamViewer Web API is not available, a relevant error message will be shown by the ServiceNow platform.
Demo Data
If any demo data is required as a part of your application installation, please outline the requirements here: -
Support and Troubleshooting
For any issues or questions on how to use the TeamViewer integration on ServiceNow, please use:
Administration and Configuration
Admin Token
Instructions
To be able to access the TeamViewer API for certain features like scheduled company-wide connection reports, an admin TeamViewer Script token needs to be configured. Below are the steps on how to create one and configure your TeamViewer instance accordingly.
Creating an Admin Token
In this description, it is assumed that the administrator has created a company profile on TeamViewer. For more information on how to setup a company profile and add users visit
- Go to https://login.teamviewer.com
- Go to ‘Profile’ on top right corner and select Edit Profile. Please note that you will need to have a Tensor TeamViewer license to be able to use this functionality.
- Go to Apps and select Create Script Token button.
- Setup permissions as shown below
- Click Save to generate the Script Token
Setting the Admin Token
Role required: admin
- Connect to ServiceNow with the required user and role(s)
- Go to module within the Application: Administration --> Properties
- Set the Admin Token for Attended Connection reporting and click Save as shown below:
TeamViewer Invite Options
Introductions
This chapter describes how to configure what types of TeamViewer invites are available to agents to create within ServiceNow. There are up to two invite types available for agents, which are the following:
- Remote Control Invite: This is the standard TeamViewer invite for Attended Session
- Pilot Invite: This is a remote assistance solution powered by augmented reality that enables agents to connect to your support requesters and see what their smartphone camera live streams to your computer or mobile device while allowing you to draw, add text, or tag real-world objects with 3D markers for reference. 📌Please note: this requires Pilot Subscription(s) for each agent that would like to use this invite option
TeamViewer Invite Options configuration
Role required: admin
- Connect to ServiceNow with the required user and role(s)
- Go to module within the Application: Administration --> Properties
- Set which TeamViewer Invite Options are available to agents as shown below:
Unattended Access Setup
Introduction
This chapter describes the step-by-step guide on how to setup the TeamViewer Unattended Access feature within your instance and how to register and unregister devices for unattended access, which means that a customer does not have to be present on the device when supporter begins a remote session. Please note for this feature, your TeamViewer account requires a Tensor License.
Unattended Access Configuration
Role required: admin
- Connect to ServiceNow with the required user and role(s)
- Go to module within the Application: Administration --> Unattended Access Setup in which you will see the following form:
- In the form, please enter the following:
- Admin Token: This is provided by TeamViewer upon the creation of an Admin Token (See – Creating an admin token).
- Click on the Verify button. When clicked, the application verifies the parameter in Step 3 and your TeamViewer License in your account. Once the account and parameters are verified successfully, you will see the following message at the bottom of the form:
- With the successful verification for Unattended Access, click on Save to save settings to your instance.
- If you do not get a successful verification, please review your input in Step 3 and Verify again. If the issue persists, please contact TeamViewer Support
Register Unattended Devices
Pre-Requisites:
- Complete Steps in Section Unattended Access Configuration with a successful verification for Unattended Access
- Each Device to be registered needs to be online and have TeamViewer application running.
Role Required: x_tvgh_enterprise.device_user or admin
Here are step-by-step instructions on how to register a device for Unattended Access. Also, depending how many devices you need to register, you may need create a bulk import of multiple devices with import sets in ServiceNow
- Go to module within the application: Administration --> Unattended Devices
- Create a new Device Record with the following field values:
- Configuration Item: Set the Configuration Item record associated with the device to be registered
- TeamViewer ID: set the TeamViewer ID which can be gathered from the device. Make sure that field starts with an “r”. For example: r1756067272
- TeamViewer GUID: GUID which can be gathered from the device
- TeamViewer ROK: Rollout Key which can be gathered from the device
- Click on the button Enable Unattended Access as shown here for example:
- If the Device is successfully registered, you will see the record’s Status filed updated to Registered, as shown here for example:
- If Device registration failed, the Status field will be updated to Invalid Registration Instead. Please review the field values and try again to register. If the issue persists, please contact TeamViewer Support.
- If you would like to enable multiple devices records for Unattended Access, you may do so in the list view of the Device record as shown here:
Unregister Unattended Devices
Pre-Requisites:
- Complete Steps in the Section Unattended Device Configuration with a successful verification for Unattended Access
- Each Device to be unregistered needs to be online and have the TeamViewer application running
Role Required: x_tvgh_enterprise.device_user or admin
Introduction: Here are step-by-step instructions on how to unregister a device for Unattended Access.
- Go to module within the application: Administration --> Unattended Devices
- Select the record you would like to disable Unattended Access and click on Disable Unattended Access, for example:
- If the Device is successfully unregistered, you will see the record’s Status filed updated to Not Registered, as shown here for example:
- If you would like to disable multiple devices for Unattended Access, you may do so in the list view of the Device record as shown here:
Bulk Import of Unattended Devices to be registered
As previously mentioned in Section Register Unattended Devices, you can do a bulk import of Device records if you have a lot of devices to register for Unattended Access. This section will provide a step-by-step guide on how to do this via import sets in ServiceNow.
Role Required: admin
- Go to module within the Application: Administrator --> Unattended Devices
- Once in the module, which shows a list of Devices [x_tvgh_enterprise_device], personalize the list columns to the following columns and order and click ok
- Click on Import by first clicking on any Column Options in the list as shown here for example
- After clicking import, you will be loaded to an Import Page. In this page, click on Create an Excel Template with the following option unchecked, marked red in the screenshot below:
- Download the file generated Excel file after completing Step 4 and then open the file. In the file, go to sheet “Page 1” and you will see a sheet with the following columns shown in this screenshot
- Use the excel file to insert the Devices that will be registered for Unattended access. Please note on the following columns as you insert:
- Configuration Item: Here insert the sys_id of the Configuration Item [cmdb_ci] associated with the Device to be registered
- The following columns values should be gathered on the Device per TeamViewer Instructions per Device Types:
- TeamViewer ID
- TeamViewer GUID
- TeamViewer ROK
- Here is an example of a completed Excel import sheet as a reference:
- After completing the Excel Sheet, upload the sheet to your instance by going back to the Import page (from Step 4) and click on Choose File, and set the following options on the form marked red on Screenshot below, and lastly click on Upload:
- After the file completed upload, click on Preview Imported Data:
- You will now be loaded to a page with a list of records to be imported. Please note you will receive some error messages that should be ignored. Click on Ignore Row Errors and Complete Import as shown in the screenshot below:
- You will be loaded back to the Unattended Devices with the list of records imported. From here, you can begin the bulk action to Register these devices to TeamViewer by selecting all devices and click on Enable Unattended Access as shown in the screenshot below:
- After all the Registrations are processed, please review the Status of each device by checking the Status column value on the list, for example:
- If the status of a device is Registered, that means that the device is ready for Unattended Access and set up is complete for the device(s). If the status is different for a device, please review the field values for errors and try again to register. If the issue persists, please contact TeamViewer Support for assistance.
Adding the Initiate Unattended Session button to the Task Table
In order to be able to start an Unattended Session on a Registered Device, changes need to be made on the Task [task] table in order to show the button that allows you to initiate the session. This section provides instructions on setting this up.
Role Required: admin
- On the Filter Navigator, type in task.config and press enter
- Go to the Dictionary Entries for the Task table and open the record with column name cmdb_ci:
- Within the record opened in Step 2, add x_tvgh_enterprise_initiate_unattended_session attribute as part of the Attributes field and update the record:
Application Registry for OAuth
Introduction
In this section, a step-by-step guide is provided to update the Application Registry [oauth_entity] provided by the application in order for the OAuth features can work when Supporters are creating and/or closing TeamViewer Service Cases in ServiceNow.
Update TeamViewer Enterprise OAuth Application Registry
Role Required: admin
- In ServiceNow, open module System OAuth -> Application Registry and open the record TeamViewer Enterprise OAuth as shown below:
- In the record, update the field Redirect URL by replacing <instance> with the name of the instance that the application is installed on and update the record:
Adding TeamViewer to task extended table
Introduction
This chapter described the step-by-step guide on how to add the TeamViewer Control and TeamViewer Connection History to a form in ServiceNow. This can only be applied to records on tables that are an extension from the task table. The application comes preconfigured with the TeamViewer Control (for Supporters) and TeamViewer Connection History on the Incident form (default view).
Prerequisites
The following prerequisites need to be met to be able to follow the steps in this guide:
- ServiceNow Store Application: TeamViewer Enterprise Integration for ServiceNow is installed, version 1.0 or above
Role: admin
Adding the Remote Control section, for Supporters, on a form
To add the TeamViewer Control to the form, follow the steps below. General documentation on how to add fields to a form can be found here:
- Open the form of the Task extended record type (e.g. problem, change request, requested item), where you want to add the TeamViewer Control
- On the form right-click on the form’s header
- From the menu choose Configure --> Form Layout
- From the ‘Section’ field, click on ‘New’ and a dialog for entering a name is shown. Enter a name (e.g. TeamViewer Remote Control) and click on OK. Documentation on how to create a form section can be found here:
- Add the TeamViewer Supporter Control to the newly created form section.
- Click on Save to apply the changes to the form.
- The TeamViewer Control should now be visible on the form within a form section.
Adding the Remote-Control section, for Customers, on a form
To add the TeamViewer Control, for customers, to the form, repeat the steps and instructions in the previous section (= Update TeamViewer Enterprise OAuth Application Registry), but with the following deviations:
- In the form, change the view to Self Service first as shown here:
- Then, configure the Form Layout of this view by adding a new section called TeamViewer Remote Control and add TeamViewer Customer Control. Afterward, click Save. Before clicking Save, the configuration should look like this:
- To confirm the changes in this section, go into an incident record in the Self-Service View and the TeamViewer Customer Control should be visible as shown here:
Adding the TeamViewer Connection Report to the Form
The next step is to add the TeamViewer Connection Report to the form, this related list shows the connection history for the open task record. More information on adding a related list to a form can be found here:
- Open the form of the Task extended record type (e.g. problem, change request, requested item), where you want to add the TeamViewer Connection Report
- Right-click on the form’s header a go to Configure --> Related Lists
- From the Available list, select the TeamViewer Connection Report and add it to the Selected list by clicking the Add arrow.
- Clicking on Save to apply the changes on the view.
- The TeamViewer Connection Report is now visible under the related lists at the bottom of the form.
Roles
The application permissions model is based on the following roles:
Connection History and Scheduled jobs
Introduction
The TeamViewer Enterprise Integration for ServiceNow application keeps a history of connections created from Sessions via ServiceNow for your account. This is stored in the Connection History table. The information in this table is periodically refreshed and augmented with the relevant information from the session, like the task reference.
Connection history refresh
The connection history is retrieved from TeamViewer via the API on four occasions:
- When a session is closed, the connection history for that session 1 is retrieved
- A scheduled job periodically (6 hours by default) retrieves the attended connection history
- A scheduled job periodically (6 hours by default) retrieves the unattended connection history
- A manual refresh of the connection history can be requested by a user with the proper role from the TeamViewer Connection Report.
Setting the scheduled job period
There are two scheduled jobs, one for Attended Access and the other for Unattended Access, that periodically retrieves the connection history is by default set to run every 6 hours. This interval can be updated by the ServiceNow System administrator by updating the repeat interval on the scheduled jobs.
Follow these steps to do this:
Role required: admin
- Go to the System Definition --> Scheduled Jobs
- Open the record for each of these jobs:
- TeamViewer - Retrieve Attended Access Report
- TeamViewer - Retrieve Unattended Access Report
- Run each job once, via the Execute Now button, to make sure the latest connection history is retrieved, and no records are missed due to a changed period. The scheduled jobs and the refresh action use the time period defined in the scheduled job to determine how far back (in time) connection history must be retrieved. So, if the last job ran 6 hours ago and you update the repeat interval to 3 hours, you miss 3 hours of connection history if you do not run the job once first.
- Update the repeat interval
- Click on Update
Online Service Cases
Within the TeamViewer Enterprise Integration for ServiceNow application, a supporter can see all the online service cases from one view, using the Online Service Cases Widget, which can be accessed via TeamViewer Enterprise Integration --> Online Service Cases.
Changing the columns
The columns shown in the Online Service Cases can be changed by the ServiceNow system administrators and impacts all users of the application. To change the columns, follow these steps to go into the widget instance options:
Role required: admin
- Change your application Settings --> Developer --> Application) to TeamViewer Enterprise Integration for ServiceNow
- Go to TeamViewer Enterprise Integration --> Online Service Cases
- Press and hold ctrl on your keyboard and right-click anywhere on the widget
- Click on Instance Options
- Add or remove any columns in the Fields list
- Click on Save at the bottom of the instance options dialog.
Change the refresh rate
The Online Service Cases Widget automatically refreshes the data as long as the page is kept open, by default the data is refreshed every 30s seconds. This can be changed by the ServiceNow system administrator.
Role required: admin
- Follow steps 1 -4 from the previous section
- Change the refresh interval to your preferred setting, the setting is in seconds
Configuring email templates
Introduction
The Share Session Code functionality on the TeamViewer Remote Control uses the standard Quick Message functionality from ServiceNow to send the session code per email to the customer. Administrators can define the templates for these quick messages.
Naming convention
Since we use the standard Quick Message functionality of ServiceNow, the Email window shows all the available Email templates in the ServiceNow instance, including email templates created for other applications. To distinguish the email templates for TeamViewer Integration, it is advised to use a clear naming convention for your Quick Messages, e.g.:
- TV_ShareSessionSimple
- TV_ShareSessionAdvance
- etc.
Creating and editing email templates
ServiceNow system administrators can create new quick message templates and edit existing templates. The email templates for the TeamViewer Integration for ServiceNow application can be accessed via the TeamViewer Integration application.
More information on creating an email template can be found in the ServiceNow documentation:
To edit or create an Email Template, follow these steps:
Role required: admin
- Change your application ( Settings --> Developer --> Application) to TeamViewer Enterprise Integration for ServiceNow
- Go to TeamViewer Enterprise Integration --> Email templates
- Click on an existing Email Template or click on New
- Fill in the form, you can use variables substitutions to use fields from the task record, e.g. ${caller_id}
- Click on Update (for an existing record) or Submit (for a new record)
Using the Integration
Introduction
Once the TeamViewer Enterprise Integration app has been properly installed and configured, it can be used to create service cases, via “Create Remote Control Invite” or “Create Pilot Invite”, and remotely access and control end users’ devices.
Creating TeamViewer Service Cases
The first time each user attempts to create a service case, he/she will be prompted to login with their TeamViewer credentials as shown below.
This will only need to happen once per user and his/her access-token will be stored in the ServiceNow platform until revoked by the user or the administrator from the TeamViewer Management Console.
After the user has logged in successfully, the service case will be created. An example is shown in the screenshot below:
Sharing Service Cases and establishing a connection
Share Session Code
Once the service case has been created, the supporter can easily share the session link with the end-user by clicking Share session code. That will open the email window where the supporter can select a pre-defined email template. Please be aware that multiple templates, also for other applications, might exist in your system and the TeamViewer email template is not pre-selected.
The end user's email address and name as well as the customer link and the subject/body text of the email can be automatically populated through the pre-configured templates. In the screenshot below an example is shown.
The supporter can then select ‘Start Session’ immediately and will wait in a virtual lobby until the end-user clicks the link after which point the remote-control session will be established. Otherwise, the supporter can wait until the end-user selects the link first (in which case he/she will appear online in the Active sessions screen) and then start the session.
SMS Pilot Invite
If a supporter creates a Service Case via Pilot Invite, the supporter can send a text message (SMS) to the end-user with the link to initiate a Pilot session. This can be done by clicking the “SMS pilot invite” after a Pilot invite has been created as shown below:
After the supporter clicks the above button, a pop-up window will show up with a pre-populated phone number gathered from the end user’s record (referenced in the Caller field of the incident/task) in ServiceNow as shown below:
The supporter must verify that the number is in the international format before clicking the Send button. After clicking send and the phone number is valid, the supporter will be notified, on top of the form, that an invite has been sent to the customer as shown below:
The supporter can then select ‘Start Session’ immediately and will wait in a virtual lobby until the end-user clicks the link after which point the remote-control session will be established. Otherwise, the supporter can wait until the end-user selects the link first (in which case he/she will appear online in the Active sessions screen) and then start the session.
📌Please note: In order for this feature to work properly, the supporter needs to have a TeamViewer Pilot subscription assigned to him/her.
Initiate TeamViewer Unattended Session
In any task-based records, like Incidents, that has a reference to a Configuration Item that is properly registered for Unattended Access (from Section 8.2.3), supporters can start an Unattended Session to that device (as long as the device is online and has TeamViewer app running) by clicking on the TeamViewer Icon located on the right side of the Configuration item field on a task form as shown here for example:
View Connection Reports
Attended Connection Report
In the TeamViewer Enterprise Integration application, you can see company-wide reports of Attended Connections by going into the module Attended Connection Report as shown here:
v
Furthermore, in every module (Incident, Problem, Change Request, Control Request) the admin has the ability to add a Related list object with the list of remote-control sessions used to solve the specific incident.
The list is refreshed either when a service case is closed or when the ‘Refresh’ button is pressed. Below is an example of the connection report.
Unattended Access Report
In the TeamViewer Enterprise Integration application, you are able to see company-wide reports of Unattended Connections by going into the module Unattended Connection Report as shown here:
OAuth Token Management
Role Required: Admin
When Supporters logs into their TeamViewer Account in ServiceNow when creating a Service Case, ServiceNow stores the User’s Access Token and Refresh Token in the ServiceNow’s OAuth Credentials [oauth_credential] table. You can find the list of tokens under module SystemOAuth --> Manage Tokens:
In this list you can review the Tokens stored for this application under the name TeamViewer Enterprise OAuth:
To see what user tokens and type of token are stored in the above list, you can personalize the columns by pressing the gear button located on the left side of the page, and add the Columns User and Type as shown below:
From here, you can revoke access to TeamViewer by selecting the User’s Refresh and Access Token and delete with the Delete UI Action button. For example:
Upgrading from TeamViewer Remote Support Integration
Introduction
This section will go over the process of upgrading from TeamViewer Remote Support Integration Application installed in your instance to TeamViewer Enterprise Integration as these two applications are in different scopes and store data in different tables. This guide will instruct how to import the data into TeamViewer Enterprise and how to properly install the application
Upgrade Guide
Role Required: Admin
- Backup Data from TeamViewer Remote Support Integration
- Backup Task [task] Records with A Session Reference
- In the filter navigator, type in task.list and press enter:
- In the list, personalize your columns with the gear icon to add the Session field to the list view. Then filter the list with Session is not empty as shown here:
- If the list is not empty, export this filtered list as an Excel, and download the file, as shown here:
- Backup Sessions [x_tvgh_teamviewer_sessions] records
- In the filter navigator, type in x_tvgh_teamviewer_sessions.list and press enter:
- In the list, personalize your columns with the gear icon to add all available fields to the list view as shown here and click OK:
- Export this list as an Excel, similarly to step 1.iii , and download the file.
- Backup TeamViewer Connection Report [x_tvgh_teamviewer_session_history]
- In the filter navigator, type in x_tvgh_teamviewer_session_history.list and press enter:
- In the list, personalize your columns with the gear icon to add all available fields to the list view as shown here and click OK:
- Export this list as an Excel, similarly to step 1.3 , and download the file.
- Uninstall TeamViewer Remote Support Integration. For details on how to uninstall the application can be found here from ServiceNow:
- Install TeamViewer Enterprise Integration for ServiceNow. For details on how to install the application can be found here from ServiceNow:
- Load backup data and Import Data
In this part of the guide, it will use the Import Set feature in ServiceNow to load the data from the original application. ServiceNow Documentation on Import Sets can be found here:
- Import Session Data from the backup Excel file created in Step 1.b.iii
- Go to module System Import Sets --> Load Data and create a new Import Set table called TeamViewer Session Backup and upload the file from Step 1.2.3. Afterwards click on Submit, as shown here:
- After the file is uploaded, click on Create transform map as shown here:
- Create the transform map in with the following configuration and Save on the record:
- Then on the form, click on Auto Map Matching Fields, in Related Links, to match the fields properly in the import process:
- Review the generated Field Maps and make the Service Case field’s Coalesce to true, as shown here:
- Afterwards, click on Transform and select the Map TeamViewer Sessions to Enterprise and click on Transform:
- Review your results. If successful, the import is complete as shown here:
- Update Task Records based on the backup Excel file created in Step 1.1.3
- Go to module System Import Sets --> Load Data and create a new Import Set table called TeamViewer Task Backup and upload the file from Step 1.1.3. Afterward click on Submit, as shown here:
- After file is uploaded, click on Create transform map, as shown here:
- Create the transform map in with the following configuration and Save on the record:
- Then on the form, click on Auto Map Matching Fields, in Related Links, to match the fields properly in the import process
- When the page reloads, review the generated Field Maps in the Related List. In this list, make sure there are 2 Field Maps , For Session and Number, and set Coalesce to true to Number. If there are additional Field Maps, delete them. In the end, the list should look like this (take careful look the red highlight):
- Afterwards, click on Transform and select the Map TeamViewer Task to Task and click on Transform:
- Review your results. If successful, the import is complete as shown here
📌Please note: No new records shall be created in this import; only updates the Task records that had a reference to a Session with the appropriate reference in TeamViewer Enterprise
- Import TeamViewer Connection Report Data from the backup Excel File created in Step 1.3.3
- Go to module System Import Sets -> Load Data and create a new Import Set table called TeamViewer Connection Report Backup and upload the file from Step 1.3.3. Afterwards click on Submit, as shown here:
- After file is uploaded, click on Create transform map, as shown here:
- Then on the form, click on Auto Map Matching Fields, in Related Links, to match the fields properly in the import process
- When the page reloads, review the generated Field Maps in the Related List. In this list, set Coalesce to true to Connection ID. In the end, the list should look like this (take careful look the red highlight):
- Afterwards, click on Transform and select the Map TeamViewer Connection Report to Enterprise and click on Transform
- Review your results. If successful, the import is complete as shown here:
- Go to Module System Definition -->Fix Scripts, open and run the Fix Script TV - Import Attended Session :
- The import is now complete for Attended Sessions. You can review the import data in module TeamViewer Enterprise Integration --> Attended Connection Report :
