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.

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

• VMware Horizon

• Citrix Virtual Desktops (formerly XenDesktop).

• Citrix Virtual Apps (formerly XenApp)

• Non-persistent VDI environments

• Multi-session environments

• Terminal-server type VDI environments

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

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

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

   • In a non-persistent VDI environment:

     • Use ScreenAgent version 3.0.22 or higher.

     • Install ScreenAgent on the base image of the VDI.

     • Take a snapshot of the base image

     • Distribute to all VDI instances.

   • For multi-session environments and terminal-server type VDI environments:

     • Use ScreenAgent version 3.0.22 or higher.

     • Configure ScreenAgent to work in OS Login mode.

       The OS Login value for each employee profile must be unique. The OS Login value cannot be used for multiple employee profiles, even if some of the duplicate employee profiles are inactive. If multiple employee profiles have the same OS Login value, ScreenAgent will not run for any agent using that OS Login value.

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

   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.

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

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:

     • CXone Agent.

     • Salesforce Agent 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/CXone Agent/Salesforce Agent softphone on the agent's computer. Not required when using OS Login.

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, except Access Key and My Access Key.

      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> STATISTICS=<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> STATISTICS=<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-3.0.37.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 STATISTICS=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, 3.0.22.	msiexec /i ScreenAgent-64bit-3.0.22.msi   msiexec /i ScreenAgent-32bit-3.0.22.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
   STATISTICS	(Optional) By default, this value is set to true and allows the ScreenAgent to collect data on the user machines (RAM, CPU). If you do not want ScreenAgent to collect data, it is possible to change this value to false. Allowed values are true and false. You can change this configuration after installation.	STATISTICS=true
   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 Multi-ACD (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. If you do not add this parameter, ScreenAgent installs with the default value, 5 frames per second. Allowed values are 1, 2, 3, 4, or 5. Lowering the number of frames per second reduces the file size, bandwidth, CPU and RAM. You can change this configuration after installation.	FRAME_PER_SECOND=3
   RESOLUTION_LEVEL	(Optional) You can set the resolution of the recorded MP4 file to optimize RAM and CPU consumption. If you do not add this parameter, ScreenAgent installs with the default resolution setting, null, the current screen resolution. Allowed values are null, low, medium, or high (case insensitive). Lowering the resolution reduces the file size, CPU, and RAM. 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.

   The config file, configFile.ini, is automatically hidden after installation. To view and open the file, enable Hidden items in the Windows File Explorer.

4. Make sure the agent has the Can be Recorded (Screen) attribute (in CXone, go to Admin > Employees, and then click on the agent). This attribute is necessary for enabling screen recording, screen monitoring, or both.

5. Record a call and check the ScreenAgent log file. The ScreenAgent.log file is located at: %appdata%\ScreenAgent\logs\ScreenAgent.log.

   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.

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.

     Lowering the number of frames per second reduces the file size, CPU, and RAM.

     Frames Per Second	Reduction in Frames	Impact on File Size/Bandwidth, CPU, & RAM (Estimated)
     5	Default (maximum)	None
     4	20% less	~15% reduction
     3	40% less	~30% reduction
     2	60% less	~45% reduction
     1	80% less	~60% reduction

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

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

     Lowering the resolution reduces the file size, CPU, and RAM.

     Resolution Level	Reduction in RESOLUTION	Impact on File Size/Bandwidth, CPU & RAM (Estimated)
     Null	Default (current screen resolution)	None
     High	Screen resolution / 1.5	~20% reduction
     Medium	Screen resolution / 2	~40% reduction
     Low	Screen resolution / 4	~60% reduction (recommended only for 4K screens)

     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

Use the ScreenAgent Connectivity Check tool run a sequence of tests to check network access and ensure that ScreenAgent will work correctly.

• You can use the tool before or after installing ScreenAgent.

• You can download the latest version of the Connectivity Check tool from the Downloads page.

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

• You can run the Connectivity Check tool multiple times using the same command.

• After each test runs, a success or fail notification is displayed. At the end of the run a summary displays the status of each test.

• After completing the tests, the Connectivity Check tool creates a log file.

• The Connectivity Check tool does not currently include tests to check networking for real-time screen monitoring.

1. Download the Connectivity Check 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 Check 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 check 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 check tool started, the tests to close ScreenAgent and restart it do not need to run.

   View image

   

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

Connectivity Tests