Employee Search

Overview

Employee Search is feature of the modular solution Employee Records Management (ERM). This is an externally built application (on a lighter stack) that integrates with the platform via APIs/webhooks/SSO to deliver targeted functionality. It operates exclusively through API calls as well as direct database queries. The app is scaffolded from a private VisualVault GitHub repository (GRM-Implementation) and uses Kendo UI JavaScript components for its interface.

The ERM application is accessed via a VisualVault menu item that navigates the user directly to the app's URL, opening it outside of VisualVault. When the menu item is configured, VisualVault passes a user login token and an authentication token as URL parameters. These tokens are consumed by the Node.js app to verify the user's identity via auth.js and config.js.

Note: Authentication is bypassed during local development and testing. When deployed to a VisualVault production environment, users must authenticate via SSO before the app is accessible.

↓ Jump to Implementation Guide

Feature Objective

The Employee Search application provides role-based, limited access to employee data through a secure search interface. This eliminates the need for the user to directly access the Document Library. Key capabilities include:

• Search by first name, last name, department or employee ID

• Scoped results restricted to a user's direct and second-level reports, enforced through Okta group membership (Okta-Workflow List of Managers) and VisualVault security group permissions

• Document viewer with view, download, and print capabilities, pulling files from the Document Library

• Impersonate User ID for admins to conduct permission validation, troubleshooting, and audit purposes

Technical Architecture

Application Stack

Integration with VisualVault Portals/Workspaces

The Employee Search app is accessed through a configured VisualVault menu item. Clicking the menu item navigates the user away from VisualVault and directly to the app's URL in the browser. Session tokens are appended to the URL as parameters, which the app uses to authenticate the current user.

+-------------------------------+          +-----------------------------+
| VisualVault (Authenticated)   |  click   | Employee Search App         |
|                               | -------> | (external URL, new nav)     |
|  [ Menu Item: ERM]            |          |                             |
|    URL + ?loginToken=...      |          | Validates tokens via        |
|         + &authToken=...      |          | auth.js and config.js       |
+-------------------------------+          +-----------------------------+

Data Flow

📋 Coming Soon: A diagram illustrating the full web app interaction with VisualVault — including all API call endpoints and the data flow between the Employee Search app, VisualVault, Okta, and the Document Library — is in progress and will be added here.

Okta Access and User Groups

Access control is enforced through Okta group membership. Users must belong to the Okta-Workflow List of Managers group to interact with the search interface. The app checks group membership on initialization and conditionally renders the UI:

• Users in the Okta-Workflow List of Managers group → search input is displayed

• Users in an excluded group → search input and dropdowns are hidden

• Users not in any configured group → dropdown container is shown in place of the search input

🔍 Troubleshooting Note: If a user reports that the search input is missing or the interface appears restricted, the most likely cause is that they are not a member of the Okta-Workflow List of Managers group, or their group membership has not propagated yet. Confirm the user's Okta group assignment and allow time for synchronization before retesting. If the user is in an excluded group, the interface will be intentionally hidden — verify with the implementer whether that group assignment is correct.

This logic is handled in the data source initialization:

if (!userGroupLoaded) {
  let userData = await $.ajax({
    url: config.APP_BASE_URL + ENDPOINT_DATA,
    dataType: "jsonp",
    data: getFilters(options, true),
    success: function (result) {
      if (result.data[0] && result.data[0].group) {
        userGroup = result.data[0].group;
      }
      userGroupLoaded = true;
      showLoading(false);
      if (isInExcludedUsersGroups(userGroup)) {
        $(INPUT_CONTAINER).hide();
        $(DROPDOWN_CONTAINER).hide();
      } else {
        (isInGroups(userGroup))
          ? $(INPUT_CONTAINER).show()
          : $(DROPDOWN_CONTAINER).show();
      }
    },
    error: function (result) {
      if (options.error) options.error(result);
      showLoading(false);
    }
  });
}

Configuration Parameters

public/js/config.js

APP_BASE_URL: 'https://portalmanager.visualvault.com'

Important: When hosted on a server, use the hostname only — do not include the port number. For example, an app hosted at https://portalmanager.visualvault.com on port 89 should be configured as APP_BASE_URL: 'https://portalmanager.visualvault.com'.

public/js/docFileView.js

// Production
const ENVIROMENT_FLAG = 'PROD';
// Sandbox
const ENVIROMENT_FLAG = 'SANDBOX';

services/serverstrings.js

AUTH_CUST_ALIAS: "CustomerAlias"
AUTH_DB_ALIAS:   "DatabaseAlias"
AUTH_VAULT_URL:  "https://yoursite.visualvault.com"
TOKEN_EXPIRES:   "8h"

Implementation Guide

The following steps are performed by an implementer in the VisualVault platform and Okta.

Configure Okta Group Access

🔧 Implementer Checklist

• Configure the Okta-Workflow List of Managers group and confirm it contains the appropriate managers.

• Map this group to the corresponding VisualVault security group to enforce search result scoping.

Execution Flow

The following describes the runtime sequence from user login to a completed search.

Application Initialization

1. User authenticates via SSO into VisualVault. Upon successful login, VisualVault navigates the user directly to the Employee Records Management (ERM) solution, landing on the Employee Dashboard page.

2. From the ERM left-side navigation menu, the user selects Employee Search. This navigates the browser to the Employee Search app's configured URL.

3. VisualVault passes user and session information to the app via the URL parameters (login token, auth token). Additional session data may be passed via postMessage.

4. The app initializes using the received tokens, verifies the user's identity via auth.js and config.js, and renders the UI.

5. On first load, the app calls the data source endpoint to determine the user's Okta group membership and conditionally renders the appropriate UI state (search input, dropdown, or hidden interface).

🔍 Troubleshooting Note: If a user reports that the Employee Search page is blank, fails to load, or shows an access denied error after SSO login, the most likely causes are an expired or missing authentication token, an incorrectly configured menu item URL, or a failure in the app's initialization call. Verify that the menu item URL includes valid loginToken and authToken parameters, and confirm the app server is running and reachable at the configured APP_BASE_URL.

Search Execution

1. On the Employee Search page, locate the search bar labeled Search (Name, Email, or Employee #).

2. Enter a first name, last name, email address, or employee number in the search field.

3. Click the Search button. The results grid below populates with matching employees.

4. Results are scoped to the authenticated user's direct and second-level reports, enforced through Okta group membership and VisualVault security group permissions. Each row in the results grid displays the following columns:

5. Use the pagination controls at the bottom of the grid to navigate through results. The items per page dropdown allows you to adjust how many records are displayed at once.

6. To view details associated with an employee, click the Details button on the corresponding row. The Employee Detail page for that employee opens, with the Details tab active

7. To view documents associated with an employee, click the Files button on the corresponding row. The Employee Detail page for that employee opens, with the Documents tab active.

🔍 Troubleshooting Note: If a user reports missing or unexpected search results, the issue is most likely related to result scoping rather than a search error. Results are intentionally limited to the authenticated user's direct and second-level reports via Okta group membership and VisualVault security group permissions. If a user expects to see an employee but cannot, confirm that the employee falls within their reporting chain and that the user's Okta group membership is correctly configured. Use the Impersonate User ID feature to replicate the user's search results for diagnostic purposes.

Impersonate User ID

The Impersonate User ID feature allows administrators to perform a search as another user, returning results scoped to that user's permissions. This is intended for permission validation, troubleshooting, and audit purposes.

Access: This feature is available to administrators only. Standard users will not have access to the Impersonate User ID field. It will be a hidden field.

Entering impersonation mode:

1. On the Employee Search page, locate the Impersonate User ID field to the right of the main search bar.

2. Enter the user ID of the user you want to impersonate.

3. Enter a search term in the Search (Name, Email, or Employee #) field as normal.

4. Click Search. Results are returned scoped to the impersonated user's permissions; this means only employees within that user's direct and second-level reports are returned, rather than the administrator's own reports.

How results differ when impersonating:

When a user ID is entered in the Impersonate User ID field, the search engine applies the impersonated user's Okta group membership and security group permissions to scope the results. This allows administrators to see exactly what that user would see when performing the same search.

Exiting impersonation mode:

1. Clear the Impersonate User ID field.

2. Click Search again. Results will return to being scoped to the authenticated administrator's own permissions.

Related Resources

• GitHub Repository: GRM-Implementation (private — requires repository access)