Audit

Overview

Audits 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 through API calls as well as direct database queries. The app is scaffolded from a private VisualVault GitHub repository (HRSurvey) and uses Kendo UI JavaScript components for its interface. When configuring the URL, parameters are passed, including a user login token that carries the user's identity and an authentication token. These tokens are used within the Node.js app to verify the user's authentication.

During testing and debugging, the app doesn't require authentication. However, when deployed into VisualVault production sites, users must log in to authenticate the app for proper access and security verification.

Feature Objective

Audit processes can be optimized by implementing a single search screen to locate and select employee records efficiently. This application eliminates the need for navigating multiple folders, reduce search times, and ensure accuracy by consolidating data access into a unified interface.

It includes role-based permissions, allowing users to view only the records of those they manage or are second-level reports. Staff can search by employee name, view matches with their employee numbers, and access documents via the integrated VisualVault document viewer for secure and efficient management.

Primary Features:

• Group all audit data into a single object.

• Share audit with coordinators.

• Select employees to be audited (possible and definite)

• Quickly locate employee documents requested by auditors and relate them to the audit.

• View all audit documents from a single screen.

Technical Architecture

Application Stack

Integration with VisualVault

The Audit Application is integrated into VisualVault by configuring the application source URL in the VisualVault portal. When a user navigates to the application via the landing page widget, VisualVault appends the user login token and authentication token as URL parameters. The Node.js app reads and validates these tokens to authenticate the session.

+-------------------------------+          +-----------------------------+
| VisualVault                   |  redirect| Audit Application           |
|                               | -------> | (Express, Node.js)          |
|  [ Menu Item: ERM]            |          |                             |
|    URL + ?userLoginToken=...  |          | Validates tokens via        |
|        + &authToken=...       |          | /Services/serverstrings.js  |
|                               |          | and configvariables.js      |
+-------------------------------+          +-----------------------------+

Data Flow

📋 Coming Soon: A diagram illustrating API call endpoints and data flow between the Audit Application, VisualVault APIs, and the SQL data sources will be added here.

Views and Partials

The server serves views using the URL path /views/<view_name>.html (e.g., localhost:89/views/index.html loads index.html). The app includes partial views using HTML includes such as include partials/head.

The application uses a single-page design (SPA) with dynamic view swapping controlled by index.html. JavaScript sets the base URL dynamically using the head.html partial and manages core functionality including authentication and Kendo grid initialization.

// PROD
// var appBaseUrl = 'https://vv5dev.visualvault.com';

// Local machine
var appBaseUrl = 'https://localhost:89';

Controllers and Routes

Routes use Express to connect API calls to controller functions. GET requests fetch data based on query parameters; POST requests submit data to filter or create documents.

// Controller Routes
// TODO - add middleware for bearer token authentication here
var documentsController = require('./controllers/documentsController.js');

app.get('/api/documents', documentsController.findAll);
app.post('/api/documents', documentsController.findAll);
app.post('/api/documents/authenticate', documentsController.authenticate);
app.get('/api/documents/authenticate', documentsController.authenticate);

Models and Data Fetching

Models interact with data sources including SQL databases and VisualVault APIs. Data retrieval is performed via JavaScript promises using SQL queries or VisualVault's API. The controller passes request parameters to the model, which constructs the SQL query or calls VisualVault APIs for data. Results are returned as JSON objects consumed by the front end to update the Kendo grid and interface dynamically.

Configuration Parameters

/Services/configvariables.js

/Services/serverstrings.js

Implemenation Guide

Step 1 — Configure Client and Server Variables

1. Open /Services/configvariables.js and populate the following constants with environment-appropriate values:

   • Auditor_Names_List

   • Document_Types_List

   • Document_Types_Requested_List

   • Leader_Name_List

   • Survey_Type_List

2. Open /Services/serverstrings.js and populate all required variables. Refer to the Configuration Parameters section for a full description of each field.

Step 2 — Deploy to the Pre-Production VisualVault Environment

1. Define the required VisualVault custom SQL queries:

   • Navigate to VisualVault → Control Panel → Enterprise Tools.

   • Click Data Connections and configure the required queries.

2. Push the application code to the VisualVault pre-production environment.

3. Set all required environment variables in the deployment environment.

Step 3 — Test the Deployed Application

1. Test all Express API endpoints to confirm the API is functioning correctly.

2. Monitor application logs for errors and resolve any issues before proceeding to production.

🔧 Implementor Checklist

• Configure the client and server variables in /Services/configvariables.js and /Services/serverstrings.js

• Define custom SQL queries in VisualVault Control Panel under Enterprise Tools → Data Connections

• Deploy application code with configured environment variables

• Verify application is accessible from the VisualVault landing page

Execution Flow

The following describes the runtime sequence from user access through document retrieval.

Application Initialization

1. User navigates to the VisualVault login page and authenticates.

2. User accesses the Audit screen via the left side menu on the landing page.

3. VisualVault appends the user login token and authentication token to the application URL.

4. The Node.js app reads the tokens, validates the user's identity, and renders the application UI.

5. The app makes an initial API call to VisualVault to determine role-based access and renders the interface conditionally based on the user's group membership.

🔍 Troubleshooting Note: If the app fails to load or displays an authentication error, verify that the user login token and authentication token are correctly appended to the Content URL in the Page Viewer widget. Also confirm that AUTH_VAULT_URL and all token-related variables in /Services/serverstrings.js are correctly set for the target environment.

Document Search

1. In the search screen, enter an employee name in the search field.

2. Press Enter or click the Search button to execute the query.

3. The application submits the search to /api/documents and retrieves matching records.

4. Results are displayed in the Kendo UI grid, which includes the following fields:

   Column / Field	Description
   Employee Name	Full name of the matching employee
   Employee Number	Unique identifier for the employee record
   Document Type	Category of the associated document
   Actions	Links to open documents in the VisualVault document viewer

5. Use the Kendo grid's built-in pagination and sorting controls to navigate large result sets.

6. Click a document link to open it in the integrated VisualVault document viewer.

7. Optionally, use the Export to Excel toolbar button to download the grid data as an Excel file.

🔍 Troubleshooting Note: If search results are missing or incorrect, confirm that the custom SQL queries are correctly defined in VisualVault → Control Panel → Enterprise Tools → Data Connections, and that the user's role-based permissions are correctly configured to scope their visible records.

Related Resources

• Github Repository: HRSurvey (private)

• Related Articles

  • User Manual for Audits