📜 HistoryViewModel Documentation


📖 Table of Contents

  1. Overview & Purpose
  2. Key Functional Areas
  3. Dependencies & Technologies
  4. Class Diagram (UML)
  5. Property Reference
  6. Data Annotations & Display
  7. Sample Usage Scenarios
  8. Integration & Third‑Party Considerations
  9. Error Handling & Validation
  10. Conclusion

1. Overview & Purpose

HistoryViewModel is a Plain Old CLR Object (POCO) residing in the IrbyImaging.Models namespace. It represents an audit/history record for a given asset within the IrbyImaging UI and API layers.

  • 🎯 Primary Goal: Surface change‐tracking information (who did what, when, and why) in both UI views and API endpoints.
  • 🌐 Intended Use:
    • Return a list of historical events via Web API endpoints.
    • Bind to Razor or Blazor UI components for display in tables, charts, or logs.

2. Key Functional Areas

  • Asset Identification: Tracks which asset the history entry belongs to (AssetId).
  • Time Stamping: Captures the exact UTC date/time of the event (Timestamp).
  • User & Ownership Info:
    • OwnerId, Owner: Who owns the asset at the time.
    • ModifiedBy: Who performed the action.
  • Event Details:
    • Action: The operation performed (e.g., “Created”, “Updated”, “Deleted”).
    • Category: A grouping or sub‐type of the action.
    • Status: Current status after the event.
    • Reason: Explanation for the change.
  • Payload / Metadata:
    • SomeAsset: A flexible object to attach additional metadata or snapshot of the asset properties.

3. Dependencies & Technologies

Category Description
Target Framework .NET 6+ (Core / 5 / 3.1 compatible)
Languages C#
Assemblies System, System.ComponentModel.DataAnnotations
NuGet Packages None directly—uses built-in DataAnnotations

4. Class Diagram (UML)

+------------------------------------------------+
|                HistoryViewModel                |
+------------------------------------------------+
| - AssetId      : Guid                          |
| - Timestamp    : DateTimeOffset                |
| - Status       : string                         |
| - OwnerId      : Guid                          |
| - Owner        : string                         |
| - Action       : string                         |
| - Category     : string                         |
| - Reason       : string                         |
| - ModifiedBy   : string                         |
| - SomeAsset    : object                         |
+------------------------------------------------+

5. Property Reference

Property Type Description
AssetId Guid Unique identifier of the asset.
Timestamp DateTimeOffset Date and time when the event occurred.
Status string Current status of the asset after the event.
OwnerId Guid Unique identifier of the asset’s owner.
Owner string Display name of the owner.
Action string The action performed (e.g., “Create”, “Update”).
Category string Classification or grouping of the action.
Reason string Free-text explanation for why the action took place.
ModifiedBy string Name or identifier of the user who performed the change.
SomeAsset object Arbitrary snapshot or metadata related to the asset.

6. Data Annotations & Display

  • [Display(Name = "...")]: Controls labels in UI and scaffolding.
  • Potential Enhancement:
    • Add [DataType(DataType.Date)] to Timestamp to format date-only displays or strip time zones in certain views.
[Display(Name = "Modified By")]
public string ModifiedBy { get; set; }

[Display(Name = "Properties")]
public object SomeAsset { get; set; }

7. Sample Usage Scenarios

7.1 As Part of an API Response

📌 Controller Method

[HttpGet("api/assets/{assetId}/history")]
public async Task<IActionResult> GetAssetHistory(Guid assetId)
{
    var events = await _historyService.FetchHistoryAsync(assetId);
    var viewModels = events.Select(e => new HistoryViewModel {
        AssetId   = e.AssetId,
        Timestamp = e.Timestamp,
        Status    = e.Status,
        OwnerId   = e.OwnerId,
        Owner     = e.OwnerName,
        Action    = e.Action,
        Category  = e.Category,
        Reason    = e.Reason,
        ModifiedBy= e.ModifiedBy,
        SomeAsset = e.Snapshot
    });
    return Ok(viewModels);
}

🔍 JSON Response Sample

[
  {
    "AssetId": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
    "Timestamp": "2022-03-31T14:25:00Z",
    "Status": "Active",
    "OwnerId": "11111111-2222-3333-4444-555555555555",
    "Owner": "John Doe",
    "Action": "Updated",
    "Category": "Maintenance",
    "Reason": "Routine check",
    "ModifiedBy": "asmith",
    "SomeAsset": { "Location": "Warehouse A", "Condition": "Good" }
  }
]

7.2 In an ASP.NET Razor View

📌 View (History.cshtml)

@model IEnumerable<IrbyImaging.Models.HistoryViewModel>

<table class="table table-striped">
    <thead>
        <tr>
            <th>Timestamp</th>
            <th>Status</th>
            <th>Action</th>
            <th>Modified By</th>
            <th>Reason</th>
        </tr>
    </thead>
    <tbody>
        @foreach (var entry in Model)
        {
            <tr>
                <td>@entry.Timestamp.ToLocalTime().ToString("g")</td>
                <td>@entry.Status</td>
                <td>@entry.Action</td>
                <td>@entry.ModifiedBy</td>
                <td>@entry.Reason</td>
            </tr>
        }
    </tbody>
</table>

8. Integration & Third‑Party Considerations

  • 🔗 UI Frameworks:
    • Compatible with Blazor, Angular/React (via JSON), or plain Razor.
  • 🛠️ No external dependencies beyond .NET Core libraries.
  • ✅ Extensible:
    • SomeAsset can carry arbitrary JSON objects returned from third‑party systems.

9. Error Handling & Validation

  • ViewModel-Level:
    • No built-in validation attributes beyond [Display].
    • If stricter validation is needed (e.g., non-null Action or valid dates), decorate properties with [Required], [StringLength], etc.
  • Flow-Level:
    • Exceptions are handled in controllers/services.
    • Return HTTP 400 Bad Request for invalid filters or 404 Not Found when no history exists.

10. Conclusion

The HistoryViewModel class is a lightweight, flexible representation of an asset’s audit trail. It seamlessly integrates with both ASP.NET MVC/Razor front ends and Web API endpoints, ensuring that your application can present human-readable, localized, and well‑formatted history records with minimal boilerplate.

🚀 Next Steps:

  • Add validation attributes for stricter contract enforcement.
  • Implement paging, filtering, and sorting in your history API.
  • Extend SomeAsset to a strong‑typed DTO for richer metadata scenarios.

Happy Coding! 😊