š 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
- Overview & Purpose
- Dependencies & Technologies
- Key Functional Areas
- API Endpoints & Actions
- View Models & Data Models
- Helper Methods & Utilities
- Error Handling & Return Types
- Sample Code Blocks & Usage
- UML Class Diagram
- 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
-
Index & BulkCreate
- Load dropādowns: Employees, Jobs, Cost Codes, Pay Codes, Equipment
- Render initial timeāentry UI.
-
BulkSave & SaveMechanicTimeSheet
- Parse JSON grid of mechanic timesheet entries
- Create new or update existing MechanicTimesheet entities
-
TimeReview, TimeApproval & ViewTimeSheet
- Supervisors review and approve submitted mechanic times
- Group by employee or date.
-
Excel & Payroll Generation
CreateExcel(),GeneratePayrollFile(),SaveFringeBenefits2()- Complex SQL merges data from JDE tables and local entries
- Build multiāsheet Excel workbooks with IronXL
-
Field Log & Crew Management
CreateFieldLog(),CreateFieldLogDraft()ā Field technician time logsCreateCrew(),ViewCrews(),EditCrew(),DeleteCrew()ā Define employee crews
-
Fringe Benefit Management
FringeBenefitSheet(),JobClassificationUpload(),CostCodeUpload(),- Heavy SQL for monthly benefits & credits.
-
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 fromDataRow.InsertLineBreaks(string text, int maxLineLength)
Inserts\nat 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=trueon 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! š