📄 FieldOfficesController.cs Documentation
Assembly: IrbyImaging.UI
Namespace:IrbyImaging.Controllers
Author: kvamshi
Created: 03-31-2022
Last Modified: 05-17-2022
🚀 Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Architecture & UML Diagram
- Key Functional Areas
- View Models & Data Models
- Helper Methods & Utilities
- Error Handling & Return Types
- API Endpoints Overview
- Third‑party Integrations
- Sample Code Blocks & Usage Examples
- Conclusion
🔍 Overview & Purpose
The FieldOfficesController is an ASP.NET Core MVC controller responsible for CRUD operations, data aggregation, and interactive views related to Field Offices in the IrbyImaging application. It orchestrates:
- Retrieval of field office records
- Display of associated jobs, employees & assets
- Map-based and directory-based visualizations
- Creation and editing of field office entities
Intended Use
Business users can manage field-office data, analyze active job metrics, and access employee-asset assignments via both tabular and map-centric UIs.
🛠 Dependencies & Technologies
| Technology / Library | Purpose |
|---|---|
| Microsoft.AspNetCore.Mvc | MVC framework & controllers |
| Microsoft.EntityFrameworkCore | Database context (IrbyContext) |
| Microsoft.Extensions.Configuration | Reading configuration (e.g., connection strings) |
| IrbyImaging.BusinessLogic | Business logic abstractions (IEmployeeAndFieldOfficeManager) |
| IrbyImaging.Services | Services layer |
| IrbyImaging.Utility | Utility enums & helpers |
| IrbyImaging.DomainClasses | Domain model definitions |
| Org.BouncyCastle.Ocsp, NuGet.* (unused in file) | (Imported but not referenced) |
| mermaid (in docs) | UML diagram generation |
🏗 Architecture & UML Diagram
Below is a simplified UML class diagram illustrating the FieldOfficesController and its collaborators:
classDiagram
class FieldOfficesController {
- IrbyContext _context
- IEmployeeAndFieldOfficeManager _manager
- IConfiguration _configuration
+ Task<IActionResult> Index(string search)
+ Task<IActionResult> Details(Guid? id)
+ Task<IActionResult> JobMasterList()
+ IActionResult FieldOfficeMap(string search, bool embed=false)
+ IActionResult EmployeeDirectory()
+ IActionResult Create()
+ Task<IActionResult> Create(FieldOffice fieldOffice)
+ Task<IActionResult> Edit(Guid? id)
+ Task<IActionResult> Edit(FieldOffice fieldOffice)
- bool FieldOfficeExists(Guid id)
}
FieldOfficesController "1" *-- "1" IrbyContext
FieldOfficesController "1" *-- "1" IEmployeeAndFieldOfficeManager
FieldOfficesController "1" *-- "1" IConfiguration
🔑 Key Functional Areas
4.1 Index (List Field Offices) 🗂️
public async Task<IActionResult> Index(string search)
{
var fieldOffices = await _manager.GetFieldOffices_Async(search);
return View(fieldOffices);
}
- Purpose: Displays a searchable list of all field offices.
- Parameters:
search: Optional search term to filter by office name or JDE number.
- Returns:
ViewResultwithIEnumerable<FieldOffice>.
4.2 Details (Field Office Profile) 📋
public async Task<IActionResult> Details(Guid? id)
- Validation:
- If
id == null➡️404 NotFound().
- If
- Fetch:
- FieldOffice via
_manager.GetFieldOfficeById_Async(id).
- FieldOffice via
- Aggregate Data:
- Jobs in this office
- Employees in those jobs
- Assets assigned to each employee
- Populate:
ViewBag.Jobs,ViewBag.Employees,ViewBag.Assets
- Return:
- Profile view with enriched data.
4.3 JobMasterList (Active Jobs) 🏗️
public async Task<IActionResult> JobMasterList()
- Fetch: All non‑closed jobs, including nested employees & assets.
- Enrich: Each
Jobwith its respectiveFieldOfficeobject. - Return:
View(alljobs)containingList<Job>.
4.4 FieldOfficeMap (Map View) 🗺️
public IActionResult FieldOfficeMap(string search, bool embed = false)
- Raw SQL: Queries a view
JobAndFieldOfficeMappingfor geospatial & contact data. - Parameters:
search: Filter by name or address (not implemented in snippet).embed: Iftrue, returns aPartialView.
- Output:
ViewBag.datasourcefor map rendering (e.g., JavaScript mapping library).
4.5 EmployeeDirectory (Directory View) 👥
public IActionResult EmployeeDirectory()
- Fetch: All active employees, their department, job & assets.
- Return: Directory UI with detailed employee cards or table.
4.6 Create / Edit Field Offices ✏️
| Action | HTTP Verb | Authorization | Functionality |
|---|---|---|---|
Create() |
GET | Admin (Policy) | Renders blank form with Manager dropdown. |
Create(Post) |
POST | Admin (Policy) | Binds & validates FieldOffice, persists to DB. |
Edit(Guid?) |
GET | Admin (Policy) | Renders form with current values & employee list. |
Edit(Post) |
POST | Admin (Policy) | Updates entity, handles concurrency. |
🗃️ View Models & Data Models
Domain Model: FieldOffice
- Fields:
Id,JdeNumber,Name,ManagerId,MailingAddress,ShippingAddress, etc. - Navigation: Manager, Superintendent, Jobs, Employees.
View Models
| Class | Purpose |
|---|---|
AssetDetail |
Flattened asset info for UI listing |
EmpDetail |
Employee summary in context of a Job |
JobDetails |
Rich job metadata + contact & address info |
AssetDetail
public class AssetDetail {
public Guid Id { get; set; }
public string Category { get; set; }
public string Make { get; set; }
public string Model { get; set; }
public string SerialNumber { get; set; }
public Guid EmployeeId { get; set; }
public string OwnerFullName { get; set; }
public string Status { get; set; }
}
🛠 Helper Methods & Utilities
-
FieldOfficeExists(Guid id)
Checks existence to handle concurrency inEdit(Post). -
SelectListItem Builders
Populate employee dropdowns for assignable managers or leads.
⚠️ Error Handling & Return Types
- NotFound() when requested resource is missing.
- ModelState.IsValid gating on POST actions.
- DbUpdateConcurrencyException caught in
Edit(Post)to surface stale data issues. - All action methods return
IActionResult(or specialized derivatives likeViewResult,PartialViewResult,RedirectToActionResult).
🌐 API Endpoints Overview
| Route Pattern | HTTP Verb | Action Method |
|---|---|---|
/FieldOffices |
GET | Index |
/FieldOffices/Details/{id} |
GET | Details |
/FieldOffices/Create |
GET | Create (form) |
/FieldOffices/Create |
POST | Create (submit) |
/FieldOffices/Edit/{id} |
GET | Edit (form) |
/FieldOffices/Edit |
POST | Edit (submit) |
/FieldOffices/JobMasterList |
GET | JobMasterList |
/FieldOffices/FieldOfficeMap |
GET | FieldOfficeMap |
/FieldOffices/EmployeeDirectory |
GET | EmployeeDirectory |
Note: Authorization attributes are commented out in source; enable
[Authorize(Policy = "...")]as per security requirements.
🔗 Third‑party Integrations
- Entity Framework Core: LINQ & raw SQL queries.
- mermaid (docs only): UML visualization.
- SelectList from
Microsoft.AspNetCore.Mvc.Renderingfor dropdown binding.
📌 Sample Code Blocks & Usage Examples
1. Searching Field Offices
// Controller call
public async Task<IActionResult> Index(string search)
{
return View(await _manager.GetFieldOffices_Async(search));
}
// Razor snippet (Index.cshtml)
@model IEnumerable<FieldOffice>
<form asp-action="Index" method="get">
<input type="text" name="search" value="@Request.Query["search"]" placeholder="Search offices…" />
<button type="submit">🔍 Search</button>
</form>
<table>
@foreach(var office in Model) {
<tr>
<td>@office.JdeNumber</td>
<td>@office.Name</td>
<td>@Html.ActionLink("Details", "Details", new { id = office.Id })</td>
</tr>
}
</table>
2. Rendering the Map
@* In FieldOfficeMap.cshtml *@
@{
var data = ViewBag.datasource as IList<JobAndFieldOfficeMapping>;
}
<div id="map" style="height: 500px;"></div>
<script>
const locations = @Html.Raw(Json.Serialize(data));
// Initialize Leaflet or Google Maps with `locations`
</script>
🏁 Conclusion
The FieldOfficesController is a pivotal component within the IrbyImaging.UI layer, delivering comprehensive management and visualization capabilities for field office data. By leveraging Entity Framework Core, dependency‑injected business logic, and rich view models, it:
- Streamlines CRUD operations for offices
- Aggregates jobs, employees, and assets
- Offers map and directory visualizations
- Handles concurrency and validation gracefully
Whether you need a quick directory or an interactive dashboard, this controller encapsulates the core patterns for extensible, testable, and maintainable MVC development.
Happy coding! 🎉