🕒 TimeExcelSheet Model Documentation


📚 Table of Contents

  1. Overview & Purpose
  2. Key Functional Areas
  3. Dependencies & Technologies
  4. Data Model: TimeExcelSheet
  5. Usage Scenarios & Examples
  6. Helper Methods & Utilities
  7. Error Handling & Validation
  8. Third-party Integrations
  9. 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.DataAnnotations for 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! 🎉