Desktop Agent Deployment

To record a user’s computer activity, the QMS Desktop Agent service must be installed on the computer on which the user is working. This service is responsible for monitoring user logins (and logouts) and recording the activity on the user’s computer screen. The Desktop Agent may be installed locally on the agent’s computer using the Desktop Agent Installer. Alternatively, it is possible to deploy the Desktop Agent to remote agent PCs using the Desktop Agent Deployment tool. This section covers installation and usage of the Desktop Agent Deployment tool as well as direct installation of the Desktop Agent service to the targeted PCs.

Target Host Requirements

Desktop Agent requirements include the following.

.NET 4.8 (Full Installation)
Windows Firewall Settings – make an exception in the firewall for TCP port 8426.
Windows Firewall (Alternatively, turn off and disable Windows Firewall service).
Add Microsoft Windows Desktop Experience. Refer to Server Running the Call Recording section in the Quality Management Suite Installation Guide.

Remote Desktop Session Host Configuration must be set to 32 bits per pixel.

In the Connections Pane, select RDP-Tcp session, right-mouse click, Properties
Select the Client Settings Tab
Change the "Color Depth" setting from 16 bits per pixel to 32 bits per pixel.
<OK>
Logout then remotely login again and test Screen Recording.

To support remote installation using the deployment tool, host computers to which the Desktop Agent deploys must have the following:

The Remote Registry service must be running. It is manual by default so it must be changed to automatic and started.

Installing the Desktop Agent Deployment Tool

The Desktop Agent Deployment Tool Installer is typically bundled with the Desktop Agent Installer and the Screen Recording Monitor Installer, and is distributed in a zip file. For example, the 4.1 versions of these installers were distributed in a file called CallRex_4_1_0_9554_Computer_Recording.zip.

There are two methods that you can perform in order to install the Desktop Agent Deployment Tool. You can perform a remote installation or a local installation. If you would like to perform a local installation see Installing the Desktop Agent Service Locally

Reviewing Screen Recordings - Requirements

Screen recordings can be reviewed with the QMS Client which plays them back using the .WEBM format.

Installing the Desktop Agent Service Remotely

To install the Desktop Agent Deployment Tool, complete the following steps.

Unzip your version of the distribution file on the Primary Quality Management Server.

Where multiple Data Collectors (DCs) are employed, depending on your network topology it may be advantageous to install the Desktop Agent Deployment Tool on each of the DC servers.

Using Windows Explorer, navigate to the unzipped Installers\Desktop Agent Deployment Tool and run the DesktopAgentDeploymentTool.msi program to startup the setup wizard. The Welcome page displays.
Click Next. The End-User License Agreement page displays.
Read and click the I accept the terms in the License Agreement checkbox and then click Next. The Configure Call Recording Server page displays.
Enter the PC Name or the IP address of the server hosting the Data Service and then click Next. The Ready to Install page displays.
Click Install to complete the installation. The Installation Complete page displays when the installer finishes.
Click Finish to close the installer. The deployment tool should now be installed. The next section explains how to use the deployment tool.

Operating the Desktop Agent Deployment Tool

The Desktop Agent Deployment Tool may be used to view the currently deployed Desktop Agents and to perform new deployments.

Desktop Agents of version 4.2 or later automatically upgrade when the computer is restarted as new versions are released. The upgrade in this feature, in this tool can be used to upgrade older versions, or to force a manual upgrade without having to wait for the computer to restart.

To start the Desktop Agent Deployment Tool browse to the folder selected during installation and double-click the DesktopAgentDeploymentTool application (DesktopAgentDeploymentTool.exe). The Desktop Agent Deployment Tool application has two tabbed pages: the Current Deployments tab and the New Deployment tab.

Current Deployments Tab

The Current Deployments tab is the default view when the application starts. This view includes a grid to display a list of deployments and five buttons/controls: Refresh, Restart Agent, Uninstall, Upgrade, and Display. On the Refresh and Display filter controls will be disabled and the list of Desktop Agent deployments will initially be empty.

Refresh – The Refresh button queries the Data Service and updates the displayed list of computers that have the Desktop Agent installed on them (and that have successfully registered a logon at least once).

Restart Agent – The Restart Agent button causes the Desktop Agent service to be restarted on the selected deployment host computers. No specific indication is given if a restart is successful, but the Last Contact Time column is typically updated. Additionally, the Desktop Agent logs on the target PC can be checked for entries confirming a restart.

Upgrade – The Upgrade button updates the Desktop Agent service components on the target host. No confirmation is requested and the Upgrade Status window displays indicating the service is being stopped on the target host.

Uninstall – The Uninstall button attempts to remove the Desktop Agent service from the target host(s). The uninstall process first prompts for confirmation.

To uninstall the Agent Service from a host, complete the following steps.

Click Uninstall in the QMS Desktop Agent Deployment Tool window. The QMS Agent Uninstallation window displays.
Click Yes and the uninstall begins. The Uninstallation Status window displays.
Soon after, the uninstall process may prompt for the credentials to be used to access the target host. If the credentials are necessary, then the Specify Alternate Credentials window displays.
Enter the appropriate credentials and click OK to proceed. In the Uninstallation Status window the status updates to Uninstall Started.

The Further status available status occurs because the service that would communicate with the status is unavailable as a result of the action, i.e. if the uninstall is stopped or removed.

Display – The Display selection control filters the list of displayed deployments. The default Display filter selections are All Deployments and Inactive Deployments. Active deployments are those that currently have a user logged into them – inactive deployments do not.

To refresh, restart, uninstall, upgrade, or display an agent, complete the following steps.

Click Refresh. All the currently deployed desktop agents display. The Restart Agent, Uninstall, and the Upgrade buttons apply to the selected deployment(s) and are disabled until at least one row is selected.
Select an item in the list. The Restart Agent, Uninstall, Upgrade, and Display buttons are enabled.
Select the action that you want to perform and complete the necessary actions that follow.

New Deployment Tab

The New Deployment tab view remotely installs the Desktop Agent to computers (used by Quality Management Suite users); this view includes a grid to display a list of candidate host computers and three buttons: Find Hosts, Install Selected, and Manual Install. The candidate hosts are typically Windows Domain Members as the candidate list is queried from Active Directory. Only the Find Hosts and Manual Install buttons will be initially enabled, while the list of candidate PCs will be empty. The Install Selected button is only enabled when one or more hosts are selected in the (candidate) hosts list.

Find Hosts – Click the Find Hosts button for the Desktop Agent Deployment Tool to issue an Active Directory query to identify any configured domain members. Depending on your network topology, it can take several minutes for this query to complete and the candidate list to display.

Install Selected – The Install Selected button installs the Desktop Agent to computers that are selected in the hosts list – typically computers that are domain members.

Manual Install – The Manual Install button installs the Desktop Agent to computers that are not present in the hosts list – typically non-domain computers.

Installing the Desktop Agent Service Locally

The Desktop Agent Installer is typically bundled with the Desktop Agent Deployment Tool Installer and Screen Recording Monitor Installer, and then distributed as a zip file. For example, the 4.1 versions of these installers were distributed in a file called CallRex_4_1_0_9554_Computer_Recording.zip. Unzip your version of the distribution file on the target host (or copy the installer files from a network share of removable media).

To install the local Desktop Agent Service, complete the following steps.

Use Windows Explorer to navigate to the Installer files (i.e. Installers\QMS DesktopAgent\).
Run the DesktopAgent Setup program to start the setup wizard.
Click Install. The Welcome page displays.
Click Next. The License Agreement page displays.
Select the I accept the terms in the License Agreement checkbox and click Next. The Welcome page displays.
Click Next. The Call Recording Server page displays.
Enter the address of the Recording Server to which this host will connect.
Enter the screen capture interval.
If the Recording Server is configured to secure Desktop Agent Connections, check the "Use SSL for SignalR" checkbox. If SSL is enabled the address for the Recording Server entered above needs to match the subject of the certificate configured on the Recording Server and is typically the FQDN of the Recording Server.
If a secret was configured on the Recording Server, enter the secret value.
Click Next. The Ready to Install page displays.
Click Install to begin the installation. The Installation Complete page displays when the installer finishes.
Click Close to close the installer. The Desktop Agent service should now be installed and the service should now be running.
Open Services and locate the QMS Desktop Agent to confirm that it downloaded.

Updating the Desktop Agent Security Settings

After the Desktop Agent Service has been installed it may be necessary to change the security configuration of the service, for example if the secret needs to be changed. To do this you can run the following command:

DesktopAgent.exe -updatesecurity /SECRET=<new secret value> /ENABLESSL=< 1 to enable, 0 to disable > [/SERVER=<server>]

SECRET - the new secret value or blank if removing the use of a secret.
ENABLESSL - 1 to enable, 0 to disable.
SERVER (optional) - the address used to reach the Recording Server.

Troubleshooting Desktop Agent Deployment

Error: “HTTP could not register URL” in AgentCacheLog.txt

You may see the following error in AgentCacheLog.txt on the client computers when it fails to establish a connection to port 8425 on the server: “HTTP could not register URL http://+8425/AgentService/. Your process does not have access rights to this namespace.”

Follow the steps in Appendix A to add a namespace registration. If the above steps do not solve this issue, repeat the steps on the Client PC and reboot. You will also need to ensure that there are no software or hardware firewalls blocking the traffic. If there are any firewalls, you need to open up traffic for ports 8006 and 8425.

Current Deployments Tab – Restart, Uninstall, and Upgrade failures

All three of these deployment targeted actions – Restart, Uninstall, and Upgrade – require communications with the selected deployment hosts if a problem occurs, the “Unable to connect…” error dialog typically displays offering the option of using different credentials to perform the action.

In the event of this error, first ensure that the target host is powered on. If the host is on, then verify that the appropriate credentials are in use. Frequently, success may be attained using the local administrator account of the target host.

If the Desktop Agent Deployment Tool continues to show the host on the previous version after upgrading the Agent Service on a target host, then you need to remove the older agent software with regedit (rename) and also in Program Files (rename), and install the newer agent once more.

New Deployment Tab – Remote Deployment errors

Regardless of the deployment mode (selected or manual), deployments can fail for similar reasons when trying to access the remote host. These failures are typically the result of a requirement missing on the Desktop Agent target host.

A failure status that includes “No access: The network path was not found” may indicate that a network or firewall issue may exist. One quick way to test connectivity between the deployment target and the host running the deployment tool is to verify that the ping utility works in both directions. If ping fails in one or both directions, then a closer look at the network configuration or firewall settings is in order. Disabling the firewall may be a quick way to determine if the firewall settings are the issue. If ping works in both directions, you may want to try credentials from the target host’s local Administrator account.

A failure status that includes “No registry access: The network path was not found” may indicate that the remote registry service is not running, start it and retry the deployment. If it was running, verify it is set to automatically start and restart the computer, and retry the deployment. If it still fails, then you may want to try credentials from the target host’s local Administrator account.

A failure status that implies “.NET 4” is missing is straightforward; install the .NET 4 client on the target machine and retry the deployment.

If after completing a deployment the target host does not show up on the Current Deployments tab, then it may be necessary to have the user log out and then back into their computer.