📜 HistoryViewModel Documentation
📖 Table of Contents
- Overview & Purpose
- Key Functional Areas
- Dependencies & Technologies
- Class Diagram (UML)
- Property Reference
- Data Annotations & Display
- Sample Usage Scenarios
- Integration & Third‑Party Considerations
- Error Handling & Validation
- 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)]toTimestampto format date-only displays or strip time zones in certain views.
- Add
[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:
SomeAssetcan 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
Actionor valid dates), decorate properties with[Required],[StringLength], etc.
- No built-in validation attributes beyond
- Flow-Level:
- Exceptions are handled in controllers/services.
- Return HTTP
400 Bad Requestfor invalid filters or404 Not Foundwhen 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
SomeAssetto a strong‑typed DTO for richer metadata scenarios.
Happy Coding! 😊