EmployeesController.cs Documentation 🚀
Table of Contents 📑
- Overview & Purpose
- Dependencies & Technologies
- Class Diagram
- Key Functional Areas
- Request & Response Flow
- Data Models & View Models
- Helper Methods & Utilities
- Error Handling & Return Types
- Third-Party Integrations
- Usage Examples
- UML Sequence Diagram
- Conclusion
1. Overview & Purpose 🎯
The EmployeesController is an ASP.NET Core MVC controller responsible for managing employee-related operations within the Irby Imaging application.
It exposes endpoints for:
- Listing employees
- Viewing employee details
- Tracking terminated employees with outstanding assets
- Updating employee notes
- Resetting user passwords and triggering email notifications
It extends BaseController, leveraging shared resources such as IrbyContext (EF Core DB context) and configuration.
2. Dependencies & Technologies 🧰
| Category | Items |
|---|---|
| .NET & ASP.NET Core | Microsoft.AspNetCore.Mvc, Microsoft.AspNetCore.Authorization, Microsoft.Extensions.Configuration |
| Entity Framework Core | Microsoft.EntityFrameworkCore |
| Business & Service Layers | IEmployeeAndFieldOfficeManager, IOutstandingAssetMapper, IEmailGenerationService |
| Data & View Models | DomainClasses.Employee, OutstandingViewModel |
| Utilities | MailService, EmployeeStatus |
| Third-Party Libraries | SkiaSharp, Newtonsoft.Json, Azure.Identity, Microsoft.Graph |
| Identity & Email | Microsoft.AspNetCore.Identity.UI.Services |
3. Class Diagram 📊
classDiagram
class EmployeesController {
- IEmployeeAndFieldOfficeManager _manager
- IOutstandingAssetMapper _mapper
- IrbyContext _context
- IEmailGenerationService _emailGeneration
- IConfiguration _configuration
+ Task<IActionResult> Index(string search)
+ Task<IActionResult> Details(Guid? id)
+ Task<IActionResult> Outstanding(string search)
+ Task<IActionResult> EmployeeNotes(string employeeNotes, Guid employeeId)
+ Task<IActionResult> ResetPassword(DomainClasses.Employee employee)
+ Task<IActionResult> ResetPassword(Guid employeeId, bool pWReset, DateTime pWResetDate)
}
interface IEmployeeAndFieldOfficeManager
interface IOutstandingAssetMapper
interface IEmailGenerationService
class IrbyContext
EmployeesController --> IEmployeeAndFieldOfficeManager
EmployeesController --> IOutstandingAssetMapper
EmployeesController --> IrbyContext
EmployeesController --> IEmailGenerationService
4. Key Functional Areas 📂
4.1 Index (List Employees) 🗂️
Signature
public async Task<IActionResult> Index(string search)
Description
- Retrieves a list of employees, optionally filtered by search term.
- Delegates to
_manager.GetEmployees_Async(search).
Code Snippet
public async Task<IActionResult> Index(string search)
{
var employees = await _manager.GetEmployees_Async(search);
return View(employees);
}
View: Views/Employees/Index.cshtml
4.2 Details (Employee Information) 🔍
Signature
[Route("Employees/Details/{id:Guid?}")]
public async Task<IActionResult> Details(Guid? id)
Description
- Fetches details of an employee by
id. - Returns 404 NotFound if
idis null or employee not found.
Code Snippet
if (id == null) return NotFound();
var employee = await _manager.GetEmployeeById_Async(id);
if (employee == null) return NotFound();
return View(employee);
View: Views/Employees/Details.cshtml
4.3 Outstanding (Terminated Employees & Assets) 💰
Signature
public async Task<IActionResult> Outstanding(string search)
Description
- Lists terminated employees with outstanding assets.
- Uses
_manager.GetTerminatedEmployeesWithAssets(search)and maps to view model via_mapper.TerminatedEmployeesWithAssetsToOutstandingViewModel(...).
Code Snippet
var employees = await _manager.GetTerminatedEmployeesWithAssets(search);
var viewModel = _mapper.TerminatedEmployeesWithAssetsToOutstandingViewModel(employees);
return View(viewModel);
View: Views/Employees/Outstanding.cshtml
4.4 EmployeeNotes (Update Notes) 📝
Signature
[HttpPost]
public async Task<IActionResult> EmployeeNotes(string employeeNotes, Guid employeeId)
Description
- Updates the EmployeeNotes field for an employee.
- Redirects back to Index.
Code Snippet
var employee = await _manager.GetEmployeeById_Async(employeeId);
if (employee == null) return RedirectToAction("Index");
employee.EmployeeNotes = employeeNotes;
await _manager.UpdateEmployee_Async(employee);
return RedirectToAction("Index");
4.5 ResetPassword (GET) 🔑
Signature
[Route("Employees/ResetPassword")]
[HttpGet]
public async Task<IActionResult> ResetPassword(DomainClasses.Employee employee)
Description
- Renders a form to search and select an active employee for password reset.
- Populates
ViewBag.Employeesfor a dropdown list. - If
employee.EmployeeIdis supplied, fetches employee details intoViewBag.SelectedEmployee.
Code Snippet
ViewBag.Employees = _context.Employees
.Where(e => e.Status != EmployeeStatus.Terminated)
.Select(e => new SelectListItem {
Value = e.EmployeeId.ToString(),
Text = $"{e.JdeNumber}-{e.DisplayName}"
}).ToList();
return View();
View: Views/Employees/ResetPassword.cshtml
4.6 ResetPassword (POST) ✉️
Signature
[Route("Employees/ResetPassword")]
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> ResetPassword(Guid employeeId, bool pWReset, DateTime pWResetDate)
Description
- Validates the model state.
- Updates
PWResetandPWResetDateon the selected employee. - Persists changes via EF Core.
- Generates an email using
_emailGeneration.ForPasswordReset(...). - Sends email via
MailService.SendEmail(...). - Redirects back to ResetPassword on success.
Code Snippet
var existingEmployee = await _context.Employees
.FirstOrDefaultAsync(e => e.EmployeeId == employeeId);
existingEmployee.PWReset = pWReset;
existingEmployee.PWResetDate = pWResetDate;
_context.Update(existingEmployee);
await _context.SaveChangesAsync();
var (to, subject, body) = _emailGeneration.ForPasswordReset(existingEmployee);
var mail = new MailService();
await mail.SendEmail(to, subject, body,
filesToAttach: new List<IFormFile>(),
isHtml: true, cc: null, bcc: "",
clientId: _configuration["HelpDeskEmailClientId"],
tenantId: _configuration["Tenant"],
clientSecret: _configuration["HelpDeskEmailClientSecret"]);
5. Request & Response Flow 🔄
sequenceDiagram
participant Browser
participant EmployeesController
participant Manager
participant DbContext
participant EmailGen
participant MailService
Browser->>EmployeesController: POST /Employees/ResetPassword { employeeId, pWReset, pWResetDate }
EmployeesController->>DbContext: Find Employee by Id
DbContext-->>EmployeesController: Employee entity
EmployeesController->>DbContext: Update fields & SaveChanges
EmployeesController->>EmailGen: ForPasswordReset(employee)
EmailGen-->>EmployeesController: (to, subject, body)
EmployeesController->>MailService: SendEmail(...)
MailService-->>Browser: 302 Redirect to /Employees/ResetPassword
6. Data Models & View Models ⚙️
| Model / VM | Purpose |
|---|---|
| DomainClasses.Employee | Core employee entity in the database. |
| OutstandingViewModel | Combines terminated employee data + asset details. |
| SelectListItem | Utility for <select> dropdown in ResetPassword view. |
7. Helper Methods & Utilities 🛠️
- IEmployeeAndFieldOfficeManager:
Abstracts business logic related to employees & field offices. - IOutstandingAssetMapper:
Maps domain entities to view models (TerminatedEmployeesWithAssetsToOutstandingViewModel). - IEmailGenerationService:
Builds email address, subject, and body for various notifications. - MailService:
Sends email via Azure/Microsoft Graph using client credentials. - EmployeeStatus:
Enum (Active,Terminated, etc.) used to filter employees.
8. Error Handling & Return Types ⚠️
- NotFound (404):
DetailsreturnsNotFound()ifidis null or entity missing.
- Redirects:
- After successful updates (Notes, Password Reset), user is redirected to summary pages.
- ModelState Validation:
ResetPassword (POST)checksModelState.IsValidbefore processing.
- ViewBag.SubmissionError:
- Displays friendly error if employee lookup fails.
9. Third-Party Integrations 🌐
- Azure.Identity & Microsoft.Graph:
- Potentially used in
MailServicefor sending emails via Graph API.
- Potentially used in
- SkiaSharp:
- (Imported) For server-side image processing—currently unused in this controller.
- Newtonsoft.Json:
- (Imported) For JSON serialization—usage may appear in other controllers/services.
10. Usage Examples 🖥️
10.1 List Employees
Navigate to:
GET /Employees/Index?search=john
Yields a paged list of employees matching “john”.
10.2 Reset Password Workflow
- GET
/Employees/ResetPassword
Shows dropdown of active employees. - Select an employee and submit form (POST).
- POST
/Employees/ResetPassword- Body:
employeeId={GUID}&pWReset=true&pWResetDate=2022-09-01 - Triggers email.
- Body:
11. UML Sequence Diagram 📈
sequenceDiagram
actor User
participant Controller as EmployeesController
participant Manager
participant Db as IrbyContext
participant EmailSvc as IEmailGenerationService
participant Mail as MailService
User->>Controller: GET /Employees/Outstanding?search=smith
Controller->>Manager: GetTerminatedEmployeesWithAssets("smith")
Manager->>Db: Query terminated + assets
Db-->>Manager: List<TerminatedEmployee>
Manager-->>Controller: domainModels
Controller->>Mapper: Map to OutstandingViewModel
Mapper-->>Controller: viewModel
Controller-->>User: View(viewModel)
12. Conclusion ✅
The EmployeesController cleanly separates concerns by delegating business operations to services and mappers, using EF Core for data persistence, and providing a user-friendly MVC interface for managing employee records—particularly focusing on password resets, employee notes, and tracking outstanding assets for terminated personnel. The code is structured for testability, extensibility, and maintainability within the Irby Imaging application stack.
Feel free to explore other related controllers and services to get the full picture of the application’s architecture!