📄 FieldOfficesController.cs Documentation

Assembly: IrbyImaging.UI
Namespace: IrbyImaging.Controllers
Author: kvamshi
Created: 03-31-2022
Last Modified: 05-17-2022


🚀 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Architecture & UML Diagram
  4. Key Functional Areas
  5. View Models & Data Models
  6. Helper Methods & Utilities
  7. Error Handling & Return Types
  8. API Endpoints Overview
  9. Third‑party Integrations
  10. Sample Code Blocks & Usage Examples
  11. 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: ViewResult with IEnumerable<FieldOffice>.

4.2 Details (Field Office Profile) 📋

public async Task<IActionResult> Details(Guid? id)
  1. Validation:
    • If id == null ➡️ 404 NotFound().
  2. Fetch:
    • FieldOffice via _manager.GetFieldOfficeById_Async(id).
  3. Aggregate Data:
    • Jobs in this office
    • Employees in those jobs
    • Assets assigned to each employee
  4. Populate:
    • ViewBag.Jobs, ViewBag.Employees, ViewBag.Assets
  5. 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 Job with its respective FieldOffice object.
  • Return: View(alljobs) containing List<Job>.

4.4 FieldOfficeMap (Map View) 🗺️

public IActionResult FieldOfficeMap(string search, bool embed = false)
  • Raw SQL: Queries a view JobAndFieldOfficeMapping for geospatial & contact data.
  • Parameters:
    • search: Filter by name or address (not implemented in snippet).
    • embed: If true, returns a PartialView.
  • Output: ViewBag.datasource for 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 in Edit(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 like ViewResult, 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.Rendering for 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! 🎉