EmployeesController.cs Documentation 🚀


Table of Contents 📑

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Class Diagram
  4. Key Functional Areas
  5. Request & Response Flow
  6. Data Models & View Models
  7. Helper Methods & Utilities
  8. Error Handling & Return Types
  9. Third-Party Integrations
  10. Usage Examples
  11. UML Sequence Diagram
  12. 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 id is 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.Employees for a dropdown list.
  • If employee.EmployeeId is supplied, fetches employee details into ViewBag.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

  1. Validates the model state.
  2. Updates PWReset and PWResetDate on the selected employee.
  3. Persists changes via EF Core.
  4. Generates an email using _emailGeneration.ForPasswordReset(...).
  5. Sends email via MailService.SendEmail(...).
  6. 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):
    • Details returns NotFound() if id is null or entity missing.
  • Redirects:
    • After successful updates (Notes, Password Reset), user is redirected to summary pages.
  • ModelState Validation:
    • ResetPassword (POST) checks ModelState.IsValid before processing.
  • ViewBag.SubmissionError:
    • Displays friendly error if employee lookup fails.

9. Third-Party Integrations 🌐

  • Azure.Identity & Microsoft.Graph:
    • Potentially used in MailService for sending emails via Graph API.
  • 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

  1. GET /Employees/ResetPassword
    Shows dropdown of active employees.
  2. Select an employee and submit form (POST).
  3. POST /Employees/ResetPassword
    • Body: employeeId={GUID}&pWReset=true&pWResetDate=2022-09-01
    • Triggers email.

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!