Get Import Errors

Overview Description

The Get Import Errors feature allows clients to retrieve validation errors for a specific upload history. This feature provides detailed error information including field headers, problematic values, line numbers, and error messages. The errors are stored in a separate table and linked to the upload history, enabling comprehensive error tracking and debugging for failed CSV imports.

Swagger Link

API: Upload Histories API

Case Documentation

Case 1: Get Import Errors for History

Description

Client requests detailed validation errors for a specific upload history record.

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Repository as ReviewUploadErrorRepository
    participant Resource as ImportReviewCSVErrorResource
    participant Database as Database
    
    Note over Client,Database: Get Import Errors Flow
    
    rect rgb(200, 255, 200)
    Note right of Client: Happy Case Flow
    
    Client->>API: GET /api/v1/general/upload-file/gcs/histories/{id}/import-errors
    
    rect rgb(200, 230, 255)
    Note right of API: Input Validation
    API->>API: Validate history ID and pagination parameters
    end
    
    rect rgb(200, 255, 255)
    Note right of API: Business Logic
    API->>Repository: serverPaginationFilteringFor(historyId, params)
    Repository->>Repository: Apply history ID filter and pagination
    Repository->>Database: SELECT review_upload_errors with pagination
    Database-->>Repository: Return paginated error results
    Repository-->>API: Return LengthAwarePaginator
    end
    
    rect rgb(255, 255, 200)
    Note right of API: Resource Transformation
    API->>Resource: collection(errors)
    Resource->>Resource: Transform each error record
    Resource-->>API: Return formatted collection
    end
    
    API-->>Client: 200 OK (formatted error data)
    end
    
    rect rgb(255, 200, 200)
    Note right of Client: Error Handling
    rect rgb(255, 230, 230)
    alt Validation Error
        API-->>Client: 422 Validation Error
    else Not Found Error
        Database-->>Repository: No matching errors
        Repository-->>API: Null result
        API-->>Client: 404 Not Found
    else Database Error
        Database-->>Repository: Database error
        Repository-->>API: Error result
        API-->>Client: 400 Bad Request
    end
    end
    end

Steps

Step 1: Request Import Errors

• Description: Client requests validation errors for specific upload history
• Request: GET /api/v1/general/upload-file/gcs/histories/{id}/import-errors
• Parameters:
  • id: The unique identifier of the upload history record (required)
  • per_page: Number of records per page (optional, default: 10)
  • page: Page number for pagination (optional, default: 1)
• Validation:
  • History ID must be a valid integer
  • Per page must be a positive integer
  • Page must be a positive integer

Step 2: Retrieve Error Data

• Description: System retrieves validation errors for the specified history
• Action:
  • Query review_upload_errors table filtered by history ID
  • Apply pagination to error results
  • Include all error fields (header, value, error_line, error_messages)
  • Return paginated error collection

Step 3: Transform and Return Results

• Description: Transform error data and return to client
• Response:
  • Success: 200 OK with formatted error collection including metadata
  • Error: Appropriate error code with message

Database Related Tables & Fields

erDiagram
    review_upload_histories {
        bigint id PK
        bigint user_id FK "Reference to users table"
        bigint group_id FK "Reference to groups table"
        string file_name "Name of the uploaded file"
        string gcs_path "Google Cloud Storage path where file is stored"
        tinyInteger status "Upload status: 0=Notyet, 1=processing, 2=success, 3=fail"
        string error_reason "Error message if upload failed (nullable)"
        timestamp validated_at "Timestamp when file was validated (nullable)"
        timestamp created_at
        timestamp updated_at
    }
    review_upload_errors {
        bigint id PK
        bigint review_upload_history_id FK "Reference to review_upload_histories table"
        string header "Field header that caused the error (nullable)"
        string value "Problematic data value (nullable)"
        integer error_line "Line number where error occurred (nullable)"
        json error_messages "Array of error messages for the field"
        timestamp created_at
        timestamp updated_at
    }

    review_upload_histories ||--o{ review_upload_errors : has_many

Error Handling

• Log
  • Import error retrieval failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  404	Import errors not found	When no errors exist for the specified history
  400	Failed to get import errors	When database operation fails
  422	Validation failed	When parameters are invalid

Key Features

• Detailed Error Information: Complete error details including field headers, values, and line numbers
• Pagination Support: Handle large error datasets with configurable pagination
• API Resource Transformation: Consistent error data formatting using Laravel resources
• History Association: Errors are linked to specific upload histories
• Error Message Arrays: Support for multiple error messages per field
• Line Number Tracking: Track specific line numbers where errors occurred

Security Considerations

• History Association: Errors are filtered by upload history ID
• Input Validation: All parameters are validated before processing
• Error Logging: Failed operations are logged for monitoring
• User Authentication: Requires authenticated user with group membership
• Data Sanitization: API resources ensure safe error data output