HR Automation - Folder Creation/Updates

Overview

The HR Automation is a feature of the modular solution Employee Records Management (ERM). It is a microservice included in the database template which the System Administrator will use when setting up a clone database for the implementation. This microservice retrieves values from the specified fields within the Employee Master Form and does not require additional configuration.

Feature Objective

The HR Automation feature streamlines the management of employee records by automatically creating and maintaining Document Library folders in response to changes in the Employee Master Form.

Key capabilities include:

• Initial Folder Creation — Automatically creates an Employee Document Library folder upon initial creation of an Employee Master iForm in VisualVault, placed under the appropriate alphabetical node based on last name, using the naming convention "Last Name, First Name, Unique Identifier."

• Folder Updates — Upon manual modification of an existing Employee Master iForm, updates the employee folder to reflect changes to first name, last name, or Employee ID.

• Status-Based Movement — Moves employee folders between the Active and Terminated nodes in the document library when an employee's status changes.

• Document Import — Imports documents from sFTP into the employee's Onboarding folder, routing exceptions to /Human Resources/Employee Files/Exceptions.

• Security Management — Applies and maintains role-based access controls across all employee folder structures according to a defined Security Matrix.

Technical Architecture

Application Stack

Integration with VisualVault

The application is included in the source database and activated as part of the HR-1 solution setup. It reads employee data from CSV files retrieved via sFTP and interacts with the VisualVault Platform API to create, update, and move folders within the Document Library. The Employee Master Form serves as the system of record; the app reads from and writes back to it during each execution cycle.

+-------------------------------+          +--------------------------------+
| sFTP Server                   |  import  | HR Automation App              |
|                               | -------> | (FM.HRFolderCreation)     |
|  [ CSV File(s) ]              |          |                                |
|    Employee records           |          | Validates via App.config       |
|    (LastName, FirstName,      |          | Reads/writes Employee Master   |
|     EmployeeID, Status, Type) |          | Form and Document Library      |
+-------------------------------+          +--------------------------------+

Data Flow

📋 Coming Soon: A diagram illustrating the full API call sequence and data flow between the HR Automation app, the VisualVault platform, the Employee Master Form, and the sFTP file source will be added here.

Security Matrix

🔍 Troubleshooting Note: If a user reports missing access to an employee folder or subfolder, first confirm that the correct security group (HR, Employee, or Executive — matching the employee type) has been assigned in VisualVault. Mismatches in employee type values between the CSV and configured EmployeeTypeValues are the most common cause.

Configuration Parameters

🔧 Implementor Note: All parameters below must be configured in the App.config file before deployment. Values are environment-specific and should be confirmed with the customer prior to implementation.

App.config

<add key="ftpRemoteFileExtensionAllowed" value=".csv" />
<add key="vvDocumentLibraryRootPath" value="/Human Resources" />
<add key="vvFormTemplate" value="Employee Master" />
<add key="folderIndexFields" value="Employee First Name,Employee Last Name,Unique Employee ID Number,Employee Status" />
<add key="formFields" value="First Name,Last Name,Employee ID,Employee Status,Employee Type,Needs Compliance Review" />
<add key="queryName" value="GetFolders" />
<add key="folderPathFormField" value="Folder Path" />
<add key="SplitCharacter" value="," />
<add key="TrimCharacter" value="&quot;" />
<add key="LastNameColumnName" value="Employee Last Name" />
<add key="FirstNameColumnName" value="Employee First Name" />
<add key="EmployeeIdColumnName" value="Employee UNIQUE ID" />
<add key="EmployeeTypeColumnName" value="Employee Type" />
<add key="EmployeeStatusColumnName" value="Employee Status" />
<add key="EmployeeTypeValues" value="Employee,Executive,HR" />

🔍 Troubleshooting Note: The vvDocumentLibraryRootPath value must match the exact path of the Human Resources root folder as configured in the VisualVault Document Library. Do not include a trailing slash.

Specs

• Need to set Client system import for 23 hrs after standard HR import to allow for folder creation

• Documents will go in the Onboarding folder in each Employee File

• Exceptions will go to /Human Resources/Employee Files/Exceptions

• Items will import from sFTP

Indexes

Walkthrough

Developer Setup

The following steps require repository access and a code editor. These are performed by a developer prior to deployment.

Step 1 — Clone the Repository

Clone the VisualVault.Net.FileManager repository from GitHub and navigate to the FM/FM.CapeCodFolderCreation directory.

https://github.com/VisualVault/VisualVault.Net.FileManager/tree/04e83116a7d83de47cba09c7e69e708d8ad5517a/FM/FM.CapeCodFolderCreation

Step 2 — Configure App.config Parameters

1. Open App.config and update all parameters listed in the Configuration Parameters section with the customer's environment-specific values.

2. Confirm that vvDocumentLibraryRootPath reflects the exact path to the Human Resources root folder in the target VisualVault environment.

3. Confirm that EmployeeTypeValues matches the exact employee type strings used in the customer's CSV export.

🔍 Troubleshooting Note: vvDocumentLibraryRootPath should be a path only, no trailing slash and no full URL.

Step 3 — Configure Import Timing

Set the client system import schedule to run 23 hours after the standard HR import. This delay ensures that employee folders are created before documents are imported into them.

🔍 Troubleshooting Note: Documents are placed in the Onboarding folder within each employee's file. Exceptions are routed to /Human Resources/Employee Files/Exceptions.

Implementor Configuration

The following steps are performed by an implementor in VisualVault after developer setup is complete.

🔧 Implementor Checklist

• Verify that security groups created in VisualVault match the Security Matrix.

• Verify security groups were populated with appropriate users.

• Configure the sFTP server with credentials and remote path matching App.config FTP settings.

Execution Flow

The following describes the runtime sequence from file detection through folder creation or update completion.

Application Initialization

1. The application reads all configuration values from App.config.

2. The Template ID for the Employee Master Form is retrieved from VisualVault.

3. All files present at the configured ftpRemotePath are retrieved.

4. For each file, the application verifies the file extension is permitted (.csv only).

5. The most recently updated backup file is retrieved from _BackupFile to use as a comparison baseline.

🔍 Troubleshooting Note: If the application fails to initialize, first verify that App.config values are correct and that the VisualVault platform API is reachable. If no files are processed, confirm that the sFTP path is accessible and that files use the .csv extension.

CSV Processing and Form Sync

1. For each row in the CSV file, the application compares the current row against the same employee ID in the previous backup file.

2. Rows with no changes are skipped.

3. For rows with changes, the application searches VisualVault for an existing Employee Master Form matching the employee ID.

   • If no form exists, a new Employee Master Form is created using the row's first name, last name, ID, and status values. The generated folder path is saved to the form.

   • If a form exists, it is updated with the new values from the row. The folder path is recalculated and saved.

Folder Creation and Movement

1. Using the row data, the application generates the expected folder path and name using the convention: Last Name, First Name, Unique Identifier.

2. A search is performed to determine whether a folder with that name already exists in the Document Library (under Active or Terminated).

3. If the folder exists:

   • The application compares the existing folder path to the generated path.

   • If the paths match, no action is taken.

   • If the paths differ (e.g., employee status has changed, or a name has been updated):

     • The parent folder (alphabetical last name initial) is validated; it is created if missing.

     • The folder and all documents are moved to the new path.

     • Index fields and security group assignments are updated for the folder, all subfolders, and all documents within those subfolders.

4. If the folder does not exist:

   • The /Human Resources/HR Template folder structure is copied to the new employee folder path.

   • The folder name and description are updated using the generated folder name.

   • Index fields for the new folder are populated with first name, last name, and unique employee ID.

   • Security group assignments are applied to the folder and all subfolders per the Security Matrix.

5. After processing, the source CSV file is moved from the root FTP folder to the backup folder (remoteFolder/_BackUp).

6. The process ends.

🔍 Troubleshooting Note: If a folder is not created or moved as expected, confirm that the HR Template folder exists at the correct path and that the GetFolders query is returning results. Verify that the employee's status and type values in the CSV match the configured EmployeeStatusColumnName and EmployeeTypeValues parameters exactly.

Document Import

Documents are imported from sFTP and placed into the Onboarding subfolder within each employee's Document Library folder. Files must follow the naming conventions below to ensure correct index field population.

🔍 Troubleshooting Note: If documents are not appearing in the expected employee folder, confirm the file naming convention matches the format above and that the import is scheduled at least 23 hours after the standard HR import. Files that cannot be matched to an employee record will be routed to /Human Resources/Employee Files/Exceptions.

Related Resources

• Github Repository: HR Folder Creation