πŸ“‘ SafetyEquipmentMapper Service Documentation

Assembly: IrbyImaging.UI
Author: kvamshi
Created: 03‑31‑2022
Last Modified: 03‑31‑2022


πŸ“š Table of Contents

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

🎯 Overview & Purpose

The SafetyEquipmentMapper service is responsible for transforming between business domain entities (SafetyEquipment, AssetHistory) and their corresponding UI view models (SafetyEquipmentCreateViewModel, SafetyEquipmentDetailViewModel, etc.). This separation of concerns allows:

  • Clean controllers: just call mapper to prepare data for views.
  • Reusable mapping logic: centralized in one service.
  • Consistent UI models: same shape everywhere.

It implements the ISafetyEquipmentMapper interface.


πŸ› οΈ Dependencies & Technologies

Dependency Purpose
IAssetManager Fetches domain data (models, owners, OS).
IrbyImaging.Utility.Helpers Generates select lists for dropdowns.
Newtonsoft.Json Serializes/deserializes JSON for history records.
IrbyImaging.DomainClasses Contains SafetyEquipment, AssetHistory, AssetStatus.
IrbyImaging.Models Defines the View Models (create, detail, list, edit, history).

Tech Stack:

  • C# .NET (UI Layer)
  • JSON serialization via Newtonsoft

πŸ”‘ Key Functional Areas

  1. Create Mapping

    • GenerateSafetyEquipmentCreateViewModel()
    • CreateViewModelToSafetyEquipment(viewModel)
  2. Read Mapping

    • GenerateSafetyEquipmentDetailViewModel(safetyEquipment)
    • GenerateSafetyEquipmentListViewModel(IEnumerable<SafetyEquipment>, AssetStatus)
  3. Update Mapping

    • SafetyEquipmentToEditViewModel(safetyEquipment)
    • EditViewModelToSafetyEquipment(viewModel)
  4. History Mapping

    • GenerateSafetyEquipmentHistoryViewModel(AssetHistory)
    • GenerateSafetyEquipmentHistoryListViewModel(IEnumerable<AssetHistory>)
  5. Warranty Utility

    • GetWarrantyExperationDate(SafetyEquipment)

πŸ“¦ Data Models & View Models

Domain Entity: SafetyEquipment

Property Type Description
Id Guid Unique identifier
SerialNumber string Manufacturer serial number
Status AssetStatus Current asset status
PurchaseDate DateTimeOffset Purchase date
ModelId Guid FK – equipment model
OperatingSystemId Guid FK – OS
OwnerId Guid? FK – current owner (nullable)
AssetNumber string Internal asset tag
UnitNumber string Unit-specific identifier
CpsNumber string CPS tracking number
Notes string Additional comments

View Models

ViewModel Purpose
SafetyEquipmentCreateViewModel Data for Create form (dropdown lists, pre-populated date, etc.)
SafetyEquipmentDetailViewModel Properties to Display details & warranty/status UI classes
SafetyEquipmentListViewModel Paged/filtered list details + counters (warranty warnings)
SafetyEquipmentEditViewModel Data for Edit form (pre-filled fields + dropdowns)
HistoryViewModel Single asset history entry (with deserialized SomeAsset)
HistoryListViewModel Chronological list of history entries for one asset

πŸ›  Helper Methods & Utilities

  • Generate Select Lists
    Uses Helpers.GenerateSelectListFor(...) to convert raw lookup lists into UI <select> options.

  • GetWarrantyExperationDate

    private DateTimeOffset GetWarrantyExperationDate(SafetyEquipment equipment) {
        var months = equipment.Model?.Make?.WarrantyMonths ?? 12;
        return equipment.PurchaseDate.AddMonths(months);
    }
    
    • Picks warranty period from Model.Make.WarrantyMonths (default 12 months).

⚠️ Error Handling & Return Types

  • Null Safety:

    • Owner fallback: if OwnerId is null, OwnerFullName = "ERROR" (should be handled upstream).
    • Default warranty period if missing.
  • Return Types:
    Every method returns a fully populated ViewModel or Domain entity; no exceptions are thrown here. Validation should be done before/after mapping.


🌐 Third‑Party Integrations

  • Newtonsoft.Json
    Used to deserialize the JSON-serialized properties stored in AssetHistory.SerializedProperties back to SafetyEquipment:
    SomeAsset = JsonConvert.DeserializeObject<SafetyEquipment>(history.SerializedProperties)
    

πŸ“Š UML Class Diagram

classDiagram
    IAssetManager <|.. SafetyEquipmentMapper
    ISafetyEquipmentMapper <|.. SafetyEquipmentMapper
    SafetyEquipmentMapper ..> IAssetManager
    SafetyEquipmentMapper ..> SafetyEquipmentCreateViewModel
    SafetyEquipmentMapper ..> SafetyEquipmentDetailViewModel
    SafetyEquipmentMapper ..> SafetyEquipmentListViewModel
    SafetyEquipmentMapper ..> SafetyEquipmentEditViewModel
    SafetyEquipmentMapper ..> HistoryViewModel
    SafetyEquipmentMapper ..> HistoryListViewModel
    SafetyEquipment ..> AssetHistory
    AssetHistory ..> SafetyEquipment

πŸš€ Sample Usage & Code Blocks

1. Registering in DI Container

services.AddScoped<ISafetyEquipmentMapper, SafetyEquipmentMapper>();
services.AddScoped<IAssetManager, AssetManager>();  // your implementation

2. Generating Create ViewModel in Controller

public class SafetyEquipmentController : Controller {
    private readonly ISafetyEquipmentMapper _mapper;

    public SafetyEquipmentController(ISafetyEquipmentMapper mapper) {
        _mapper = mapper;
    }

    public IActionResult Create() {
        var vm = _mapper.GenerateSafetyEquipmentCreateViewModel();
        return View(vm);
    }
}

3. Mapping from Create ViewModel β†’ Domain Entity

[HttpPost]
public IActionResult Create(SafetyEquipmentCreateViewModel vm) {
    if(!ModelState.IsValid) {
        vm = _mapper.GenerateSafetyEquipmentCreateViewModel(); // repopulate lists
        return View(vm);
    }
    var entity = _mapper.CreateViewModelToSafetyEquipment(vm);
    _assetManager.SaveSafetyEquipment(entity);
    return RedirectToAction("Index");
}

4. Displaying Details & Warranty Status

<div class="status @Model.StatusColor">
    Status: @Model.Status
</div>
<div class="@Model.WarrantyColorClass">
    Warranty expires on: @Model.EndOfWarranty:d
    @if(Model.IsOutOfWarranty) { <span>⚠️ Out of warranty</span> }
    @else if(Model.IsApproachingEndOfWarranty) { <span>⏳ Approaching end of warranty</span> }
</div>

🏁 Conclusion

The SafetyEquipmentMapper streamlines the conversion between your domain and UI layers. By centralizing mapping logic:

  • You ensure consistency and DRY principles.
  • Controllers remain thin and focused on HTTP concerns.
  • ViewModels are always fully populated (dropdown lists, computed fields).

Use this mapper in your MVC controllers or API endpoints whenever you need to prepare or process safety equipment data for the UI. Happy coding! πŸš€