📄 IEmployeeAndFieldOfficeManager Interface Documentation
Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Interface Definition
- Key Functional Areas
- Method Details
- Usage Examples
- UML Diagram
- Error Handling & Return Types
- Conclusion
1. Overview & Purpose
The IEmployeeAndFieldOfficeManager interface is part of the IrbyImaging.Services namespace. It defines a contract for retrieving and updating Employee and Field Office data in an asynchronous manner.
👉 Intended Use
- To abstract the data-access logic for Employees and Field Offices.
- To allow dependency injection of any implementation (e.g., EF Core, Dapper, in-memory).
- To support search, lookup by ID/JDE Number, and updates on Employee entities.
2. Dependencies & Technologies
| Category | Details |
|---|---|
| Platform | .NET Standard / .NET 6+ |
| Language | C# (async/await, Generics) |
| Domain Models | Employee, FieldOffice (IrbyImaging.DomainClasses) |
| Asynchronous Pattern | Task<T> |
3. Interface Definition
using IrbyImaging.DomainClasses;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
namespace IrbyImaging.Services
{
/// <summary>
/// Defines operations for Employee and Field Office
/// lookups and updates.
/// </summary>
public interface IEmployeeAndFieldOfficeManager
{
Task<IEnumerable<Employee>> GetEmployees_Async(string searchTerm);
Task<Employee> GetEmployeeById_Async(Guid? id);
Task<Guid> GetEmployeeIdByJdeNumber_Async(string number);
Task<IEnumerable<Employee>> GetTerminatedEmployeesWithAssets(string searchTerm);
Task<IEnumerable<FieldOffice>> GetFieldOffices_Async(string searchTerm);
Task<FieldOffice> GetFieldOfficeById_Async(Guid? id);
Task<Guid> GetFieldOfficeIdByJdeNumber_Async(string number);
Task UpdateEmployee_Async(Employee employee);
}
}
4. Key Functional Areas
4.1 🧑 Employee Management
- Search & Listing
GetEmployees_Async(searchTerm)GetTerminatedEmployeesWithAssets(searchTerm)
- Lookup by ID
GetEmployeeById_Async(id)
- Lookup by JDE Number
GetEmployeeIdByJdeNumber_Async(number)
- Update Employee
UpdateEmployee_Async(employee)
4.2 🏢 Field Office Management
- Search & Listing
GetFieldOffices_Async(searchTerm)
- Lookup by ID
GetFieldOfficeById_Async(id)
- Lookup by JDE Number
GetFieldOfficeIdByJdeNumber_Async(number)
5. Method Details
| Method | Parameters | Returns | Description |
|---|---|---|---|
GetEmployees_Async(string searchTerm) |
searchTerm |
Task<IEnumerable<Employee>> |
Retrieves employees matching the search term. |
GetEmployeeById_Async(Guid? id) |
id |
Task<Employee> |
Fetches a single employee by their GUID. |
GetEmployeeIdByJdeNumber_Async(string number) |
number |
Task<Guid> |
Looks up Employee ID from a JDE Number. |
GetTerminatedEmployeesWithAssets(string term) |
term |
Task<IEnumerable<Employee>> |
Retrieves terminated employees who still have assets assigned. |
GetFieldOffices_Async(string searchTerm) |
searchTerm |
Task<IEnumerable<FieldOffice>> |
Retrieves field offices matching search criteria. |
GetFieldOfficeById_Async(Guid? id) |
id |
Task<FieldOffice> |
Fetches a single field office by GUID. |
GetFieldOfficeIdByJdeNumber_Async(string num) |
number |
Task<Guid> |
Looks up Field Office ID from a JDE Number. |
UpdateEmployee_Async(Employee employee) |
employee |
Task |
Persists changes to an existing Employee entity. |
6. Usage Examples
6.1 Dependency Injection Setup
// In Startup.cs or similar
services.AddScoped<IEmployeeAndFieldOfficeManager, EmployeeAndFieldOfficeManager>();
6.2 Fetching Data in a Controller or Service
public class EmployeeController : ControllerBase
{
private readonly IEmployeeAndFieldOfficeManager _mgr;
public EmployeeController(IEmployeeAndFieldOfficeManager mgr)
{
_mgr = mgr;
}
[HttpGet("employees/search")]
public async Task<IActionResult> SearchEmployees(string q)
{
var list = await _mgr.GetEmployees_Async(q);
return Ok(list);
}
[HttpGet("employees/{id}")]
public async Task<IActionResult> GetById(Guid id)
{
var employee = await _mgr.GetEmployeeById_Async(id);
if (employee == null)
return NotFound();
return Ok(employee);
}
}
6.3 Updating an Employee
[HttpPost("employees/update")]
public async Task<IActionResult> UpdateEmployee([FromBody] Employee updated)
{
await _mgr.UpdateEmployee_Async(updated);
return NoContent();
}
7. UML Diagram
interfaceDiagram
interface IEmployeeAndFieldOfficeManager {
+ Task<IEnumerable<Employee>> GetEmployees_Async(string)
+ Task<Employee> GetEmployeeById_Async(Guid?)
+ Task<Guid> GetEmployeeIdByJdeNumber_Async(string)
+ Task<IEnumerable<Employee>> GetTerminatedEmployeesWithAssets(string)
+ Task<IEnumerable<FieldOffice>> GetFieldOffices_Async(string)
+ Task<FieldOffice> GetFieldOfficeById_Async(Guid?)
+ Task<Guid> GetFieldOfficeIdByJdeNumber_Async(string)
+ Task UpdateEmployee_Async(Employee)
}
class Employee
class FieldOffice
IEmployeeAndFieldOfficeManager <|.. Employee
IEmployeeAndFieldOfficeManager <|.. FieldOffice
8. Error Handling & Return Types
- Asynchronous Exceptions
- Methods may throw
ArgumentNullExceptionif required parameters arenull. - Data-access exceptions (e.g.,
DbUpdateException) should be caught in implementation.
- Methods may throw
- Return Types
Task<IEnumerable<T>>: returns an empty list if no matches found.Task<T>: returnsnullif entity not found (calling code should check).Task<Guid>: may throw if JDE Number is invalid or not found.
9. Conclusion
The IEmployeeAndFieldOfficeManager interface provides a clean, asynchronous API for working with Employee and Field Office data in the IrbyImaging application. By coding against this interface, you gain:
- Loose coupling between controllers/services and data-access logic
- Testability via mocking/stubbing
- Reusability for any data store (SQL, NoSQL, in-memory)
✨ Next Steps:
- Implement the interface (
EmployeeAndFieldOfficeManager) using your preferred ORM. - Register it in Dependency Injection.
- Build Controllers or UI components to consume the methods!
Happy coding! 🚀