Workforce Access Client Diagnostics Tool

Test HYPR Workforce Access Client connectivity.

📘

Version 6.17.0+ is required

This tool is packaged with Windows HYPR Workforce Access Client 6.17.0 and above. Earlier versions are also compatible, but the tool must be requested from HYPR Support as a standalone download.

Overview

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 version 6.17 and higher.

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. You are prompted to confirm running the tests:

Click Yes to run the tests.

Launching the Diagnostics Tool from the Command Line

📘

NOTE

If the logged in user is not an administrator, run CMD as an administrator to use the Diagnostics Tool.

  1. Open a command prompt and navigate to the directory with the Diagnostics Tool, HyprDiagnosticsConsole.exe. The default location is C:\Program Files\HYPR\.

📘

NOTE

This folder exists for all users with the Workforce Access Client installed.

To run tests for an individual user, e.g., grace.hopper, the complete path to the directory would be C:\Users\grace.hopper>"C:\Program Files\.

  1. Type HyprDiagnosticsConsole.exe to start the Diagnostics Tool. Enter help for more details about the tool usage and parameters.
    Example: HyprDiagnosticsConsole.exe help

Example Commands

  • 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

  • To run basic tests that don't require administrative privileges:
    HyprDiagnosticsConsole.exe run

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.

The test results will be stored in the \Diagnostics directory, located in the folder where the executable resides. In \Diagnostics, the output directory is <username>_<domain>. For user HIGHLANDSBANK\grace.hopper, the default location would translate as C:/ProgramData/HYPR/Diagnostics/grace.hopper_HIGHLANDSBANK, 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.

Supported Commands

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

Lists tests both built-in and ad hoc.

HyprDiagnosticsConsole.exe tests

results

Lists results from previous runs (NOT IMPLEMENTED YET).

HyprDiagnosticsConsole.exe results

example

This command returns examples for various parameters, which are detailed in the following section.

C:\\Program Files\HYPR\HyprDiagnosticsConsole.exe example

Supported Parameters

Below are descriptions of the parameters for the above commands:

-? or -h or --help

This is the default --help parameter providing details for all the supported commands and parameters.

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

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

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

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

Specify directories to file the relative file names specified in --adhoc-files parameters.

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

Store test output in the specified path using this parameter.

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

Explicitly limit the width of the error column in characters.

--log-file=<path>

Specify a custom location in which to write logs.

--log-level=<N>

Overrides the default log level, which is 6 if not specified or if the WACDT is not installed.

--timeout=<N seconds>

Override any and all test timeouts with the entered value.

--connect-timeout=<N seconds>

Overrides default connect timeout value of 10 with the specified value.

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

Includes a more detailed result.

--very-verbose

And an even more detailed result.