Assignment API Controller

Relevant source files

The following files were used as context for generating this wiki page:

• Part1/API/src/main/java/com/example/api/controller/AssignmentController.java
• Part1/API/src/main/java/com/example/api/service/AssignmentService.java
• Part1/API/src/main/java/com/example/api/model/Assignment.java
• Part1/API/src/main/resources/api-spec.yaml
• Part1/API/src/main/java/com/example/api/security/SecurityConfig.java
• Part1/API/src/main/java/com/example/api/repository/AssignmentRepository.java

Introduction

The Assignment API Controller is a core component of the SafeDispatch HQ Administration API, responsible for managing the organizational relationships between employees and departments. Its primary purpose is to facilitate the assignment of personnel to specific business units while defining their functional roles and access levels within those units.

This controller serves as the entry point for administrative operations that link Employee entities to Department entities. It ensures that such associations are valid by verifying the existence of both parties before persisting the relationship. Access to these operations is strictly regulated through role-based access control, primarily restricted to users with HR privileges.

Sources: Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:12-25, Part1/API/src/main/resources/api-spec.yaml:5-9

API Endpoints and Operations

The controller exposes RESTful endpoints under the /api/assignments base path. These endpoints allow for the creation and removal of links between employees and departments.

Method	Endpoint	Description	Auth Requirement
POST	/api/assignments	Assigns an employee to a department with a role and access level.	ROLE_HR
DELETE	/api/assignments/{id}	Removes an existing assignment by its unique ID.	ROLE_HR

Sources: Part1/API/src/main/resources/api-spec.yaml:236-285, Part1/API/src/main/java/com/example/api/security/SecurityConfig.java:49-52

Assignment Creation Flow

When a POST request is received, the system performs a multi-step validation and persistence process. It uses a Data Transfer Object (DTO) called AssignmentRequest to capture the necessary IDs and metadata.

This diagram illustrates the validation logic ensuring referential integrity before a new assignment is recorded.
Sources: Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:28-44, Part1/API/src/main/java/com/example/api/service/AssignmentService.java:26-40

Data Models and Structures

The Assignment Entity

The Assignment class is a JPA entity that maps the many-to-many relationship between employees and departments into a concrete table. It contains metadata regarding the nature of the assignment.

Field	Type	Description
id	Long	Primary key (auto-generated).
employee	Employee	The assigned staff member (Many-to-One).
department	Department	The target department (Many-to-One).
role	String	Functional job role (e.g., Fleet Coordinator).
accessLevel	String	Security clearance level (e.g., LEVEL_2).

Sources: Part1/API/src/main/java/com/example/api/model/Assignment.java:7-21, Part1/API/src/main/resources/api-spec.yaml:105-125

AssignmentRequest DTO

A specialized static inner class within the controller facilitates communication with the client by decoupling the API contract from the internal database schema.

public static class AssignmentRequest {
    private Long employeeId;
    private Long departmentId;
    private String role;
    private String accessLevel;
    // Getters and Setters...
}

Sources: Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:54-74

System Architecture and Logic

Component Relationships

The system follows a standard Spring Boot tiered architecture. The AssignmentController handles HTTP requests, while the AssignmentService contains the business logic, and the AssignmentRepository manages database interactions.

The architecture ensures separation of concerns, where the controller manages the web interface and the service layer manages the entity lifecycle.
Sources: Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:15-24, Part1/API/src/main/java/com/example/api/service/AssignmentService.java:15-24

Data Integrity and Constraints

The system enforces strict constraints on assignments:

1. Mandatory Associations: An assignment cannot exist without both a valid Employee and a valid Department.
2. Cascading Behavior: The Employee and Department entities define assignments with CascadeType.ALL, meaning life-cycle operations on the parent entities may affect the assignments.
3. Database Mapping: The Assignment entity uses @JoinColumn with nullable = false to enforce non-null foreign keys at the database level.

Sources: Part1/API/src/main/java/com/example/api/model/Assignment.java:12-18, Part1/API/src/main/java/com/example/api/model/Employee.java:31-32, Part1/API/src/main/java/com/example/api/model/Department.java:22-23

Security and Access Control

Security is integrated via Spring Security configuration. All modification requests to assignments (POST and DELETE) require the user to have the HR role.

This sequence demonstrates the role-based barrier protecting the assignment endpoints.
Sources: Part1/API/src/main/java/com/example/api/security/SecurityConfig.java:46-52, Part1/API/src/main/resources/api-spec.yaml:256-259

Conclusion

The Assignment API Controller provides a secure and validated interface for managing the SafeDispatch organizational structure. By acting as a mediator between employees and departments, it ensures that every assignment is backed by existing records and authorized by personnel with the appropriate administrative roles.