Data Models

This document provides a detailed technical specification of the data models used for ticket creation, retrieval, and management within the application. These models serve as Data Transfer Objects (DTOs) for API interactions, ensuring a clear and stable contract between the client and the server.

For information on how these models are used in API endpoints, refer to the Tickets API Reference.

TicketRequest

The TicketRequest DTO is used as the payload for creating a new ticket or updating an existing one. It encapsulates all the user-submittable data and includes validation constraints to ensure data integrity at the controller level.

Implementation Details

This model is a plain old Java object (POJO) enhanced with Lombok annotations (@Data, @Builder, etc.) to minimize boilerplate code. It leverages the Jakarta Bean Validation API (jakarta.validation.constraints.*), which is integrated via the spring-boot-starter-validation dependency, to enforce field-level rules.

// src/main/java/com/slalom/demo/ticketing/dto/TicketRequest.java
package com.slalom.demo.ticketing.dto;

import com.slalom.demo.ticketing.model.TicketPriority;
import com.slalom.demo.ticketing.model.TicketStatus;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class TicketRequest {

    @NotBlank(message = "Title is required")
    private String title;

    @NotBlank(message = "Description is required")
    private String description;

    @NotNull(message = "Status is required")
    private TicketStatus status;

    @NotNull(message = "Priority is required")
    private TicketPriority priority;

    @NotBlank(message = "Requester email is required")
    @Email(message = "Invalid email format")
    private String requesterEmail;

    private String assignedTo; // Optional field, can be null
}

Fields and Validation Constraints

The following table details each field in the TicketRequest model and its associated validation rules. Failure to meet these constraints will result in a 400 Bad Request response with a descriptive error message. For more details on error responses, see the Validation API documentation.

Field	Type	Required?	Constraints	Description
title	String	Yes	@NotBlank	The main subject or title of the ticket. Cannot be null or empty.
description	String	Yes	@NotBlank	A detailed description of the issue or request. Cannot be null or empty.
status	TicketStatus	Yes	@NotNull	The initial status of the ticket. Must be one of the valid TicketStatus enum values.
priority	TicketPriority	Yes	@NotNull	The priority level of the ticket. Must be one of the valid TicketPriority enum values.
requesterEmail	String	Yes	@NotBlank, @Email	The email address of the person who created the ticket. Must be a valid email format.
assignedTo	String	No	None	The identifier (e.g., email or username) of the user assigned to the ticket. Can be null.

Example JSON Payloads

Valid Payload (for creating a new ticket)

{
  "title": "Database connection is failing on staging",
  "description": "Users are unable to log in to the staging environment. Logs show 'Communications link failure'. Please investigate.",
  "status": "OPEN",
  "priority": "CRITICAL",
  "requesterEmail": "dev.lead@example.com",
  "assignedTo": "dba.team@example.com"
}

Invalid Payload

This payload would be rejected by the validation layer.

{
  "title": "", // Fails @NotBlank
  "description": "The app is broken.",
  "status": null, // Fails @NotNull
  "priority": "URGENT", // Invalid enum value
  "requesterEmail": "not-an-email" // Fails @Email
}

TicketResponse

The TicketResponse DTO is the standard representation of a ticket returned by the API (e.g., from a GET request). It includes all fields from the TicketRequest plus additional system-generated fields that are managed by the persistence layer.

Design Rationale

Using a separate TicketResponse DTO allows the API to expose a read-only, enriched view of the ticket data. This prevents clients from attempting to modify system-managed fields like id or createdAt and decouples the API contract from the internal persistence model. For more on the internal model, see Core Concepts: Ticket Model.

// src/main/java/com/slalom/demo/ticketing/dto/TicketResponse.java
package com.slalom.demo.ticketing.dto;

import com.slalom.demo.ticketing.model.TicketPriority;
import com.slalom.demo.ticketing.model.TicketStatus;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDateTime;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class TicketResponse {

    private Long id;
    private String title;
    private String description;
    private TicketStatus status;
    private TicketPriority priority;
    private String requesterEmail;
    private String assignedTo;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    private LocalDateTime resolvedAt;
}

Field Descriptions

Field	Data Type	Description
id	Long	System-generated. The unique, immutable identifier for the ticket.
title	String	The title of the ticket.
description	String	The detailed description of the ticket.
status	TicketStatus	The current status of the ticket.
priority	TicketPriority	The priority level of the ticket.
requesterEmail	String	The email of the user who submitted the ticket.
assignedTo	String	The user or team assigned to the ticket. May be null.
createdAt	LocalDateTime	System-generated. The timestamp (UTC) when the ticket was created.
updatedAt	LocalDateTime	System-generated. The timestamp (UTC) of the last modification to the ticket.
resolvedAt	LocalDateTime	System-generated. The timestamp (UTC) when the ticket's status was first set to RESOLVED. May be null.

Example JSON Response

{
  "id": 101,
  "title": "Database connection is failing on staging",
  "description": "Users are unable to log in to the staging environment. Logs show 'Communications link failure'. Please investigate.",
  "status": "IN_PROGRESS",
  "priority": "CRITICAL",
  "requesterEmail": "dev.lead@example.com",
  "assignedTo": "dba.team@example.com",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T11:30:00Z",
  "resolvedAt": null
}

Status Enumeration

The TicketStatus enum defines the discrete states within a ticket's lifecycle. Using an enum ensures type safety and prevents invalid status values from being persisted.

// src/main/java/com/slalom/demo/ticketing/model/TicketStatus.java
package com.slalom.demo.ticketing.model;

public enum TicketStatus {
    OPEN,
    IN_PROGRESS,
    WAITING_ON_CUSTOMER,
    RESOLVED,
    CLOSED
}

Valid Status Transitions

While the enum itself does not enforce a state machine, the application's business logic should adhere to a defined set of valid transitions to maintain data consistency.

Developer Note: The enforcement of these transitions is handled within the TicketService layer, not at the data model or database level. Attempting to make an invalid transition (e.g., from OPEN to CLOSED) should be rejected by the service logic.

A typical state transition flow is as follows:

• OPEN -> IN_PROGRESS
• IN_PROGRESS -> WAITING_ON_CUSTOMER | RESOLVED
• WAITING_ON_CUSTOMER -> IN_PROGRESS
• RESOLVED -> CLOSED | IN_PROGRESS (if reopened)
• Any state can transition to CLOSED (e.g., if closed prematurely).

Priority Enumeration

The TicketPriority enum is used to classify the urgency of a ticket. This is critical for filtering, sorting, and prioritizing work queues. It can also be a factor in determining Service Level Agreement (SLA) response times.

// src/main/java/com/slalom/demo/ticketing/model/TicketPriority.java
package com.slalom.demo.ticketing.model;

public enum TicketPriority {
    LOW,
    MEDIUM,
    HIGH,
    CRITICAL
}

Usage in Filtering and Sorting

The API endpoints for listing tickets should support filtering and sorting by this field. For example, a client might request all CRITICAL tickets, sorted with the oldest first.

Example API query: GET /api/tickets?priority=CRITICAL&sort=createdAt,asc