PlatformProduct updates

Troubleshooting Agent for Windows

Components

The Windows version of the EDC Agent consists of multiple components. The components are communicating with each other via gRPC.

Name

Role

AgentUI

The User Interface of the Agent. Runs constantly in the background (in the context of the current user). Icon in tray bar.

Auto-Update Service

A Windows Service responsible for running auto-update. Runs as a Service (system).

Platform Hub

The backbone of the Agent. Runs as a Windows Service (Local Service).

Classifier

Is started by AgentUI and acts as a bridge used by AgentUI to classify files (via explorer classification).

CLI

A lightweight .exe file used to execute CLI commands.

Outlook Plugin

VSTO Plugin for Microsoft Outlook.

Excel Plugin

VSTO Plugin for Microsoft Excel.

PowerPoint Plugin

VSTO Plugin for Microsoft PowerPoint.

Word Plugin

VSTO Plugin for Microsoft Word.

Windows Shell Extension

A Shell Extensions used to add the right-click classification option in Windows Explorer.

Health Check Task

A Windows Scheduler Task for running health checks.

Log and installation paths

Version 3.*

Name

Path

AgentUI

%appdata%\GVClient.AgentUI\logs

Auto-Update Service

C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\GVClient.AutoUpdateService.Windows\Logs

Platform Hub

C:\Windows\ServiceProfiles\LocalService\AppData\Roaming\GVClient.PlatformHub.Windows\Logs

Classifier

%appdata%\GVClient.Classifier.Windows\Logs

CLI

%appdata%\GVClient.CLI.Windows\Logs

Outlook Plugin

%appdata%\OutlookClassifier\Logs

Excel Plugin

%appdata%\ExcelClassifier\Logs

PowerPoint Plugin

%appdata%\GVClient.Powerpoint\Logs

Word Plugin

%appdata%\WordClassifier\Logs

Windows Shell Extension

Logging must be manually enabled: sharpshell/docs/logging/logging.md at main · dwmkerr/sharpshell (github.com)

Health Check Task

C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\GVClient.Healtcheck.Windows\Logs

Steps to generate logs for installation:

Generate Installation Logs

Logs structure overview

12/06/2022 10:29:51.009  [  T4\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Connection was aborted: System.AggregateException: One or more errors occurred. (No such host is known.)
 ---> System.Net.Http.HttpRequestException: No such host is known.
 ---> System.Net.Sockets.SocketException (11001): No such host is known.
   at System.Net.Http.ConnectHelper.ConnectAsync(String host, Int32 port, CancellationToken cancellationToken)
   --- End of inner exception stack trace ---
   .
   .
   .
12/06/2022 10:29:51.015  [  T4\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Waiting 10s before trying to reconnect
12/06/2022 10:30:00.262  [ T12\ConfigurationProviderService.GetConfiguration] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]         WARNING: Configuration missed: PluginConfigurationEvent
...
12/06/2022 10:30:01.035  [  T8\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Creating new channel to https://3.253.33.11-jirka:443
12/06/2022 10:30:01.035  [  T8\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Keycloak token endpoint: https://3.253.33.11-jirka/auth/realms/gv/protocol/openid-connect/token, clientId: agent, userName: agent
12/06/2022 10:30:01.119  [  T8\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Connection was aborted: System.AggregateException: One or more errors occurred. (No such host is known.)
                              ^^^ "Component's name + component's action".          ^^^ some metadata                                                                                                ^ log level   ^ log message

The most crucial elements in the given example are the Component along with the component's action, and the log message. These components, when combined, provide a clear understanding of the actions being performed by the application and their respective outcomes.

Troubleshooting tips

  • Starting from version v.4.1 the agent will by default only log items marked as information or above, Debug entries will be ignored.

    • This results in much smaller log files

    • However, in certain scenarios it’s still preferrable to see all logs entries, those can be enabled via Right click on AgentUI in Taskbar -> Diagnostics -> Set log level

  • Always check the version of the agent and check release notes for latest version to check if a similar issue wasn’t already fixed in a newer version.

  • Always note the timestamp when issues occur—this step is essential for accurately identifying problems within logs.

  • Begin by checking the logs of the affected component. For example, if an issue arises with Outlook, first examine the Outlook plugin logs.

    • The Platform Hub logs should be your second priority, as they are also vital for correctly diagnosing the issue.

    • Windows Event Viewer might also hold important log entries.

  • Avoid handling large log files. Instead, restart the application and attempt to replicate the issue immediately, ensuring the log file remains as small as possible.

    • Refresh the logs folder regularly to ensure you are reviewing the most recent logs.

    • When troubleshooting an issue (or capturing a clear log sequence) with a plugin—for instance, Outlook not inheriting classification from the original email upon replying in certain cases—it's easy for application logs to become cluttered and important entries to be overlooked. In such instances, consider stopping the service, clearing the logs, and then starting the service again. Open Outlook, perform one action, stop the service, save the log file, and restart the service. Then, open Outlook, execute a second action, stop the service, save the log file, and repeat as necessary. Although this approach is time-consuming, it allows for a precise record of all actions, enabling comparison between different procedures and understanding what occurred among all the components. For example, we were able to verify that, in one scenario, the Outlook plugin did not check the source message (document) for classification, thus failing to inherit it.

  • Utilize advanced editor tools like Notepad++ for log analysis.

Health Check Task

The Windows Scheduler Task is responsible for automatically fixing some common issues which might appear on a user machine. It will run every 5 minutes with admin permissions.

The automated health check tasks include:

  • Check if AgentUI autorun is properly setup under Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Run

  • Check if AutoUpdate Service and Platform Hub Service are properly setup:

    • Startup type is either Automatic or Automatic (Delayed Start)

    • The services are running

    • Log On As is properly set to Local System and Local Service

  • Office VSTO Plugins are properly setup:

    • AddinList, DoNotDisableAddinList, LoadBehaviour are properly setup

    • CrashingAddinList, Disableditems, StartupItems, NotificationReminderAddinData are cleaned up

Common Issues

1. Plugins not loading / Classification ribbon not visible.

When the plugins can’t load for some reason, the Getvisibility ribbons will be missing in the office application.

a. Check if the ribbon is not suppressed in Agent Config.

b. Check Plugin is enabled under COM Add-ins.

Go to File → Options → Add-ins → Manage: COM Add-ins → Go…

Ensure the Plugin is checked.

If for some reasons the Plugin was disabled, Office will show a short message about the issue:

c. Check Office Resiliency registry keys.

Check Office Resiliency registry keys: Microsoft Office might on occasions disable specific plugins (e.g. due to plugin crashing). When this happens a registry value will be created under:

  • HKCU\SOFTWARE\Microsoft\Office\{version}\{product}\Resiliency\DisabledItems

  • HKCU\SOFTWARE\Microsoft\Office\{version}\{product}\Resiliency\CrashingAddinList

Where {product} might be of values:

  • Outlook

  • PowerPoint

  • Word

  • Excel

And {version} might be:

  • 14.0

  • 15.0

  • 16.0

The value might be either in plain string (REG_SZ) or binary (REG_BINARY).

d. Check Windows Event Viewer.

The plugin might throw an unhandled exception which interrupts the startup of the plugin. Check if any error was logged at the time the Office Application was started.

2. Updating document failed with “Unexpected error when updating document. Please contact support.”

When the Office Plugin (Word, Excel, Outlook or PowerPoint) encounters an unexpected error while trying to update the document, a generic error message will be shown to the user. This is a top-level catch all message. Meaning this will occur when there is a new, unhandled bug that has previously not been seen. It is designed to alert the user that there has been an error and that they should contact support. THIS MESSAGE BOX IS NOT AN ERROR ITSELF.

This error message is generic and doesn’t indicate any specific issue. In order to get more details about the issue, the logs of the affected plugin must be investigated as they will hold more information about the error. Search the log file for the relevant plugin (Word, Excel, Outlook or PowerPoint) for either FATAL and/or Unhandled exception when updating document to find the correct entry. See the screenshot below for an example:

NOTE: When creating a bug ticket for an issue discovered as a result of the above message, DO NOT create a ticket with only generic information such as a title of “Unexpected error”, etc. Please check the logs for the specific error, then create the ticket with these specific details. Having multiple tickets created all with the same name causes confusion when tracking tickets, and leads to the assumption that the issue has been previously fixed when in fact it it an entirely new issue.

3. Ribbon is greyed out

A greyed-out button is an indication, that the plugin is loaded but classification is not available. There might be multiple root causes for this issue.

a. Plugin is disabled in Agent Config.

Make sure the plugin is enabled in Agent Configuration:

b. Platform Hub is not running / Agent Configuration not available.

The proper functioning of the plugins is contingent on the Platform Hub being operational and that it was able to fetch config from BE. Should the Platform Hub cease to run properly, this will impede the functionality of the plugins.

If the Platform Hub is not running, you may try to manually start the Hub.

If this attempt is unsuccessful or the Hub was already running, it's advisable to consult the provided guidelines for resolving issues related to the Platform Hub. For detailed instructions, please refer to TODO.

Another indication of Platform Hub issues will be an alert icon on the taskbar agent icon:

4. Platform Hub is not running

The Platform Hub is essential for the agent's functionality; without it, the entire product cannot operate properly.

a. .NET Framework not installed.

The Platform Hub was built using Microsoft .NET 6 framework. It’s essential that the machine has the following frameworks installed:

b. Startup Type is misconfigured.

The HealthCheck component of the product should automatically ensure that the Service is running and that it’s properly setup. Please also ensure that the Getvisibility Health Check Windows Scheduler Task is properly setup.

Make sure the Startup Type of the Getvisibility Platform Service is set to Automatic (Delayed Start) or Automatic.

To open Services: Press the ⊞ Win + R keys simultaneously. Type services.msc . Press OK or hit ↵ Enter.

The default startup type for the Platform Hub is Automatic (Delayed Start), however it’s possible to change it to Automatic in case the machine has issues with this startup type.

5. Agent not connected to server / configuration not available.

An agent not connected to the server will hinder the application's normal operation. The taskbar icon will display a red alert indicator, and the classification ribbons in Office applications may appear greyed out. The right-click classification feature will also be non-functional.

a. Server address misconfigured or not reachable.

Verify that the server address has been correctly entered. It should consist solely of the domain name or IP address, without the protocol prefix, e.g: somecluster.com or 199.222.111.111

Conduct a ping test to the server to eliminate potential network or cluster issues.

In this example we can see attempt to connect to backend (agent-edge) at https://3.253.33.11-jirka:443or https://3.253.33.11-jirka/auth/realms/gv/protocol/openid-connect/token which failed with: Connection was aborted: System.AggregateException: One or more errors occurred. (No such host is known.) produced by AgentEdgeConnectivityManager.ManageConnection

12/06/2022 10:29:51.015  [  T4\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Waiting 10s before trying to reconnect
..
..
12/06/2022 10:30:01.035  [  T8\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Creating new channel to https://3.253.33.11-jirka:443
12/06/2022 10:30:01.035  [  T8\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Keycloak token endpoint: https://3.253.33.11-jirka/auth/realms/gv/protocol/openid-connect/token, clientId: agent, userName: agent
12/06/2022 10:30:01.119  [  T8\AgentEdgeConnectivityManager.ManageConnection] [OfficeVersionNumber: 16.0.15726.20196, OfficeVersionName: O365BusinessRetail] [CpuCores: 1] [TotalMemory: 7.92GB]     INFORMATION: Connection was aborted: System.AggregateException: One or more errors occurred. (No such host is known.)
 ---> System.Net.Http.HttpRequestException: No such host is known.
 ---> System.Net.Sockets.SocketException (11001): No such host is known.
   at System.Net.Http.ConnectHelper.ConnectAsync(String host, Int32 port, CancellationToken cancellationToken)
   --- End of inner exception stack trace ---
   at System.Net.Http.ConnectHelper.ConnectAsync(String host, Int32 port, CancellationToken cancellationToken)
   at System.Net.Http.HttpConnectionPool.ConnectAsync(HttpRequestMessage request, Boolean allowHttp2, CancellationToken cancellationToken)
   at System.Net.Http.HttpConnectionPool.CreateHttp11ConnectionAsync(HttpRequestMessage request, CancellationToken cancellationToken)
   at System.Net.Http.HttpConnectionPool.GetHttpConnectionAsync(HttpRequestMessage request, CancellationToken cancellationToken)
   at System.Net.Http.HttpConnectionPool.SendWithRetryAsync(HttpRequestMessage request, Boolean doRequestAuth, CancellationToken cancellationToken)
   at System.Net.Http.RedirectHandler.SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
   at System.Net.Http.HttpClient.FinishSendAsyncBuffered(Task`1 sendTask, HttpRequestMessage request, CancellationTokenSource cts, Boolean disposeCts)
   --- End of inner exception stack trace ---
   at System.Threading.Tasks.Task.ThrowIfExceptional(Boolean includeTaskCanceledExceptions)
   at System.Threading.Tasks.Task`1.GetResultCore(Boolean waitCompletionNotification)
   at System.Threading.Tasks.Task`1.get_Result()
   at GVClient.PlatformHub.Shared.AgentsEdge.KeycloakAgentEdgeTokenInterceptor.CreateAccessToken() in C:\actions-runner\_work\office-classifier\office-classifier\GVClient\GVClient.PlatformHub.Shared\AgentsEdge\KeycloakAgentEdgeTokenInterceptor.cs:line 160
   at GVClient.PlatformHub.Shared.AgentsEdge.KeycloakAgentEdgeTokenInterceptor.GetAccessToken() in C:\actions-runner\_work\office-classifier\office-classifier\GVClient\GVClient.PlatformHub.Shared\AgentsEdge\KeycloakAgentEdgeTokenInterceptor.cs:line 138
   at GVClient.PlatformHub.Shared.AgentsEdge.KeycloakAgentEdgeTokenInterceptor.BlockingUnaryCall[TRequest,TResponse](TRequest request, ClientInterceptorContext`2 context, BlockingUnaryCallContinuation`2 continuation) in C:\actions-runner\_work\office-classifier\office-classifier\GVClient\GVClient.PlatformHub.Shared\AgentsEdge\KeycloakAgentEdgeTokenInterceptor.cs:line 90
   at Grpc.Core.Interceptors.InterceptingCallInvoker.BlockingUnaryCall[TRequest,TResponse](Method`2 method, String host, CallOptions options, TRequest request)
   at Grpc.Core.Interceptors.InterceptingCallInvoker.<BlockingUnaryCall>b__3_0[TRequest,TResponse](TRequest req, ClientInterceptorContext`2 ctx)
   at Grpc.Core.ClientBase.ClientBaseConfiguration.ClientBaseConfigurationInterceptor.BlockingUnaryCall[TRequest,TResponse](TRequest request, ClientInterceptorContext`2 context, BlockingUnaryCallContinuation`2 continuation)
   at Grpc.Core.Interceptors.InterceptingCallInvoker.BlockingUnaryCall[TRequest,TResponse](Method`2 method, String host, CallOptions options, TRequest request)
   at Com.Getvisibility.Grpc.Ping.PingPongService.PingPongServiceClient.Ping(PingRequest request, CallOptions options) in C:\actions-runner\_work\office-classifier\office-classifier\GVClient\GVClient.Common\obj\Release\_proto\PingpongGrpc.cs:line 114
   at Com.Getvisibility.Grpc.Ping.PingPongService.PingPongServiceClient.Ping(PingRequest request, Metadata headers, Nullable`1 deadline, CancellationToken cancellationToken) in C:\actions-runner\_work\office-classifier\office-classifier\GVClient\GVClient.Common\obj\Release\_proto\PingpongGrpc.cs:line 109
   at GVClient.PlatformHub.Shared.AgentsEdge.AgentEdgeConnectivityManager.ManageConnection() in C:\actions-runner\_work\office-classifier\office-classifier\GVClient\GVClient.PlatformHub.Shared\AgentsEdge\AgentEdgeConnectivityManager.cs:line 140

b. Keycloak settings misconfigured.

Misconfiguration of Keycloak settings can prevent the agent from authenticating correctly. In such instances, the logs may include messages like:

  • Grpc.Core.RpcException: Status(StatusCode="Unauthenticated", Detail="JWT Token is null or malformed")

  • Failed to get access token!

If you encounter these issues, please consult the pages:

Reseller Keycloak Quick Installation GuideAlternative authentication methods for agent

c. HTTP 2.0 disabled

Some proxies are blocking HTTP 2.0 requests, resulting in error messages like below:

INFORMATION: Connection was aborted: Grpc.Core.RpcException: Status(StatusCode="Internal", Detail="Error starting gRPC call. HttpRequestException: Requesting HTTP version 2.0 with version policy RequestVersionOrHigher while unable to establish HTTP/2 connection.", DebugException="System.Net.Http.HttpRequestException: Requesting HTTP version 2.0 with version policy RequestVersionOrHigher while unable to establish HTTP/2 connection.
   at System.Net.Http.HttpConnectionPool.ThrowGetVersionException(HttpRequestMessage request, Int32 desiredVersion)
   at System.Net.Http.HttpConnectionPool.SendWithVersionDetectionAndRetryAsync(HttpRequestMessage request, Boolean async, Boolean doRequestAuth, CancellationToken cancellationToken)
   at System.Net.Http.RedirectHandler.SendAsync(HttpRequestMessage request, Boolean async, CancellationToken cancellationToken)
   at System.Net.Http.HttpClient.<SendAsync>g__Core|83_0(HttpRequestMessage request, HttpCompletionOption completionOption, CancellationTokenSource cts, Boolean disposeCts, CancellationTokenSource pendingRequestsCts, CancellationToken originalCancellationToken)
   at Grpc.Net.Client.Internal.GrpcCall`2.RunCall(HttpRequestMessage request, Nullable`1 timeout)")
   at Grpc.Net.Client.Internal.HttpClientCallInvoker.BlockingUnaryCall[TRequest,TResponse](Method`2 method, String host, CallOptions options, TRequest request)
   at Grpc.Core.Interceptors.InterceptingCallInvoker.<BlockingUnaryCall>b__3_0[TRequest,TResponse](TRequest req, ClientInterceptorContext`2 ctx)
   at GVClient.Application.Hub.AgentsEdge.Authentication.KeycloakTokenInterceptor.BlockingUnaryCall[TRequest,TResponse](TRequest request, ClientInterceptorContext`2 context, BlockingUnaryCallContinuation`2 continuation) in C:\Users\admin\Documents\Git\office-classifier\GVClient\2.Application\GVClient.Application.Hub\AgentsEdge\Authentication\KeycloakTokenInterceptor.cs:line 85
   at Grpc.Core.Interceptors.InterceptingCallInvoker.BlockingUnaryCall[TRequest,TResponse](Method`2 method, String host, CallOptions options, TRequest request)
   at Grpc.Core.Interceptors.InterceptingCallInvoker.<BlockingUnaryCall>b__3_0[TRequest,TResponse](TRequest req, ClientInterceptorContext`2 ctx)
   at Grpc.Core.ClientBase.ClientBaseConfiguration.ClientBaseConfigurationInterceptor.BlockingUnaryCall[TRequest,TResponse](TRequest request, ClientInterceptorContext`2 context, BlockingUnaryCallContinuation`2 continuation)
   at Grpc.Core.Interceptors.InterceptingCallInvoker.BlockingUnaryCall[TRequest,TResponse](Method`2 method, String host, CallOptions options, TRequest request)
   at Com.Getvisibility.Grpc.Ping.PingPongService.PingPongServiceClient.Ping(PingRequest request, CallOptions options) in C:\Users\admin\Documents\Git\office-classifier\GVClient\GVClient.Common\obj\Release\netstandard2.1\_proto\PingpongGrpc.cs:line 114
   at Com.Getvisibility.Grpc.Ping.PingPongService.PingPongServiceClient.Ping(PingRequest request, Metadata headers, Nullable`1 deadline, CancellationToken cancellationToken) in C:\Users\admin\Documents\Git\office-classifier\GVClient\GVClient.Common\obj\Release\netstandard2.1\_proto\PingpongGrpc.cs:line 109
   at GVClient.Application.Hub.AgentsEdge.AgentEdgeConnectivityManager.ManageConnection() in C:\Users\admin\Documents\Git\office-classifier\GVClient\2.Application\GVClient.Application.Hub\AgentsEdge\AgentEdgeConnectivityManager.cs:line 154

The proxy config should be adjusted.

d. Additional steps to verify.

Keycloak can log authentication error events if enabled:

When looking for login events we need to identify the IP address which was used for login as there are other service authorizing against Keycloak. For GV agent connections it is traefik pod which is handling all connections from the outside world.

Once we know the IP we can search for login events from this source:

d. Keycloak troubleshooting.

Retrieve Keycloak user/password:

cd /opt/keycloak/bin ./kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin --password admin

List users configured in Keycloak:

./kcadm.sh get users -r gv

Create agent user:

./kcadm.sh create users -s username=agent -s enabled=true -s email="agent@gv.com" -r gv

Export current config to see if Realm has changed:

cd /opt/keycloak/bin ./kc.sh build --cache=local ./kc.sh export --file /opt/keycloak/bin/mark.jsonbash-4.4$ cat /opt/keycloak/bin/mark.json | grep -A 1 getvisibility "id" : "getvisibility", "realm" : "Awaed DC", --

Where should be

bash-4.4$ cat /opt/keycloak/bin/mark.json | grep -A 1 getvisibility "id" : "getvisibility", "realm" : "gv",

6. Missing suggestions

Please consult the following document for missing suggestions:

Guide for missing suggestions

7. Agent icon not appearing in taskbar

Missing icon in taskbar is usually an indicator that the AgentUI process is not running at all.

a. AgentUI process crashed.

There's a possibility that the AgentUI process has encountered a crash. A system reboot or a manual initiation often resolves this issue. Attempt to manually launch the process using the path:

C:\Program Files (x86)\GVClient\app-4.1.0\AgentUI\GVClient.AgentUI.exe

Additionally, it's essential to examine the AgentUI logs along with the Windows Event Viewer logs to pinpoint the crash's cause. Analyzing these logs is vital for enhancing the agent's performance and stability.

b. AgentUI is removed from Autorun.

Ensure the GVClient.AgentUI.exe is properly configured under Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Run. Make sure it points to the right version of the application.

Also make sure the AgentUI is not disabled under Startup Apps:

8. Auto-Update not working

The auto-update functionality depends on a lot of conditions in order to perform properly.

Please note the auto-update won’t be executed for RC versions, unless the registry key IsRCVersion will be explicitly set to False.

a. Auto-Update properly configured.

Make sure Auto-Update is enabled and that the URL and package regex are properly configured.

It’s recommended to leave Auto-update: server URL or path and Auto-update: regex for agent packages to include empty. The agent will assume proper default values.

b. Startup Type is misconfigured.

The HealthCheck component of the product should automatically ensure that the Service is running and that it’s properly setup. Please also ensure that the Getvisibility Health Check Windows Scheduler Task is properly setup.

Make sure the Startup Type of the Getvisibility AutoUpdate Service is set to Automatic (Delayed Start) or Automatic.

To open Services: Press the ⊞ Win + R keys simultaneously. Type services.msc . Press OK or hit ↵ Enter.

The default startup type for the AutoUpdate Service is Automatic (Delayed Start), however it’s possible to change it to Automatic in case the machine has issues with this startup type.

The Service must also run as Local System.

c. AutoUpdate artifacts properly deployed.

To deploy agent artifacts correctly, please refer to the Artifact bundle deployment - Getvisibility - Confluence (atlassian.net) for comprehensive instructions.

  • For v3 agents, use: https://{cluster}/updates/static/

  • For v4 agents, access: https://{cluster}/static-server/static/agent/stable/

  • For beta versions of v4 agents, the correct URL is: https://{cluster}/static-server/static/agent/beta/

By navigating to these URLs, you'll be able to see a list of available artifacts for the respective agent versions.

This method is more straightforward than accessing the user's Command Line Interface (CLI), navigating to the correct auto-update server (either AutoUpdateServer or StaticServer), and then browsing the appropriate subdirectory to check the files present.

d. Analyze logs and failure point.

The AutoUpdate Service has verbose logs to make troubleshooting easier.

The agent will attempt to retrieve the auto-update configuration in the following order:

  1. The primary source will be the agent config, the auto-update service will try to connect to the Platform Hub, retrieve the config and determine the endpoint.

  2. If for some reason the auto-update service can’t reach the Platform Hub, then it will look for the auto-update config in Windows Registry. The hub is responsible for filling data in the Windows Registry (whenever it had a chance to retrieve the config). It can be also manually adjusted.

9. Installation of agent fails

If the installation of the agent fails abruptly, please check the following point before raising a ticket:

  • Make sure there are no leftovers from previous installations under C:\Program Files (x86)\GVClient\

  • Try to restart the process explorer.exe

  • It’s also recommended to perform a reboot after previous versions were removed.

  • Make sure the file installerConfig.json is not blocked -> right-click -> Properties -> Unblock

Always use the deployment script for mass deployments - the script will attempt to automatically cleanup any leftovers so the agent can properly be installed. Contact GV Support for further details: support@getvisibility.com

If none of the above step help, then it’s necessary to investigate the installer logs. The installer also logs all custom steps in Windows Event Viewer.

10. CLI not working

Most of the time the CLI not working is due the following reasons:

  • Platform Hub not running or agent config not available - in this case please consult steps above.

  • Wrong format of tags:

    • Binary tags must use this format: --tag f14fc1f1-8950-40d5-8a29-45909da947d6/PCI/true (--tag {tagsetId}/{tagName}/{true/false}), and categorical tags --tag e16409a7-1700-4153-9090-3955bc2f0ae8/Classification/Internal (-- tag {tagsetId}/{tagsetName}/{tagname})

    • If the tag contains a / in the name, it has to be escaped with //

    • Missing --save parameter - this parameter specifies that the changes to the file should be saved.

11. Dashboard Agent Configuration Problems

If the dashboard doesn't work right when you're trying to change the agent settings, it might be because your browser is showing an old saved version. To fix this, refresh your browser to get the latest version by pressing CTRL+F5. Do this before you report any bugs.

12. Print options missing after installing agent

The absence of print options following the installation of the agent is an anticipated outcome. Due to our inability to intercept print commands within PowerPoint, the standard print functionality has been substituted with a specialized button designed to manage printing tasks. This custom button, however, offers only a restricted set of options for print customization.

Plans are underway to roll out a feature that will enable administrators to modify and control this behavior, providing a more flexible approach to managing print options.

13. PowerPoint Footers do not appear in some/all slides despite being configured and working in other PowerPoint Files

A commonly reported bug is footers not appearing in PowerPoint in some or all slides. This is nearly always due to the custom settings for that file’s slide layouts. Slide layouts in ppt (Title Slide, Title and Content, Blank, etc) can be modified or added to by end users. One of these options is to disable footers for the slide layout. In this case, we assume it is deliberate from the user, and we respect this by not adding the GV footer. If you see this issue, please go to View → Slide Master and check the specific slide layout(s) to see if the footer is disabled, as shown in the screenshot below. If the footer shows as enabled here still (and you can’t appear to uncheck the box) then check the master slide layout as in the second screenshot.

PreviousGenerate Installation LogsNextGuide for missing suggestions

Last updated

Was this helpful?