📄 IEmployeeAndFieldOfficeManager Interface Documentation


Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Interface Definition
  4. Key Functional Areas
  5. Method Details
  6. Usage Examples
  7. UML Diagram
  8. Error Handling & Return Types
  9. 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 ArgumentNullException if required parameters are null.
    • Data-access exceptions (e.g., DbUpdateException) should be caught in implementation.
  • Return Types
    • Task<IEnumerable<T>>: returns an empty list if no matches found.
    • Task<T>: returns null if 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! 🚀