10 KiB

Raw Blame History

Story 8.8: Timeline Update Notification

Epic Reference

Epic 8: Email Notification System

Story Context

This story implements email notifications when admin adds updates to a client's case timeline (from Epic 4). When admin creates a TimelineUpdate record, the associated client automatically receives an email with the update details, keeping them informed of their case progress without needing to manually check the portal.

User Story

As a client, I want to be notified via email when my case timeline is updated, So that I stay informed about my case progress without having to repeatedly check the portal.

Dependencies

Requires: Story 8.1 (Email Infrastructure - BaseMailable class and templates)
Requires: Epic 4 Stories 4.1-4.2 (Timeline and TimelineUpdate models must exist)
Blocks: None

Data Model Reference

From Epic 4, the relevant models are:

Timeline
├── id
├── user_id (FK → users.id, the client)
├── case_name (string, required)
├── case_reference (string, optional, unique if provided)
├── status (enum: 'active', 'archived')
├── created_at
└── updated_at

TimelineUpdate
├── id
├── timeline_id (FK → timelines.id)
├── admin_id (FK → users.id, the admin who created it)
├── update_text (text, the update content)
├── created_at
└── updated_at

Relationships:
- TimelineUpdate belongsTo Timeline
- Timeline belongsTo User (client)
- Timeline hasMany TimelineUpdate
- Access client: $timelineUpdate->timeline->user

Acceptance Criteria

Trigger

Email sent automatically when TimelineUpdate is created
Uses model observer pattern for clean separation
Email queued for performance (not sent synchronously)
Only triggered for active timelines (not archived)

Content

Subject: "Update on your case: [Case Name]" / "تحديث على قضيتك: [اسم القضية]"
Case reference number (if exists)
Full update content text
Date of update (formatted for locale)
"View Timeline" button linking to client dashboard timeline view

Language

Email template selected based on client's preferred_language
Default to Arabic ('ar') if no preference set
Date formatting appropriate for locale

Design

Uses base email template from Story 8.1 (Libra branding)
Professional, informative tone
Clear visual hierarchy: case name → update content → action button

Technical Implementation

Files to Create/Modify

File	Action	Description
`app/Mail/TimelineUpdateEmail.php`	Create	Mailable extending BaseMailable
`resources/views/emails/timeline/update-ar.blade.php`	Create	Arabic email template
`resources/views/emails/timeline/update-en.blade.php`	Create	English email template
`app/Observers/TimelineUpdateObserver.php`	Create	Observer to trigger email
`app/Providers/AppServiceProvider.php`	Modify	Register the observer

Mailable Implementation

<?php

namespace App\Mail;

use App\Models\TimelineUpdate;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;

class TimelineUpdateEmail extends BaseMailable
{
    public function __construct(
        public TimelineUpdate $update
    ) {
        $this->locale = $this->update->timeline->user->preferred_language ?? 'ar';
    }

    public function envelope(): Envelope
    {
        $caseName = $this->update->timeline->case_name;
        $subject = $this->locale === 'ar'
            ? "تحديث على قضيتك: {$caseName}"
            : "Update on your case: {$caseName}";

        return new Envelope(
            subject: $subject,
        );
    }

    public function content(): Content
    {
        return new Content(
            markdown: "emails.timeline.update-{$this->locale}",
            with: [
                'update' => $this->update,
                'timeline' => $this->update->timeline,
                'client' => $this->update->timeline->user,
                'viewUrl' => route('client.timelines.show', $this->update->timeline),
            ],
        );
    }
}

Observer Implementation

<?php

namespace App\Observers;

use App\Mail\TimelineUpdateEmail;
use App\Models\TimelineUpdate;
use Illuminate\Support\Facades\Mail;

class TimelineUpdateObserver
{
    public function created(TimelineUpdate $update): void
    {
        // Only send for active timelines
        if ($update->timeline->status !== 'active') {
            return;
        }

        $client = $update->timeline->user;

        Mail::to($client->email)->queue(
            new TimelineUpdateEmail($update)
        );
    }
}

Register Observer

In AppServiceProvider::boot():

use App\Models\TimelineUpdate;
use App\Observers\TimelineUpdateObserver;

public function boot(): void
{
    TimelineUpdate::observe(TimelineUpdateObserver::class);
}

Arabic Template Structure (`update-ar.blade.php`)

<x-mail::message>
# تحديث على قضيتك

**اسم القضية:** {{ $timeline->case_name }}
@if($timeline->case_reference)
**رقم المرجع:** {{ $timeline->case_reference }}
@endif

---

## التحديث

{{ $update->update_text }}

**تاريخ التحديث:** {{ $update->created_at->locale('ar')->isoFormat('LL') }}

<x-mail::button :url="$viewUrl">
عرض الجدول الزمني
</x-mail::button>

مع تحياتنا,<br>
{{ config('app.name') }}
</x-mail::message>

English Template Structure (`update-en.blade.php`)

<x-mail::message>
# Update on Your Case

**Case Name:** {{ $timeline->case_name }}
@if($timeline->case_reference)
**Reference:** {{ $timeline->case_reference }}
@endif

---

## Update

{{ $update->update_text }}

**Date:** {{ $update->created_at->format('F j, Y') }}

<x-mail::button :url="$viewUrl">
View Timeline
</x-mail::button>

Best regards,<br>
{{ config('app.name') }}
</x-mail::message>

Edge Cases & Error Handling

Scenario	Handling
Archived timeline gets update	No email sent (observer checks status)
Client has no `preferred_language`	Default to Arabic ('ar')
Client email is null/invalid	Mail will fail gracefully, logged to failed_jobs
Timeline has no case_reference	Template conditionally hides reference line
Multiple rapid updates	Each triggers separate email (acceptable per requirements)

Testing Requirements

Test File

Create tests/Feature/Mail/TimelineUpdateEmailTest.php

Test Scenarios

<?php

use App\Mail\TimelineUpdateEmail;
use App\Models\Timeline;
use App\Models\TimelineUpdate;
use App\Models\User;
use Illuminate\Support\Facades\Mail;

test('email is queued when timeline update is created', function () {
    Mail::fake();

    $client = User::factory()->create(['preferred_language' => 'en']);
    $timeline = Timeline::factory()->for($client)->create(['status' => 'active']);

    TimelineUpdate::factory()->for($timeline)->create();

    Mail::assertQueued(TimelineUpdateEmail::class);
});

test('email is not sent for archived timeline updates', function () {
    Mail::fake();

    $client = User::factory()->create();
    $timeline = Timeline::factory()->for($client)->create(['status' => 'archived']);

    TimelineUpdate::factory()->for($timeline)->create();

    Mail::assertNothingQueued();
});

test('email uses arabic template when client prefers arabic', function () {
    $client = User::factory()->create(['preferred_language' => 'ar']);
    $timeline = Timeline::factory()->for($client)->create();
    $update = TimelineUpdate::factory()->for($timeline)->create();

    $mailable = new TimelineUpdateEmail($update);

    expect($mailable->locale)->toBe('ar');
});

test('email uses english template when client prefers english', function () {
    $client = User::factory()->create(['preferred_language' => 'en']);
    $timeline = Timeline::factory()->for($client)->create();
    $update = TimelineUpdate::factory()->for($timeline)->create();

    $mailable = new TimelineUpdateEmail($update);

    expect($mailable->locale)->toBe('en');
});

test('email defaults to arabic when no language preference', function () {
    $client = User::factory()->create(['preferred_language' => null]);
    $timeline = Timeline::factory()->for($client)->create();
    $update = TimelineUpdate::factory()->for($timeline)->create();

    $mailable = new TimelineUpdateEmail($update);

    expect($mailable->locale)->toBe('ar');
});

test('email contains case name in subject', function () {
    $client = User::factory()->create(['preferred_language' => 'en']);
    $timeline = Timeline::factory()->for($client)->create(['case_name' => 'Smith vs Jones']);
    $update = TimelineUpdate::factory()->for($timeline)->create();

    $mailable = new TimelineUpdateEmail($update);

    expect($mailable->envelope()->subject)->toContain('Smith vs Jones');
});

test('email contains update content', function () {
    $client = User::factory()->create(['preferred_language' => 'en']);
    $timeline = Timeline::factory()->for($client)->create();
    $update = TimelineUpdate::factory()->for($timeline)->create([
        'update_text' => 'Court date scheduled for next month.',
    ]);

    $mailable = new TimelineUpdateEmail($update);

    $mailable->assertSeeInHtml('Court date scheduled for next month.');
});

test('email contains view timeline link', function () {
    $client = User::factory()->create(['preferred_language' => 'en']);
    $timeline = Timeline::factory()->for($client)->create();
    $update = TimelineUpdate::factory()->for($timeline)->create();

    $mailable = new TimelineUpdateEmail($update);

    $mailable->assertSeeInHtml(route('client.timelines.show', $timeline));
});

Definition of Done

TimelineUpdateEmail mailable created extending BaseMailable
Arabic and English templates created with proper formatting
Observer registered and triggers on TimelineUpdate creation
Email only sent for active timelines (not archived)
Email queued (not sent synchronously)
Subject includes case name in appropriate language
Email body includes case reference (if exists), update content, and date
View Timeline button links to correct client dashboard route
All tests pass
Code formatted with Pint

Estimation

Complexity: Low | Effort: 2-3 hours

10 KiB Raw Blame History