IndicatorSubmission

Intro

The IndicatorSubmission model stores the actual submission data when administrators complete their assigned indicator tasks. It serves as the central data store for indicator values, file attachments, and submission metadata.

Model and Relationships

The IndicatorSubmission model has the following key relationships:

• Task: Belongs-to relationship with IndicatorTask model
• Submitter: Belongs-to relationship with User model (submitted_by_user_id)
• Attachments: Has-many relationship with IndicatorSubmissionAttachment model
• Reviews: Has-many relationship with IndicatorSubmissionReview model through review tasks

Key Fields

Core Data Fields

• indicator_task_id: Links to the original assigned task
• submitted_by_user_id: User who created the submission
• value: The main indicator value/data (can be numeric or text)
• comment: Optional comment from the submitter
• submitted_at: Timestamp of submission

Status Fields

• status: Current submission status using IndicatorSubmissionStatusEnum
• verification_level: Current verification level (0 = not started, 1 = level 1, 2 = level 2)

Status Management

Uses IndicatorSubmissionStatusEnum for status tracking:

• PENDING_VERIFICATION_1: Initial status when submission is created if the task requires verification
• PENDING_VERIFICATION_2: After level 1 verification is approved and the task requires level 2 verification
• REJECTED: Set when verification is rejected
• APPROVED: Final status when all verifications are approved

Display Attributes

displayStatus()

Returns the submission status enum for programmatic use:

public function getDisplayStatusAttribute(): IndicatorSubmissionStatusEnum
{
    return $this->status;
}

displayLabel()

Returns user-friendly status text:

public function getDisplayLabelAttribute(): string
{
    return match($this->status) {
        IndicatorSubmissionStatusEnum::PENDING_VERIFICATION_1 => 'In Verification (Level 1)',
        IndicatorSubmissionStatusEnum::PENDING_VERIFICATION_2 => 'In Verification (Level 2)',
        IndicatorSubmissionStatusEnum::REJECTED => 'Rejected',
        IndicatorSubmissionStatusEnum::APPROVED => 'Approved',
    };
}

File Attachments

Submissions can have multiple file attachments stored in the indicator_submission_attachments table:

// Access attachments
$submission->attachments; // Collection of IndicatorSubmissionAttachment models

// Files are stored on the disk returned by IndicatorSubmissionAttachment::getDisk()
// e.g. 'indicator_submissions' (S3) in production, 'indicator_submissions_local' during testing

Event Integration

The model triggers events at key lifecycle points:

• Created: Dispatches IndicatorSubmissionSubmitted event
• Status Updates: Related events (IndicatorSubmissionApproved, IndicatorSubmissionRejected) are dispatched by verification actions

Usage in Service Layer

The IndicatorSubmissionService handles creation and manages the submission workflow:

// Standard creation (controller usage)
$service = new IndicatorSubmissionService();
$submission = $service->createSubmission($data, auth()->user());

// Filament integration (adapter pattern)
$submission = $service->createSubmissionFromFilament($filamentData, auth()->user(), $indicatorTaskId);

Verification Workflow Integration

Submissions integrate with the verification workflow through:

1. Creation: Triggers Level 1 verification task creation
2. Level 1 Approval: May trigger Level 2 verification task creation
3. Final Approval: Updates related IndicatorTask to COMPLETED status
4. Rejection: Updates related IndicatorTask to NEEDS_REVISION status

Query Patterns

User-scoped Queries

// Get submissions for current user's tasks
$submissions = IndicatorSubmission::whereHas('task', function($query) {
    $query->where('responsible_user_id', auth()->id());
})->get();

Status-based Filtering

// Get submissions pending verification
$pending = IndicatorSubmission::where('status', IndicatorSubmissionStatusEnum::SUBMITTED)->get();

With Related Data

// Eager load related data for performance
$submissions = IndicatorSubmission::with([
    'task.indicator',
    'task.entrepreneur',
    'task.organisation',
    'attachments'
])->get();

Important Notes

• Submissions are immutable once created (revisions create new submissions)
• File attachments are managed separately but are automatically handled by the service layer
• The verification level tracks progression through the multi-level approval process
• Status changes trigger automatic updates to the related IndicatorTask status