🕒 TimeExcelSheet Model Documentation
📚 Table of Contents
- Overview & Purpose
- Key Functional Areas
- Dependencies & Technologies
- Data Model: TimeExcelSheet
- Usage Scenarios & Examples
- Helper Methods & Utilities
- Error Handling & Validation
- Third-party Integrations
- Conclusion
1. Overview & Purpose
The TimeExcelSheet class is a Plain Old CLR Object (POCO) within the IrbyImaging.UI.Models namespace. It represents a single row of time-entry data—often exported to or imported from an Excel worksheet—comprising employee work details such as hours worked, job codes, and approval information.
Intended Use:
- Populate from an Excel spreadsheet when importing time entries.
- Serialize to Excel for reporting or payroll systems.
- Bind to UI components (e.g., data grids) for display and editing in the front-end.
2. Key Functional Areas
- 📑 Data Mapping: Encapsulates Excel columns as strongly typed string properties.
- 🔄 Serialization: Feeds into Excel-reading/writing libraries for batch operations.
- 👩💻 UI Binding: Serves as a ViewModel in MVVM/MVC patterns for time-entry forms.
3. Dependencies & Technologies
This model has no direct dependencies—it’s a simple data container. However, typical workflows include:
- Excel Processing Libraries:
- EPPlus
- ClosedXML
- Serialization:
- Newtonsoft.Json (if exporting/importing JSON)
- UI Frameworks:
- ASP.NET MVC
- WPF / WinForms
4. Data Model: TimeExcelSheet
namespace IrbyImaging.UI.Models
{
public class TimeExcelSheet
{
public string EmployeeNumber { get; set; }
public string AlphaName { get; set; }
public string Pay { get; set; }
public string PayTypeDescription { get; set; }
public string Hours { get; set; }
public string AccountNumber { get; set; }
public string SubType { get; set; }
public string SubLedger { get; set; }
public string JobType { get; set; }
public string EquipmentWorkedOn { get; set; }
public string WorkDate { get; set; }
public string RecordType { get; set; }
public string OverrideRate { get; set; }
public string ApprovedBy { get; set; }
public string ApprovedDate { get; set; }
}
}
Class Diagram (UML)
classDiagram
class TimeExcelSheet {
+string EmployeeNumber
+string AlphaName
+string Pay
+string PayTypeDescription
+string Hours
+string AccountNumber
+string SubType
+string SubLedger
+string JobType
+string EquipmentWorkedOn
+string WorkDate
+string RecordType
+string OverrideRate
+string ApprovedBy
+string ApprovedDate
}
Property Reference Table
| Property | Description |
|---|---|
| EmployeeNumber | Unique ID of the employee (e.g., “E12345”). |
| AlphaName | Employee name in “LAST, FIRST” format. |
| Pay | Pay code or rate identifier. |
| PayTypeDescription | Human-readable pay type (e.g., “Overtime”, “Regular”). |
| Hours | Number of hours worked (e.g., “8.00”). |
| AccountNumber | Cost center or project account. |
| SubType | Subclassification of the entry (e.g., “Holiday”, “Sick”). |
| SubLedger | Ledger grouping for financial tracking. |
| JobType | Task or job code. |
| EquipmentWorkedOn | Asset or machine the employee worked on. |
| WorkDate | Date of work performed (MM/dd/yyyy). |
| RecordType | Type of record (e.g., “TimeEntry”, “PTO”). |
| OverrideRate | Custom pay rate override, if applicable. |
| ApprovedBy | Approver’s username or ID. |
| ApprovedDate | Date/time of approval (MM/dd/yyyy HH:mm). |
5. Usage Scenarios & Examples
Reading from Excel (EPPlus) 📊
using OfficeOpenXml;
using IrbyImaging.UI.Models;
public List<TimeExcelSheet> LoadTimeEntries(string filePath)
{
var list = new List<TimeExcelSheet>();
ExcelPackage.LicenseContext = LicenseContext.NonCommercial;
using var package = new ExcelPackage(new FileInfo(filePath));
var ws = package.Workbook.Worksheets.First();
// Assume header row at row 1
for(int row = 2; row <= ws.Dimension.End.Row; row++)
{
list.Add(new TimeExcelSheet {
EmployeeNumber = ws.Cells[row, 1].Text,
AlphaName = ws.Cells[row, 2].Text,
Pay = ws.Cells[row, 3].Text,
PayTypeDescription= ws.Cells[row, 4].Text,
Hours = ws.Cells[row, 5].Text,
AccountNumber = ws.Cells[row, 6].Text,
SubType = ws.Cells[row, 7].Text,
SubLedger = ws.Cells[row, 8].Text,
JobType = ws.Cells[row, 9].Text,
EquipmentWorkedOn = ws.Cells[row,10].Text,
WorkDate = ws.Cells[row,11].Text,
RecordType = ws.Cells[row,12].Text,
OverrideRate = ws.Cells[row,13].Text,
ApprovedBy = ws.Cells[row,14].Text,
ApprovedDate = ws.Cells[row,15].Text
});
}
return list;
}
Writing to Excel (ClosedXML) 📈
using ClosedXML.Excel;
public void ExportTimeEntries(string filePath, List<TimeExcelSheet> entries)
{
using var workbook = new XLWorkbook();
var ws = workbook.Worksheets.Add("TimeSheet");
// Header
var headers = typeof(TimeExcelSheet).GetProperties();
for(int i = 0; i < headers.Length; i++)
ws.Cell(1, i+1).Value = headers[i].Name;
// Data
for(int r = 0; r < entries.Count; r++)
{
var item = entries[r];
ws.Cell(r+2, 1).Value = item.EmployeeNumber;
ws.Cell(r+2, 2).Value = item.AlphaName;
// ... repeat for each property ...
}
workbook.SaveAs(filePath);
}
6. Helper Methods & Utilities
While TimeExcelSheet itself contains no methods, you can augment it with:
- Factory Methods for conversions (e.g.,
FromCsv(string[] row)). - Extension Methods for bulk transformations (e.g.,
.ToDataTable()). - Validation Attributes via
System.ComponentModel.DataAnnotationsfor UI binding.
7. Error Handling & Validation
- Null / Empty Values
Ensure the importer gracefully handles missing columns or blank cells. - Data Conversion
· Wrap date parsing (DateTime.TryParse) and numeric conversion (decimal.TryParse) in safe methods. - Validation
Leverage annotations:[Required, RegularExpression(@"\d{2}/\d{2}/\d{4}")] public string WorkDate { get; set; }
8. Third-party Integrations
- EPPlus: Excel import/export without Microsoft Office.
- ClosedXML: Fluent interface for Excel creation/formatting.
- Newtonsoft.Json: (Optional) for JSON serialization of time entries.
9. Conclusion
The TimeExcelSheet class is a lightweight, flexible ViewModel/DataModel designed for Excel-based time tracking workflows. By abstracting each Excel column into a property, it simplifies data exchange, UI binding, and integration with downstream payroll or financial systems.
🚀 Next Steps
- Enhance with data annotations for validation.
- Create mapping utilities to convert between domain entities and this model.
- Incorporate unit tests to verify import/export logic.
Happy coding! 🎉