Skip to main content

v1.9.3 Technical Notes

Audience

This document is for developers and system administrators. End users should refer to the CA System Guide and School Admin Guide instead.

This document captures technical decisions, migrations, and upgrade considerations for the v1.9.3 release.

Database Migrations Required​

The following migrations must be run when upgrading to v1.9.3.

1. School Database Migrations (Multi-Tenant)​

These run on each school's database (eschool_saas_*):

php artisan migrate:school

Migrations included:

  • 2026_04_28_131900_version1_9_3_create_terms_table.php

    • Creates terms table for Term Exams (multi-tenant per school)

  • 2026_04_28_132000_version1_9_3_create_continuous_assessments_table.php

    • Creates continuous_assessments table for CA configuration

  • 2026_04_28_132100_version1_9_3_modify_exam_tables_for_ca.php

    • Adds term_id and exam_weightage to exams
    • Adds ca_type and total_marks to exam_marks
    • Adds term_total, session_cumulative_average, session_position, term_id to exam_results

2. Main Database Migration​

This runs on the main database (stage4sch or production equivalent):

php artisan migrate

Migration:

  • 2026_04_30_000000_add_syllabus_permissions_to_existing_schools.php
    • Iterates all installed schools
    • Adds syllabus permissions to each school's School Admin role
    • Required for schools created before v1.9.2

Architecture Decisions​

Multi-Tenant Permissions​

Each school has its own database containing:

  • permissions table
  • roles table
  • role_has_permissions table

The main database only contains the Super Admin role and global permissions. When adding new permissions for a feature:

  1. Update SchoolDataService::createSchoolDatabaseData() for new schools
  2. Create a backfill migration for existing schools (see syllabus permissions migration as reference)

Term Exam Architecture​

Term Exams are stored in school databases (per-tenant), NOT the main database:

  • Allows each school to have its own term structure
  • Maintains data isolation between schools
  • Foreign keys to local exam tables work properly
  • Cross-database foreign keys are avoided

Why this matters: A previous attempt placed Term Exams in the main database, causing SQL errors when joining with school-specific exam tables.

CA-Aware Result Calculation​

The publishExamResult method uses COALESCE for backward compatibility:

SUM(COALESCE(exam_marks.total_marks, exam_timetables.total_marks)) as total_marks

This pattern:

  • Prefers exam_marks.total_marks (per-CA value, set during marks entry)
  • Falls back to exam_timetables.total_marks (subject's pre-defined max)
  • Allows mixed CA-enabled and traditional exams in the same system

Upgrade Considerations​

For Hosted Deployments​

  1. Pull latest code from staging branch
  2. Install/update dependencies: 
    composer install --no-dev --optimize-autoloader
    npm install --production
  3. Run migrations: 
    php artisan migrate
    php artisan migrate:school
  4. Clear all caches: 
    php artisan cache:clear
    php artisan config:clear
    php artisan view:clear
    php artisan route:clear
  5. Verify by logging in as a School Admin and checking:
    • Manage Term Exams menu visible (under Offline Exam)
    • Manage Syllabus menu visible (under Class)
    • CA Configuration accessible from Manage Exam

Browser Cache Considerations​

Several frontend assets now use cache busting via filemtime():

  • custom.js
  • validate.js
  • function.js
  • common.js

This ensures users get fresh JavaScript without manually clearing browser cache. After deployment, the version query string will change automatically.

Known Issues Resolved​

SQL Ambiguous Column Error​

Error:

SQLSTATE[23000]: Integrity constraint violation: 1052
Column 'total_marks' in SELECT is ambiguous

Cause: Both exam_marks and exam_timetables have total_marks column after CA migration.

Fix: Explicit table prefix and COALESCE in ExamController@publishExamResult and related queries.

Spatie Permission Cache​

After running the syllabus permissions migration, the Spatie permission cache may be stale.

Resolution:

php artisan permission:cache-reset

Or manually clear cache:

php artisan cache:clear

jQuery Repeater Single-Item Edge Case​

The jQuery repeater plugin (used in Class Subject form) sometimes serializes single items as objects instead of arrays.

Defensive code added in ClassSchoolController@classSubjectUpdate:

// Handle single-item serialization edge case
if (is_array($subjects) && isset($subjects['id'])) {
    $subjects = [$subjects];
}

File Reference​

Key Files Modified in v1.9.3​

Backend:

  • app/Http/Controllers/Exam/ExamController.php - CA support, SQL fixes
  • app/Http/Controllers/ContinuousAssessmentController.php - CA configuration API
  • app/Http/Controllers/TermController.php - Term Exam management
  • app/Http/Controllers/ClassSchoolController.php - Validation fixes
  • app/Models/Term.php, ContinuousAssessment.php - New models
  • app/Services/ResultService.php - CA calculations
  • app/Services/HelpService.php - In-app help system
  • app/Console/Commands/GenerateHelpContent.php - Help generation

Frontend:

  • resources/views/exams/partials/ca_configuration_modal.blade.php
  • resources/views/exams/index.blade.php - Term Exam selector, Configure CAs button
  • resources/views/exams/upload-marks.blade.php - CA Type selector
  • resources/views/terms/index.blade.php - Term Exams management
  • resources/views/components/help-tooltip.blade.php - Reusable tooltip
  • public/assets/js/custom/custom.js - Repeater fixes
  • public/assets/js/custom/validate.js - Duplicate validation fix
  • public/assets/css/custom.css - Modal styling, tooltip z-index

Support & Troubleshooting​

For end-user troubleshooting, see:

For developer questions, contact the engineering team or refer to inline code comments in the modified files.

Last Updated: v1.9.3 release Next Review: v1.10.0 release planning

Last updated on