šŸ“‘ TimeEntryController Documentation

Welcome to the comprehensive documentation for
IrbyImaging.UI.Controllers.TimeEntryController.cs,
the heart of time‐entry, timesheet, payroll and fringe‑benefit management in the Irby Imaging application.


Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. API Endpoints & Actions
  5. View Models & Data Models
  6. Helper Methods & Utilities
  7. Error Handling & Return Types
  8. Sample Code Blocks & Usage
  9. UML Class Diagram
  10. Conclusion

Overview & Purpose

TimeEntryController orchestrates:

  • Mechanic Timesheets (create, bulk upload, review, approve, export)
  • Field Logs / Field Timesheets (create, draft, submit, export to Excel)
  • Payroll / Fringe Benefit Sheets (compute benefits, generate reports)
  • Crew Management (create, view, edit, delete crews)

It connects UI views with the EF Core IrbyContext, leverages Azure AD for user info, and generates Excel reports using IronXL & OpenXML.


Dependencies & Technologies

Dependency Usage
Microsoft.AspNetCore.Mvc MVC controllers & actions
Microsoft.EntityFrameworkCore Data access (IrbyContext)
Microsoft.Extensions.Configuration Config settings & Azure AD integration
Newtonsoft.Json (JArray & JObject) Parse JSON grids for bulk operations
Syncfusion.EJ2.Base Kendo‑style grids & dropdowns
IronXL Excel workbook creation & styling
System.Data.SqlClient & SMO Advanced SQL queries & temp‑table reporting
iTextSharp PDF parsing (if needed)
ClosedXML & OpenXML (Word/Spreadsheet) Alternative Excel/Word exports

Key Functional Areas

  1. Index & BulkCreate

    • Load drop‑downs: Employees, Jobs, Cost Codes, Pay Codes, Equipment
    • Render initial time‐entry UI.
  2. BulkSave & SaveMechanicTimeSheet

    • Parse JSON grid of mechanic timesheet entries
    • Create new or update existing MechanicTimesheet entities
  3. TimeReview, TimeApproval & ViewTimeSheet

    • Supervisors review and approve submitted mechanic times
    • Group by employee or date.
  4. Excel & Payroll Generation

    • CreateExcel(), GeneratePayrollFile(), SaveFringeBenefits2()
    • Complex SQL merges data from JDE tables and local entries
    • Build multi‑sheet Excel workbooks with IronXL
  5. Field Log & Crew Management

    • CreateFieldLog(), CreateFieldLogDraft() – Field technician time logs
    • CreateCrew(), ViewCrews(), EditCrew(), DeleteCrew() – Define employee crews
  6. Fringe Benefit Management

    • FringeBenefitSheet(), JobClassificationUpload(), CostCodeUpload(),
    • Heavy SQL for monthly benefits & credits.
  7. Search & Filtering

    • FilterByEmployee(), FilterByDay(), FilterWorkOrders()
    • Server‐side filtering for grids.

API Endpoints & Actions

Action HTTP Verb Route Purpose
Index GET /TimeEntry/Index Load main time entry page
BulkCreate GET /TimeEntry/BulkCreate Mechanic bulk timesheet UI
BulkSave POST /TimeEntry/BulkSave Save grid of mechanic timesheet entries
TimeReview GET /TimeEntry/TimeReview List timesheets awaiting review
TimeApproval GET /TimeEntry/TimeApproval Supervisor approval queue
ViewTimeSheet/{id} GET /TimeEntry/ViewTimeSheet/{id} View single employee’s timesheet entries
SaveMechanicTimeSheet POST /TimeEntry/SaveMechanicTimeSheet Save (draft) mechanic timesheet
SendTimeSheetToReview POST /TimeEntry/SendTimeSheetToReview Submit mechanic timesheet for review
ApproveTimesheet POST /TimeEntry/ApproveTimesheet Approve multiple mechanic entries
RejectTimesheet POST /TimeEntry/RejectTimesheet Reject mechanic entries with comment
CreateFieldLog GET/POST /TimeEntry/CreateFieldLog Initialize field log
CreateFieldLogDraft GET /TimeEntry/CreateFieldLogDraft Draft field log with job & equipment
ExportFieldTimesheet/{id} GET /TimeEntry/ExportFieldTimesheet/{id} Download Excel of a field timesheet
ExportBulkTimesheets POST /TimeEntry/ExportBulkTimesheets Download many field timesheets by date range
FringeBenefitSheet GET /TimeEntry/FringeBenefitSheet UI for fringe‐benefit calculations
JobClassificationUpload GET/POST /TimeEntry/JobClassificationUpload Manage job fringe classifications
CostCodeUpload GET/POST /TimeEntry/CostCodeUpload Manage cost codes for fringe
CopyTimesheet/{id} GET /TimeEntry/CopyTimesheet/{id} Generate ā€œnewā€ draft from existing timesheet
CreateCrew GET/POST /TimeEntry/CreateCrew Add new crew + equipment/employees
ViewCrews GET /TimeEntry/ViewCrews List existing crews
EditCrew/{id} GET/POST /TimeEntry/EditCrew/{id} Modify crew definitions
DeleteCrew POST /TimeEntry/DeleteCrew Soft‐delete a crew

View Models & Data Models

Core Data Models (DomainClasses)

  • MechanicTimesheet
    Captures individual mechanic entries:

    public class MechanicTimesheet {
      public Guid Id { get; set; }
      public Guid EmployeeId { get; set; }
      public string Job { get; set; }
      public string CostType { get; set; }
      public string PayCode { get; set; }
      public string RegularTime { get; set; }
      public DateTime StartDate { get; set; }
      public TimeSheetStatus Status { get; set; }
      // …etc.
    }
    
  • FieldTimesheet, EmployeeTimesheet, WorkEntry, EquipmentTimesheet, EquipmentEntry
    Represent hierarchical field log structure.

  • PayrollFringe, JobClassification, CostCode
    Fringe benefit and payroll entities.

Key View Models

  • TimeEntryListViewModel – flatten field timesheet list for UI tables.
  • CreateFieldTimesheetViewModel – dropdowns & forms for new field log.
  • CrewViewModel – job, employees, cost codes & equipment selectors.
  • FringeBenefitModel & FringeBenefitEntry – payload for fringe‐benefit POST.

Helper Methods & Utilities

  • GetSafeString(), GetSafeDateTime(), GetSafeDouble(), GetSafeBoolean()
    Uniform null checks & conversions from DataRow.
  • InsertLineBreaks(string text, int maxLineLength)
    Inserts \n at word boundaries for Excel headers.
  • GetExcelColumnName(int columnNumber)
    Convert numeric index to Excel column (A,B,…,AA,…).
  • GetUniqueFilePath(string path)
    Prevent file‐overwrite by appending (1), (2), …

Error Handling & Return Types

  • Try/Catch around save/export operations – return Content("Save Failed") or JSON error payload.
  • ModelState validation on [FromBody] MVC POST – returns BadRequest(ModelState).
  • Soft‐delete sets IsDeleted=true on crews/timesheets.

Sample Code Blocks & Usage

Bulk Save of Mechanic Timesheets

[HttpPost]
public ContentResult BulkSave(string grid, string workDate) {
  try {
    var gridValues = JArray.Parse(grid);
    var identity = User.Claims.ElementAt(1).Value;
    int newRef = _context.MechanicTimesheet.Max(m=>m.ReferenceNumber)+1;
    foreach(var record in gridValues) {
      var emp = Guid.Parse((string)record["EmployeeId"]);
      var ts = new MechanicTimesheet {
        Id = Guid.NewGuid(),
        EmployeeId = emp,
        SubmittedBy = identity,
        StartDate = DateTime.Parse(workDate),
        Job = (string)record["Job"],
        PayCode = (string)record["PayCode"],
        CostType = (string)record["CostType"],
        RegularTime = (string)record["RegularTime"],
        Status = TimeSheetStatus.Submitted,
        ReferenceNumber = newRef
      };
      _context.Add(ts);
    }
    _context.SaveChanges();
    return Content("Save Successful");
  }
  catch {
    return Content("Save Failed");
  }
}

Generating a Payroll Excel

public IActionResult GeneratePayrollFile(string jobId, DateTime? selectedDate) {
  // 1) Query Job & Set Up IronXL workbook
  var job = _ctx.Jobs.Find(Guid.Parse(jobId));
  var sheet = workbook.CreateWorkSheet($"WE {selectedDate:MM-dd-yyyy}");
  // 2) Fill header rows: Contractor, Address, Week ending…
  sheet["B1:C1"].Merge().Value = "Irby Construction Company";
  sheet["D3:E3"].Merge().Value = $"FOR WEEK ENDING: {selectedDate:MM/dd/yyyy}";
  // 3) SQL queries via SqlCommand, build DataTable
  // 4) Render rows with styling & borders
  // 5) Return File(stream, contentType, filename)
}

UML Class Diagram

@startuml
class TimeEntryController {
  - IrbyContext _context
  - IConfiguration _configuration
  + IActionResult Index()
  + IActionResult BulkCreate()
  + ContentResult BulkSave(string, string)
  + IActionResult TimeReview()
  + IActionResult TimeApproval()
  + IActionResult CreateFieldLog(...)
  + IActionResult GeneratePayrollFile(...)
  + IActionResult CreateCrew(...)
  + IActionResult EditCrew(...)
  + IActionResult ViewCrews(...)
  // …many more actions
}
class MechanicTimesheet { + Guid Id; + Guid EmployeeId; + DateTime StartDate; + TimeSheetStatus Status; /*…*/ }
class FieldTimesheet { + Guid TimesheetId; + Guid CrewId; + string Comments; /*…*/ }
class EmployeeTimesheet { + Guid EmployeeTimesheetId; + Guid TimesheetId; + Guid EmployeeId; /*…*/ }
class WorkEntry { + Guid WorkEntryId; + Guid EmployeeTimesheetId; + DateTime WorkDate; /*…*/ }
class Crew { + Guid CrewId; + string CrewName; /*…*/ }
TimeEntryController --> MechanicTimesheet
TimeEntryController --> FieldTimesheet
TimeEntryController --> EmployeeTimesheet
TimeEntryController --> WorkEntry
TimeEntryController --> Crew
MechanicTimesheet ..> TimeSheetStatus
@enduml

Conclusion

The TimeEntryController is a multifunctional cornerstone, handling everything from daily mechanic logs to corporate payroll and fringe‐benefits reporting. It seamlessly integrates:

  • Entity Framework for data
  • Azure AD for identity
  • IronXL & SQL for Excel report generation
  • Syncfusion for rich UI components

With robust error handling, helper utilities, and extensive Excel formatting, it delivers a full‑featured, end‑to‑end time‑management and payroll solution. šŸš€

Feel free to explore each action method above, adapt snippets to your needs, and extend the helper methods for new export scenarios. Good luck! šŸ‘