πŸ“‹ JobManager Service Documentation


Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Class Diagram
  4. Key Functional Areas
  5. Method Details
  6. Usage Example
  7. Error Handling & Return Types
  8. Conclusion

1. Overview & Purpose

The JobManager class is a service-layer component in the IrbyImaging application. It implements the IJobManager interface to provide asynchronous retrieval and searching of Job entities from the database.

πŸš€ Intended Use

  • Retrieve a single Job by its unique identifier (GUID).
  • Search and retrieve a list of Jobs by partial matching of JDE Number or Name.

This class abstracts database access logic (via Entity Framework Core), centralizing it in one place and making it reusable across controllers, business logic layers, and other services.


2. Dependencies & Technologies

Category Details
βš™οΈ ORM Microsoft.EntityFrameworkCore
πŸ“¦ Data Context IrbyContext (inherits from DbContext)
πŸ“ Domain Classes Job, Employee, Asset, Model, Make, FieldOffice
πŸ”— Business Logic & Utils IrbyImaging.BusinessLogic, IrbyImaging.Utility
πŸ“‘ Asynchronous Patterns async / await, Task<T>

Note: The code relies on EF Core’s eager loading (Include, ThenInclude) to fetch related navigation properties in a single query.


3. Class Diagram

+-------------------------------------------------+
|                IJobManager                      |  Β«interfaceΒ»
+-------------------------------------------------+
| + GetJobById_Async(Guid? id) : Task<Job>        |
| + GetJobs_Async(string searchTerm) : Task<IEnumerable<Job>> |
+-------------------------------------------------+

               β–²
               β”‚ implements
               β”‚
+-------------------------------------------------+
|                JobManager                       |
+-------------------------------------------------+
| - _context : IrbyContext                        |
+-------------------------------------------------+
| + JobManager(IrbyContext context)               |
| + GetJobById_Async(Guid? id) : Task<Job>        |
| + GetJobs_Async(string searchTerm) : Task<IEnumerable<Job>> |
+-------------------------------------------------+

4. Key Functional Areas

4.1 GetJobById_Async

πŸ” Purpose
Retrieve one Job by its primary key (JobId), along with its full graph of related entities:

  • Employees
    • Assets
      • Model
        • Make

4.2 GetJobs_Async

πŸ”Ž Purpose
Retrieve a collection of Job entities, optionally filtered by a search term that matches either:

  • JdeNumber.Contains(searchTerm)
  • Name.Contains(searchTerm)

Results are ordered by JdeNumber.


5. Method Details

Method Signature Description
Constructor JobManager(IrbyContext context) Injects the EF Core data context to be used for database operations.
GetJobById_Async Task<Job> GetJobById_Async(Guid? id) - Fetches a single job by JobId- Eager loads Employees β†’ Assets β†’ Model β†’ Make- Returns null if not found
GetJobs_Async Task<IEnumerable<Job>> GetJobs_Async(string searchTerm) - If searchTerm supplied, filters jobs by JDE Number or Name- Always includes FieldOffice navigation property (if needed no explicit Include shown)- Orders by JdeNumber

5.1 Code Snippets

public async Task<Job> GetJobById_Async(Guid? id)
{
    return await _context.Jobs
        .Include(j => j.Employees)
            .ThenInclude(e => e.Assets)
                .ThenInclude(a => a.Model)
                    .ThenInclude(m => m.Make)
        .FirstOrDefaultAsync(j => j.JobId == id);
}

public async Task<IEnumerable<Job>> GetJobs_Async(string searchTerm)
{
    IQueryable<Job> jobs = _context.Jobs;

    if (!string.IsNullOrEmpty(searchTerm))
    {
        jobs = jobs.Include(j => j.FieldOffice)
                   .Where(j => j.JdeNumber.Contains(searchTerm)
                            || j.Name.Contains(searchTerm));
    }

    return await jobs
        .OrderBy(j => j.JdeNumber)
        .ToListAsync();
}

6. Usage Example

6.1 Dependency Injection (Startup.cs)

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<IrbyContext>(options => 
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

    // Register the JobManager service
    services.AddScoped<IJobManager, JobManager>();

    // ... other services
}

6.2 Consuming in a Controller

[ApiController]
[Route("api/[controller]")]
public class JobsController : ControllerBase
{
    private readonly IJobManager _jobManager;

    public JobsController(IJobManager jobManager)
    {
        _jobManager = jobManager;
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetJob(Guid id)
    {
        var job = await _jobManager.GetJobById_Async(id);
        if (job == null) return NotFound();
        return Ok(job);
    }

    [HttpGet]
    public async Task<IActionResult> SearchJobs([FromQuery] string search)
    {
        var jobs = await _jobManager.GetJobs_Async(search);
        return Ok(jobs);
    }
}

7. Error Handling & Return Types

  • Error Handling

    • Currently, no explicit try/catch within JobManager. Exceptions (e.g., database connectivity) bubble up to calling layer.
    • It’s recommended to add logging or wrap calls in try { } catch (Exception ex) { ... } if fine-grained handling is needed.
  • Return Types

    • Task<Job>: returns a single Job or null.
    • Task<IEnumerable<Job>>: returns an empty list (List<Job>) if no matches found.

8. Conclusion

🎯 JobManager is a lightweight, single-responsibility service that encapsulates all read-access logic for Job entities. By leveraging EF Core’s eager loading and LINQ for filtering & ordering, it provides developers with simple, reusable methods to fetch jobs in the IrbyImaging system.

Whether you need a detailed job with its employees and assets, or a paginated search list, JobManager can be extended to suit caching, additional filters, pagination, or deeper graph loading in the future.


Happy coding! πŸš€