Workforce Access Client Diagnostics Tool
HYPR Workforce Access Client: Workstation Troubleshooting: Windows
The HYPR Workforce Access Client Diagnostics Tool is designed to simplify troubleshooting the HYPR Workforce Access Client in a new environment or during active deployment when users are experiencing problems with authentication or registration. The tool allows common system compatibility tests such as certificate template validation, user permission, and network connectivity. It is based upon Microsoft's Active Directory Certificate Services (AD CS); more detailed information about AD CS can be found here.
This document explains how to run the Workforce Access Client Diagnostics Tool, including the various switches used to get different results, on a Windows 10 operating system. The Diagnostics Tool is a standalone application included in the HYPR Workforce Access Client .msi
client installation.
Running Tests
The Diagnostics Tool can be launched either by double-clicking the HYPR logo on the Workforce Access Client dialog (the logo location varies by version) or by issuing commands at a command-line prompt.
Launching the Diagnostics Tool from the GUI
To start the UI version, double-click the logo at top left. You are prompted to confirm running the tests:
Click Yes to run the tests.
Launching the Diagnostics Tool from the Command Line
Run as administrator
If the logged in user is not an administrator, run CMD as an administrator to use the Diagnostics Tool.
To run tests for the current user:
- Change directory to
C:\Program Files\HYPR\
and launchHyprDiagnosticsConsole.exe
from there, or - Run it from anywhere using the complete path,
C:\Program Files\HYPR\HyprDiagnosticsConsole.exe
Sharing is Caring
This folder exists for all users with the Workforce Access Client installed.
Run HyprDiagnosticsConsole.exe help
for more details about the tool usage and parameters.
Example Commands
- To run basic tests that don't require administrative privileges:
HyprDiagnosticsConsole.exe run
- To run administrative tests, replace
HYPRUserTest
in the example below with your certificate template name:
HyprDiagnosticsConsole.exe run --include-domain-admin-tests --test-certificate-template=HYPRUserTest
Output Directory
The test results will be stored in a \Diagnostics
directory where the executable resides. The output directory format is <workstation>_<username>
. So for user HIGHLANDSBANK\grace.hopper
, the default location is C:\ProgramData\HYPR\Diagnostics\HIGHLANDSBANK_grace.hopper
, followed by a subdirectory for each test attempt.
Subdirectories will be created in this folder during each test attempt, named to match the test performed and inclusive of a date-time stamp. (EX: \run-2022-03-08_15-23-45\ADCS
) A maximum of 10 subdirectories will be stored in this fashion; the older ones will be removed as newer tests are generated. In each of the timestamped folders, under \ADCS
, is a .json
file containing the results for each test that was run.
The HyprDiagnostics.log
file is written to the \Diagnostics
folder. It includes valuable information that Support may need to diagnose advanced issues.
The output directory can be changed for a given test by using the --output-dir
parameter, described below.
Test Results
The tests will give a result of Passed (in green on the GUI version) or Failed (in red on the GUI version). If any test fails, the issue description, error code, and recommended resolution will be displayed to the right of the applicable test.
Supported Commands
run
run
Used to run both the built-in diagnostics tests and any ad hoc tests you want to use. Used alone, it runs only the non-domain administrative tests.
HyprDiagnosticsConsole.exe run
tests
tests
Lists tests both built-in and ad hoc.
HyprDiagnosticsConsole.exe tests
results
results
Lists results from previous runs (NOT IMPLEMENTED YET).
HyprDiagnosticsConsole.exe results
example
example
This command returns examples for various parameters, which are detailed in the following section.
HyprDiagnosticsConsole.exe example
Supported Parameters
Below are descriptions of the parameters for the above commands:
-?
or -h
or --help
-?
or -h
or --help
This is the default --help
parameter providing details for all the supported commands and parameters.
--config=<path>
--config=<path>
Used to supply parameters using a .json
file. Usage can be found by using the --help
parameter.
HyprDiagnosticsConsole.exe run --config=C:\Users\<username>\Desktop\hypr-diag.json
This parameter requires a .json
file for all the parameters you would like to test with the Diagnostics Tool. The format of the content to be updated in the .json
file can be obtained by running the example
command as shown here:
HyprDiagnosticsConsole.exe example --config-non-default
HyprDiagnosticsConsole.exe" example --config-default
--include-domain-admin-tests
--include-domain-admin-tests
Run domain administrative tests. The tests marked with the domainAdminTest attribute will run when the above parameter is specified.
HyprDiagnosticsConsole.exe runΒ --include-domain-admin-tests
--adhoc-files=<file1;file2;...>
--adhoc-files=<file1;file2;...>
Use the above parameter to supply the ad hoc test file path. The command shown here returns an example ad hoc test.
HyprDiagnosticsConsole.exe example --adhoc
Copy the output and save the content as a .json
file, providing the file name from the above parameter <file1;file2;...>
.
--adhoc-only
--adhoc-only
Use the above parameter to run only ad hoc tests.
HyprDiagnosticsConsole.exe runΒ --adhoc-only --adhoc-files=C:\Users\<username>\Documents\adhoc.json
--adhoc-dirs <dir1;dir2;...>
--adhoc-dirs <dir1;dir2;...>
Specify directories to file the relative file names specified in --adhoc-files
parameters.
--test-certificate-template=HYPRUserTest
--test-certificate-template=HYPRUserTest
Provides the certificate template name to be used running the test. By default if no value is passed or if the parameter is not specified, the certificate template from the HYPR configuration in the registry editor will be picked up for the tests.Β If the registry entry is empty, User will be assumed as the configuration template to be used by default. Some examples follow:
When no parameter is specified:
When the parameter is specified and supplied with a valid template name:
When the parameter is specified and supplied with a invalid template name:
--output-dir=<path>
--output-dir=<path>
Store test output in the specified path using this parameter.
--filter-name <positive-patterns: -negative-patterns>
--filter-name <positive-patterns: -negative-patterns>
A sequence of search patterns separated by colons (:). Negative search patterns should be preceded by a hyphen (-). Both positive and negative patterns can use wildcards to match the test name, which is identified by <Test Group Name>.<Test Name>
where <Test Group Name>
is the name of the folder including the date-time stamp, and <Test Name>
is the name of the specific test, such as Certificate Template.
--output-width=<N>
--output-width=<N>
Explicitly limit the width of the error column in characters.
--log-file=<path>
--log-file=<path>
Specify a custom location in which to write logs.
--log-level=<N>
--log-level=<N>
Overrides the default log level, which is 6 if not specified or if the WACDT is not installed.
--timeout=<N seconds>
--timeout=<N seconds>
Override any and all test timeouts with the entered value.
--connect-timeout=<N seconds>
--connect-timeout=<N seconds>
Overrides default connect timeout value of 10 with the specified value.
--test-certificate-template=<certificate template name>
--test-certificate-template=<certificate template name>
Specify a certificate template name to be used for testing. When not used, the Diagnostics Tool defaults to User.
--verbose
--verbose
Includes a more detailed result.
--very-verbose
--very-verbose
And an even more detailed result.
Updated 11 months ago