🚀 EmployeeAndFieldOfficeManager Service Documentation

Welcome to the comprehensive documentation for the EmployeeAndFieldOfficeManager service in the IrbyImaging solution. This document covers everything from purpose to code snippets, UML diagrams, dependencies, and usage examples.


📑 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Class Definition & Interfaces
  4. Key Functional Areas
    4.1. Employee Management 👤
    4.2. Field Office Management 🏢
  5. Data Models & Domain Entities
  6. Helper Methods & Utilities 🛠️
  7. Error Handling & Return Types ⚠️
  8. Third-Party Integrations 🔗
  9. Sample Usage & Code Snippets 📋
  10. UML Class Diagram 📊
  11. Conclusion ✔️

1. Overview & Purpose

EmployeeAndFieldOfficeManager is a service class within the IrbyImaging.Services namespace. It provides asynchronous CRUD‐style operations for:

  • Employees: searching, retrieving details, updating notes, listing terminated employees with assets.
  • Field Offices: searching, retrieving details, fetching by JDE numbers.

🎯 Intended Use:

  • Abstract away direct EF Core calls from controllers or other business logic layers.
  • Provide a clean, consistent API for UI components to manage employee and field office data.
  • Combine data from database and Active Directory (for phone numbers) seamlessly.

2. Dependencies & Technologies

Component Purpose
Microsoft.EntityFrameworkCore ORM for database interactions
IrbyContext (DbContext) EF Core database context
IrbyImaging.DomainClasses Domain entities: Employee, FieldOffice, etc.
IrbyImaging.Utility Enums (e.g., EmployeeStatus, DeviceType)
IrbyImaging.UI.Services.IActiveDirectoryService Abstraction over AD lookups (phone numbers)
.NET / C# Base platform and language
Asynchronous Programming (async/await) Scalability and responsiveness

3. Class Definition & Interfaces

namespace IrbyImaging.Services
{
    public class EmployeeAndFieldOfficeManager : IEmployeeAndFieldOfficeManager
    {
        private readonly IrbyContext _context;
        private readonly IActiveDirectoryService _activeDirectory;

        public EmployeeAndFieldOfficeManager(
            IrbyContext context, 
            IActiveDirectoryService activeDirectory) { … }

        // Employee methods …
        // FieldOffice methods …
    }
}
  • Implements: IEmployeeAndFieldOfficeManager
  • Injects:
    • IrbyContext for EF Core operations
    • IActiveDirectoryService for retrieving office phone numbers

4. Key Functional Areas

4.1 Employee Management

Method Description Return Type
UpdateEmployee_Async(Employee employee) Saves any changes made to an Employee instance Task
GetEmployees_Async(string searchTerm) Lists active (non‐terminated) employees, optional search filter Task<IEnumerable<Employee>>
GetEmployeeById_Async(Guid? id) Retrieves a full employee record, includes job, assets & phone Task<Employee>
GetEmployeeIdByJdeNumber_Async(string) Gets EmployeeId by JDE number Task<Guid>
GetTerminatedEmployeesWithAssets(string) Fetches terminated employees who still have assigned assets Task<IEnumerable<Employee>>

🔍 Search Logic:

  • Filters on JdeNumber, FirstName, LastName, MiddleName, FullName.
  • Excludes terminated employees in GetEmployees_Async.
  • Includes nested Job and Assets → Model → Make relationships.

📱 Phone Retrieval:

  • Assigned Mobile: Queries MobileDevices for first active phone. Formats (NNN-NNN-NNNN).
  • Office # (commented out): Illustrates how AD lookup might be used.

4.2 Field Office Management

Method Description Return Type
GetFieldOffices_Async(string searchTerm) Lists all field offices, optional search filter Task<IEnumerable<FieldOffice>>
GetFieldOfficeById_Async(Guid? id) Retrieves a full field office record, includes key relationships & assets Task<FieldOffice>
GetFieldOfficeIdByJdeNumber_Async(string) Gets FieldOffice.Id by JDE number Task<Guid>

🔍 Search Logic:

  • Filters on JdeNumber, Name, or manager’s name.
  • Eager-loads: Manager, Superintendent, ProjectManager, AsstProjectManager, Lead, Director, Primary/SecondaryContact, Assets → Model → Make.

5. Data Models & Domain Entities

Entity Key Properties & Navigation
Employee EmployeeId, JdeNumber, FirstName, LastName, FullName, StatusNavigations: Job, Assets, AssignedMobileDevices
FieldOffice Id, JdeNumber, NameNavigations: Manager, Superintendent, ProjectManager, AsstProjectManager, Lead, Director, Primary/SecondaryContact, Assets
Asset AssetId, ModelId, Status, OwnerIdNavigations: Model → Make
Model/Make Device model and manufacturer details
Job Employee job details
MobileDevice Type (Phone/Tablet), Status, PhoneNumber, OwnerId

6. Helper Methods & Utilities 🛠️

  • EntityState.Modified: Marks the EF Core entity as changed.
  • LINQ & EF Includes: Eager‐loads related data for serialization or business logic.
  • String Formatting: Break apart assignedNumber into standard phone segments.
// Formatting phone number
var areaCode = assignedNumber.Substring(0, 3);
var prefix   = assignedNumber.Substring(3, 3);
var line     = assignedNumber.Substring(6);
assignedNumber = $"{areaCode}-{prefix}-{line}";

7. Error Handling & Return Types ⚠️

  • All methods are async Task<…> and rely on EF Core’s built‐in exception propagation.
  • No internal try/catch: Exceptions bubble up to calling layer (Controller / Business Layer).
  • Return values:
    • Collections may be empty lists if no matches.
    • Get…ById_Async returns null if not found.
    • ID lookup methods (Guid) return Guid.Empty if no match.

8. Third-Party Integrations 🔗

Integration Role
Active Directory (AD) Retrieve HomePhone for employees (commented out example).
EF Core Database interactions, migrations, change tracking.
// Example AD lookup (currently commented in code)
employee.PhoneNumberFromActiveDirectory =
    _activeDirectory.GetPhoneNumberFromActiveDirectory(employee.JdeNumber);

9. Sample Usage & Code Snippets 📋

9.1 Dependency Injection (Startup.cs)

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<IrbyContext>(opt =>
        opt.UseSqlServer(Configuration.GetConnectionString("IrbyDb")));
    services.AddScoped<IActiveDirectoryService, ActiveDirectoryService>();
    services.AddScoped<IEmployeeAndFieldOfficeManager, EmployeeAndFieldOfficeManager>();
    // … other services
}

9.2 Controller Example

[ApiController]
[Route("api/[controller]")]
public class EmployeeController : ControllerBase
{
    private readonly IEmployeeAndFieldOfficeManager _manager;

    public EmployeeController(IEmployeeAndFieldOfficeManager manager)
    {
        _manager = manager;
    }

    // GET: api/Employee?searchTerm=Smith
    [HttpGet]
    public async Task<IActionResult> Get(string searchTerm = "")
    {
        var employees = await _manager.GetEmployees_Async(searchTerm);
        return Ok(employees);
    }

    // GET: api/Employee/{id}
    [HttpGet("{id}")]
    public async Task<IActionResult> GetById(Guid id)
    {
        var employee = await _manager.GetEmployeeById_Async(id);
        if (employee == null) return NotFound();
        return Ok(employee);
    }
}

9.3 Console App Example

var manager = serviceProvider.GetService<IEmployeeAndFieldOfficeManager>();
var allEmployees = await manager.GetEmployees_Async("");
Console.WriteLine("Active Employees:");
allEmployees.ToList().ForEach(e => 
    Console.WriteLine($"{e.FullName} ({e.JdeNumber})"));

10. UML Class Diagram 📊

classDiagram
    IEmployeeAndFieldOfficeManager <|.. EmployeeAndFieldOfficeManager
    EmployeeAndFieldOfficeManager o-- IrbyContext : uses
    EmployeeAndFieldOfficeManager o-- IActiveDirectoryService : uses
    EmployeeAndFieldOfficeManager ..> Employee : returns/includes
    EmployeeAndFieldOfficeManager ..> FieldOffice : returns/includes
    Employee ..> Job
    Employee ..> Asset
    Asset ..> Model
    Model ..> Make
    FieldOffice ..> Employee : Manager, Superintendent, etc.

11. Conclusion ✔️

The EmployeeAndFieldOfficeManager class is a central piece of the IrbyImaging UI layer, providing a robust and consistent API for:

  • Managing employee records
  • Searching and retrieving details
  • Handling field office data with complex navigations
  • Integrating database data with external sources (AD phones)

By following the patterns shown above, you can easily extend, test, and maintain this service. Happy coding! 🎉