ScreenAgent for Windows

ScreenAgent NICE ScreenAgent is a service that runs on agent desktops that require screen recording. is available if you have CXone Recording Advanced and a screen recording license.

Install ScreenAgent on computers to record or monitor activity on an agent's screen during an interaction. ScreenAgent runs in the background and automatically records according to the recording policies (see CXone Recording). Supervisors and evaluators can also monitor an agent’s activity during an interaction (see Manage Agents).

You can install ScreenAgent on agents' computers, or in a virtual desktop infrastructure (VDI) environment. Supported VDIs include:

• VMware Horizon

• Citrix Virtual Apps (formerly XenApp)

• Citrix Virtual Desktops (formerly XenDesktop).

• Multi-session environments

• Non-persistent VDI environments

VMware Horizon doesn’t require any special configuration. For other VDI environments, see prerequisites.

The following environments do not support screen recording:

• Terminal-server type VDI environments

You can Check ScreenAgent Connectivity before or after installation.

 

For more information, see FAQs for ScreenAgent.

For a list of features added to previous ScreenAgent releases, see ScreenAgent: Cumulative Release Notes.

Prerequisites

Before installing ScreenAgent, make sure to:

1. Check the Port, Domain, Voice, and IP Address Requirements. Keep in mind, ScreenAgent doesn't record if your firewall generates self-signed certificates or strips request headers from HTTPS packets.

2. If your site uses VDIs, make sure:

   • You're using ScreenAgent V2.1 and up.

   • In a non-persistent VDI environment:

     • Use ScreenAgent version 3.0 or higher.

     • Install ScreenAgent on the base image of the VDI.

     • Take a snapshot of the base image

     • Distribute to all VDI instances.

   • For Citrix virtual apps mode:

     • Enable a Virtual IP Loopback policy. Add ScreenAgent.exe and Chrome.exe to the Virtual IP virtual loopback programs list. Keep in mind that each program must be listed on a separate line.

     • Install ScreenAgent on the Citrix Virtual Apps server.

   • For multi-session environments:

     • Use ScreenAgent version 3.0 or higher.

     • Configure ScreenAgent to work in OS Login mode.

     • Users need to log in to ScreenAgent with OS Login credentials.

   • VMware Horizon and Citrix virtual desktop mode don't require any special configuration.

   If you are working in a multi-session or non-persistent VDI environments, and you encounter issues, contact NICE support to check whether your specific environment is supported.

3. Check the agent's computer configuration.

   Agent computer requirements

   • Microsoft .NET 4 or higher installed on the agent's computer.

   • One of the softphone solutions for agents:

     • Agent for Salesforce softphone installed on the same computer as ScreenAgent.

     • MAX softphone.

   • Relevant computer specifications in Platform Requirements.

     Keep in mind, if the computer configuration is set to full HD or 4K and the CPU usage is high, then a more powerful CPU (such as i5) may be required.

   • Port 31322 open. This port is only used for internal communication between ScreenAgent and MAX/Agent for Salesforce softphone on the agent's computer.

4. Make sure the user who is installing ScreenAgent (for example, the admin) has Admin privileges on the agent's computer.

5. Make sure the user who is installing ScreenAgent (for example, the admin) has these CXone permissions:

   • Can access support downloads: On, this allows you to access the Supports - Downloads page.

   • Access Key: Create, this is to manage access keys for your organization.

6. Generate an access key for ScreenAgent.

   You can use the same access key for installing ScreenAgent on all agents' computers in your tenant.

   The access key receives all of the permissions of the CXone user who generates it. If this user is an administrator, then anyone with the access key would have administrator privileges. So for security reasons, first create a CXone user and role for ScreenAgent, and then generate the key with the ScreenAgent user.

   1. Create a role for the ScreenAgent service:

      1. Click the app selector and select Admin.

      2. Go to Security > Roles and Permissions.

      3. Click New Role.

      4. Give a name for the role, such as ScreenAgent access key.

      5. Remove all permissions for the role.

      6. Save & Activate the profile.

   2. Create an employee for the ScreenAgent service:

      1. Click the app selector and select Admin.

      2. Click Employees.

      3. Click New Employee.

      4. Give a name for the employee, such as ScreenAgent.

      5. From the Primary Role drop-down list, select the ScreenAgent access key role you just created.

      6. On the General tab, clear all the attributes.

      7. Create the ScreenAgent employee. You can generate access keys only after you create the account.

   3. Open the ScreenAgent employee again and go to the Security tab. Click Add access key to generate an access key.

   4. Copy both the Access Key ID and Secret Access Key and save them somewhere safe. If you don't copy the Secret Access Key or if you lose it, you'll need to create a new one. Use this access key ID and secret access key when installing ScreenAgent on all agents' computers.

   5. Activate the ScreenAgent employee account by clicking the Activate Account button in the activation email.

7. Download the ScreenAgent MSI:

   1. Go to CXone, and log in as a user with the Can access support downloads permission.

   2. Click your Username and select Support and Downloads.

   3. Download the required MSI. Note where you download the MSI to, you'll need the file location later.

8. ScreenAgent supports five proxy authentication methods for screen recording—Basic, Digest, Kerberos, NTLM, and Negotiate. When using the proxy authentication method:

   • Make sure to set the proxy at the operating system level in the Proxy settings.

   • For Basic and Digest authentication method, you must set credentials in Windows Credential Manager.

   • There's no change in installation. However, if you want to use proxy for ScreenAgent without changing proxy at the operating system, you can use the direct proxy in the ScreenAgent installation.

   • Keep in mind, these authentication methods are only for screen recording and not for screen monitoring.

Install ScreenAgent for Windows

You can install ScreenAgent using a deployment tool or install manually on each agent's computer.

If you're using a deployment tool, configure the installation to one of the following:

• Run with user's rights (user mode/user context)—You don't have to restart the agent's computer.

• Run with administrative rights—You must restart all agents' computers.

You can specify installation location:

• By default, ScreenAgent is installed on the C drive under the \NICE-InContact\ScreenAgent folder. You can specify a different installation path in the installation command.

• When upgrading to a later version, you can define a different installation path. The previous version is removed and the later version is installed in the specified location.

• Reinstalling the same ScreenAgent version replaces the existing installation in the same location. To change the installation path, uninstall the existing instance and specify the required location on reinstallation.

Some ScreenAgent parameters can be changed after installation. See Change ScreenAgent Configuration. To update other installation parameters, reinstall the ScreenAgent client.

To upgrade ScreenAgent to a later version, install the ScreenAgent client. You do not need to uninstall the previous version.

When you upgrade or reinstall ScreenAgent, the installation automatically uses the existing configuration unless you specify different parameter settings. See Reinstall or upgrade with the current configuration. When you uninstall ScreenAgent, the configuration is not saved and you need to specify installation parameters when you upgrade or reinstall.

Upgrade or reinstall ScreenAgent when agents aren't being recorded. If an agent is on a call during the installation, screen recording stops for that call. After the installation completes, calls will record according to the recording policies and Studio scripts.

To install ScreenAgent:

1. Make sure all prerequisites are in place.

2. Open the command prompt as Administrator. In the command line, navigate to where you downloaded the MSI and enter the installation command with the relevant parameters:

   Step-by-step instructions

   1. Go to the folder where you downloaded the MSI, and copy the path to the folder. This is typically the %UserProfile%\downloads folder.

   2. Run the command prompt as Administrator:

      1. In Windows, click the Windows button and type cmd.

      2. Right-click the Command Prompt tile and click Run as administrator.

   3. Type cd/ and press Enter.

   4. Type cd and paste your file location, then press Enter.

      For example, cd %UserProfile%\downloads.

   5. Copy and paste the command into the Command Prompt, and edit the parameters listed in the table.

      • If you don't have a web proxy or the proxy is defined at OS level, use this command:

        msiexec /i ScreenAgent-<32|64>bit-<MSI version>.msi INSTALL_PATH=<optional: installation path> ACCESS_KEY_ID=<access key ID> ACCESS_KEY_SECRET=<secret access key> REGION_TYPE=<subdomain (first 3 characters) of the CXone URL> RESOLVE_USER=<optional: auto|oslogin> FRAME_PER_SECOND=<optional: 1, 2, 3, 4, or 5> RESOLUTION_LEVEL=<optional: null, low, medium, or high> LOAD_CERTIFICATES=<optional: true|false> /log install.log /quiet

      • If you are using proxy authentication, and the proxy is not defined at OS level, use this command:

        msiexec /i ScreenAgent-<32|64>bit-<MSI version>.msi INSTALL_PATH=<optional: installation path> ACCESS_KEY_ID=<access key ID> ACCESS_KEY_SECRET=<the secret access key> REGION_TYPE=<subdomain (first 3 characters) of the CXone URL> WEB_PROXY=<only if using a proxy server to connect to the internet> RESOLVE_USER=<optional: auto|oslogin> FRAME_PER_SECOND=<optional: 1, 2, 3, 4, or 5> RESOLUTION_LEVEL=<optional: null, low, medium, or high> LOAD_CERTIFICATES=<optional: true|false> /log install.log /quiet

      Example installation command (for no web proxy or when proxy is defined at the OS level):

      msiexec /i ScreenAgent-64bit-2.2.18.msi INSTALL_PATH=d:\newdir ACCESS_KEY_ID=ABCDEF12345==== ACCESS_KEY_SECRET=12345ABCDEF REGION_TYPE=na1 RESOLVE_USER=oslogin FRAME_PER_SECOND=5 RESOLUTION_LEVEL=high  LOAD_CERTIFICATES=true /log install.log /quiet

   Reinstall or upgrade with the current configuration

   Use this command:

   msiexec /i ScreenAgent-<32|64>bit-<MSI version>.msi KEEP_CURRENT_CONFIG= true

   KEEP_CURRENT_CONFIG= true is optional since the default value for this parameter is true.

   • If all configurations were set in the previous installation, ScreenAgent is installed with all the existing configurations.

   • If some configurations were missing or not set in the previous installation, ScreenAgent is installed with the existing configurations and default values for missing parameters.

   • The installation path is not saved after installation; if it is not provided in the installation command, ScreenAgent is installed in the default location even when KEEP_CURRENT_CONFIG= true.

   To keep some parameter settings and change others, use the command above and add other parameters as required. For example, to change only the frame per second and resolution level, use the following (KEEP_CURRENT_CONFIG=true is optional):

   msiexec /i ScreenAgent-64bit-2.2.18.msi KEEP_CURRENT_CONFIG=true FRAME_PER_SECOND=5 RESOLUTION_LEVEL=high

   Installation command parameters
   

   Parameter	Description	Example
   msiexec /i ScreenAgent-32bit-<MSI version>.msi	32bit or 64bit If you’re installing on a computer with: 32-bit Windows installed, enter 32bit 64-bit Windows installed, enter 64bit MSI version Enter the MSI version of the installation file you downloaded from the Support and Downloads page. For example, 2.2.18.	msiexec /i ScreenAgent-64bit-2.2.18.msi   msiexec /i ScreenAgent-32bit-2.2.18.msi
   KEEP_CURRENT_CONFIG	(Optional) By default, the installation uses the current configuration when you reinstall or upgrade ScreenAgent. See Reinstall or upgrade with the current configuration. When set to false, the ScreenAgent installation does not use the existing configuration. The installation uses all specified parameters and default values for parameters with no configuration. The default value is true. For a clean installation, default values are used for parameters with no configuration.	KEEP_CURRENT_CONFIG=true
   INSTALL_PATH	(Optional) You can specify the installation path. The installation files will be saved in the \NICE-InContact\ScreenAgent folder under the specified installation path. When you do not add this parameter, ScreenAgent installs with the default installation path on drive C, even when KEEP_CURRENT_CONFIG= true.	INSTALL_PATH=d:\newdir
   ACCESS_KEY_ID	Paste the access key ID created in the Employee account. To generate an access key, see Generate an access key for ScreenAgent.	ACCESS_KEY_ID=ABCDEF12345====
   ACCESS_KEY_SECRET	Paste the secret access key created in the Employee account	ACCESS_KEY_SECRET=12345ABCDEF
   REGION_TYPE	Enter the subdomain (first 3 characters) of your CXone URL (for example: na1, na2, au1, eu1)	REGION_TYPE=na1
   WEB_PROXY	Only include this parameter if you’re using a proxy server to connect to the internet. Keep in mind: Host can be hostname or IP Use http or https according to your proxy settings Use username and password of the server if it’s set in your proxy settings For example: http://server_username:server_password@host:port https://server_username:server_password@host:port https://host:port When you are using a proxy URL that works with a proxy pac file, add the prefix pac+ in front of the proxy URL, for example, if the proxy URL is https://<proxy server>.pac, use: WEB_PROXY=pac+https://<proxy server>.pac	WEB_PROXY=http://admin:pwd@168.63.76.32:3128     WEB_PROXY=https://proxyserver:8088
   RESOLVE_USER	(Optional) Configure RESOLVE_USER=oslogin to use the agent's OS Login. In this mode, ScreenAgent connects to the server with the agent's OS Login information, and can work on advanced configurations, such as, CXone Open, multi-session environments, and more. When using OS Login, ScreenAgent does not use port 31322. If you do not add this parameter, ScreenAgent installs with the default value, auto, and relies on the CXone clients (MAX, CXone Agent, and so on) to connect to the server. In this mode, ScreenAgent uses port 31322 to connect to the CXone client. The agent's OS Login is defined in the General tab of the Employee setup in the format Domain\Username.	RESOLVE_USER=oslogin
   FRAME_PER_SECOND	(Optional) You can set the number of recorded frames per second for the output MP4 file. Allowed values are 1, 2, 3, 4, or 5. A higher number creates a higher quality recording but uses more CPU and memory (RAM). If you do not add this parameter, ScreenAgent installs with the default frame per second value, 5. You can change this configuration after installation.	FRAME_PER_SECOND=3
   RESOLUTION_LEVEL	(Optional) You can reduce the resolution of the recorded MP4 file to optimize RAM and CPU consumption. Allowed values are null, low, medium, or high (case insensitive). Null is the current screen resolution. Low reduces the recorded resolution the most, by a factor of 4. This setting is recommended only for 4K screens. Medium reduces the recorded resolution by a factor of 2. High reduces the recorded resolution the least, by a factor of 1.5. For example, if the current screen resolution is 1920 x 1080: Null keeps the recorded resolution at 1920 x 1080. Low reduces the recorded resolution to 480 x 270. Medium reduces the recorded resolution to 960 x 540. High reduces the recorded resolution to 1280 x 720. If you do not add this parameter, ScreenAgent installs with the default resolution setting, null. You can change this configuration after installation.	RESOLUTION_LEVEL=low
   LOAD_CERTIFICATES	(Optional) Set this parameter to false if ScreenAgent should not access and load self-signed certificates from the Windows certificates store. Allowed values are true or false. If you do not add this parameter, ScreenAgent accesses self-signed certificates from the Windows certificates store. You can change this configuration after installation.	LOAD_CERTIFICATES=false
   /log install.log	Prints the installation results in the log file.	/log install.log
   /quiet	(Optional) Include if you want to suppress popups during installation. You’ll be able to view the installation results in the log file.	/quiet

3. Verify installation success from the log file. The install.log file is in the folder you installed the MSI from, this is typically the %UserProfile%\downloads folder.

   • Verify that the installer has admin privileges.

   • If the agent's computer doesn't have Microsoft .NET Framework 4.0 or higher, then install it.

4. Make sure the agent has the attribute Can be Recorded (Screen) (in CXone, go to Admin > Employees, and then click on the agent).

5. Record a call and check the ScreenAgent log file. The ScreenAgent.log file is in the %appdata%\Roaming\ScreenAgent folder.

   Your ScreenAgent logs are also automatically uploaded to the cloud where the NICE CXone support team can access them, if needed.

   If there are any errors, see Troubleshoot Recordings.

Set up Screen Recording in Agent Application Administration

After installation, if required, you can set up screen recording in the CXone Agent application on the following platforms:

• Chromium browser

• Microsoft Dynamics

• ServiceNow

• ZenDesk

Change ScreenAgent Configuration

After installation, you can change some ScreenAgent configurations:

1. Open the configFile.ini file in the ScreenAgent install folder, typically under C:\Program Files\NICE-InContact\ScreenAgent.

2. Edit parameter values:

   • Change the framePerSecond value under the [recordingParameters] section. By default, this value is 5.

     Allowed values are 1, 2, 3, 4, or 5. A higher number creates a higher quality recording but uses more CPU and memory (RAM).

   • Change the resolutionLevel value under the [recordingParameters] section. By default this value is null.

     Allowed values are null, low, medium, or high (case insensitive).

     • Null is the current screen resolution.

     • Low reduces the recorded resolution the most, by a factor of 4. This setting is recommended only for 4K screens.

     • Medium reduces the recorded resolution by a factor of 2.

     • High reduces the recorded resolution the least, by a factor of 1.5.

     For example, if the current screen resolution is 1920 x 1080:

     • Null keeps the recorded resolution at 1920 x 1080.

     • Low reduces the recorded resolution to 480 x 270.

     • Medium reduces the recorded resolution to 960 x 540.

     • High reduces the recorded resolution to 1280 x 720.

     To reset to the screen's resolution, change the resolutionLevel value to null.

   • Change the loadCertificates value under the [others] section. By default, this value is true.

     Allowed values are true or false.

3. Save the configFile.ini file.

4. To apply changes, restart the ScreenAgent application:

   1. In the Windows Task Manager, end the current ScreenAgentWatchDog.exe task and then end the ScreenAgent.exe processes.

   2. From the ScreenAgent install folder, run ScreenAgentWatchdog.exe.

Check ScreenAgent Connectivity

You can test network access before or after installation to ensure that ScreenAgent will work correctly. It is recommended to use this tool when an agent’s network configuration has changed or is different from the regular configuration. You do not need to run the tool for every agent.

1. Download the Connectivity Tool EXE file:

   1. Go to CXone, and log in as a user with the Can access support downloads permission.

   2. Click your Username and select Support and Downloads.

   3. Download the required EXE file. Note where you download the EXE file to, you'll need the file location later.

2. Run the Connectivity Tool.

   1. Run the command prompt as Administrator.

   2. Copy and paste the command into the Command Prompt, and edit the parameters listed in the table.

      <path to exe file> ACCESS_KEY_ID=<access key ID> ACCESS_KEY_SECRET=<secret access key> REGION_TYPE=<subdomain (first 3 characters) of the CXone URL> WEB_PROXY=<optional: URL of proxy server>

      Connectivity tool command parameters

      Parameter	Description	Example
      path to exe file	File location of the downloaded EXE file.	C:%UserProfile%\downloads
      ACCESS_KEY_ID	Paste the access key ID created in the Employee account. To generate an access key, see Generate an access key for ScreenAgent.	ACCESS_KEY_ID=ABCDEF12345====
      ACCESS_KEY_SECRET	Paste the secret access key created in the Employee account	ACCESS_KEY_SECRET=12345ABCDEF
      REGION_TYPE	Enter the subdomain (first 3 characters) of your CXone URL (for example: na1, na2, au1, eu1)	REGION_TYPE=na1
      WEB_PROXY	Only include this parameter if you’re using a proxy server to connect to the internet. Host can be hostname or IP Use http or https according to your proxy settings Use username and password of the server if it’s set in your proxy settings	WEB_PROXY=http://admin:pwd@168.63.76.32:3128 WEB_PROXY=https://proxyserver:8088

   Example command:

   C:%UserProfile%\downloads ACCESS_KEY_ID=ABCDEF12345==== ACCESS_KEY_SECRET=12345ABCDEF REGION_TYPE=na1 WEB_PROXY=https://proxyserver:8088

3. The connectivity tool starts to run the tests. After each test runs, a success or fail notification is displayed. If a test fails, the reason for failure is displayed. At the end of the run a summary displays whether each test passed, failed, or did not need to run (N/A). For example, if ScreenAgent was not running in the background when the connectivity tool started, the tests to close ScreenAgent and restart it do not need to run.

   View image

   

   After completing the tests, the connectivity tool creates a log file (SA_Connectivity_tool_log_<runUniqueUUID>) in the same folder as the connectivity tool installation file. The log file includes all the information that was displayed at the command prompt.