Assignment Management Feature

Relevant source files

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

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

The Assignment Management Feature is a core component of the SafeDispatch HQ Administration API designed to facilitate the linking of employees to specific departments. It serves as a relational bridge, allowing administrators to define an employee's functional role and security access level within a specific organizational unit.

This feature is primarily intended for use by HR personnel, as evidenced by the security constraints requiring the ROLE_HR for creating and deleting assignments. It ensures that organizational structures are maintainable by providing endpoints to establish new assignments and terminate existing ones when organizational changes occur.

Sources: Part1/API/src/main/resources/api-spec.yaml:268-271, Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:27-38

System Architecture and Data Flow

The feature follows a standard Spring Boot tiered architecture consisting of a Controller, Service, and Repository layer. Data enters the system via RESTful endpoints, is validated and processed in the service layer, and is persisted using Spring Data JPA.

Data Model Relationships

The Assignment entity acts as a junction table in a many-to-many relationship between Employee and Department, though it is implemented using two @ManyToOne relationships to store additional metadata such as role and accessLevel.

The diagram above illustrates how an Assignment bridges an Employee and a Department, allowing one employee to have many assignments and one department to contain many assignments.
Sources: Part1/API/src/main/java/com/example/api/model/Assignment.java:11-20, Part1/API/src/main/java/com/example/api/model/Employee.java:31, Part1/API/src/main/java/com/example/api/model/Department.java:23

Creation Flow

When creating an assignment, the system validates the existence of both the target employee and the target department before persisting the record.

API Endpoints

The Assignment Management Feature exposes two primary endpoints under the /api/assignments base path. These endpoints are secured and require specific roles for access.

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

Assignment Schema

The request body for creating an assignment utilizes a Data Transfer Object (DTO) containing the following fields:

Field	Type	Description	Required
employeeId	Long	Unique identifier of the employee to be assigned.	Yes
departmentId	Long	Unique identifier of the target department.	Yes
role	String	The functional job role (e.g., "Fleet Coordinator").	No
accessLevel	String	Security clearance level (e.g., "LEVEL_2").	No

Sources: Part1/API/src/main/resources/api-spec.yaml:78-100, Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:54-68

Implementation Details

Model Structure

The Assignment entity uses JPA annotations to define its database mapping. It includes a generated identity ID and enforces non-nullable foreign keys for both employee_id and department_id.

@Entity
@Table
public class Assignment {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne 
    @JoinColumn(name="employee_id", nullable = false) 
    private Employee employee;

    @ManyToOne 
    @JoinColumn(name="department_id", nullable = false)
    private Department department;

    private String role; 
    private String accessLevel;
}

Sources: Part1/API/src/main/java/com/example/api/model/Assignment.java:6-23

Repository Layer

Persistence logic is handled by the AssignmentRepository, which extends JpaRepository. This interface provides standard CRUD operations without requiring manual SQL implementation.

@Repository
public interface AssignmentRepository extends JpaRepository<Assignment, Long> {
}

Sources: Part1/API/src/main/java/com/example/api/repository/AssignmentRepository.java:9-11

Service Validation Logic

The AssignmentService performs existence checks. If an employeeId or departmentId provided in the request does not exist in the database, a ResponseStatusException with a 404 NOT_FOUND status is thrown.

Sources: Part1/API/src/main/java/com/example/api/service/AssignmentService.java:27-31

Conclusion

The Assignment Management Feature provides a structured way to manage the relationship between personnel and organizational units within SafeDispatch HQ. By leveraging a centralized assignment entity with specific role and access metadata, the system maintains referential integrity while enforcing strict role-based access control for administrative actions.