🚀 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
- Overview & Purpose
- Dependencies & Technologies
- Class Definition & Interfaces
- Key Functional Areas
4.1. Employee Management 👤
4.2. Field Office Management 🏢 - Data Models & Domain Entities
- Helper Methods & Utilities 🛠️
- Error Handling & Return Types ⚠️
- Third-Party Integrations 🔗
- Sample Usage & Code Snippets 📋
- UML Class Diagram 📊
- 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:
IrbyContextfor EF Core operationsIActiveDirectoryServicefor 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
JobandAssets → Model → Makerelationships.
📱 Phone Retrieval:
- Assigned Mobile: Queries
MobileDevicesfor 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
assignedNumberinto 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_Asyncreturnsnullif not found.- ID lookup methods (
Guid) returnGuid.Emptyif 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! 🎉