Skip to content

Upgrading From 9x

Jump to bottom
Brent Cordis edited this page Mar 10, 2026 · 2 revisions

Upgrading from Proclaim 9.x to 10.x

This guide covers the full migration path from Proclaim 9.x (running on Joomla 3) to Proclaim 10.x (Joomla 5+).

Overview

Proclaim 10.x introduces a modernised architecture built on Joomla 5/6 MVC, PHP 8.3+, and a significantly improved database schema. There are two supported migration paths:

Path Best for
Upgrade Wizard Sites migrating the full Joomla 3 database to Joomla 5
Backup & Restore Sites wanting a clean Joomla 5 install with only Proclaim data imported

Minimum requirements before upgrading:

Requirement Minimum
Proclaim 9.x version 9.2.0
Joomla (new site) 5.1.0+
PHP (new site) 8.3+

Important: You must upgrade your Proclaim 9.x installation to at least 9.2.0 on your Joomla 3 site before migrating. Earlier 9.x versions use a schema that is not compatible with either migration path. Versions 7.x and earlier require a two-step upgrade (see Legacy Versions below).

Recommended Path: Upgrade Wizard

For most sites, the easiest approach is:

  1. Install a fresh Joomla 5 site with Proclaim 10.x installed
  2. Migrate your Joomla 3 database to the Joomla 5 database (standard Joomla migration)
  3. Run the Proclaim Upgrade Wizard from the Admin Center

Step-by-step

1. Back up everything

Before starting, take a full backup of your Joomla 3 site:

  • Full database dump (.sql)
  • All media files from images/ and images/com_biblestudy/ (or wherever your images are stored)

2. Install Joomla 5 + Proclaim 10.x

Set up a new Joomla 5 site. Install Proclaim 10.x from the Joomla Extension Manager.

Do not run the Joomla installation or Proclaim setup wizard — you will be migrating data into this site.

3. Migrate the Joomla 3 database tables

Use a standard Joomla migration tool (e.g. JMigration, Akeeba Kickstart, or manual SQL import) to copy the Joomla 3 database tables into the Joomla 5 database.

After the migration, both the Joomla 3-era bsms_* tables and the Proclaim 10.x tables will coexist. The Upgrade Wizard handles the conversion.

4. Run the Upgrade Wizard

  1. Go to Components → Proclaim → Admin Center
  2. Click the 9.x Upgrade tab
  3. The wizard detects your legacy schema and shows the version and record counts
  4. Click Start Upgrade

The wizard runs six sequential steps:

Step What it does
Safety Backup Creates a full database backup before any changes
Convert Parameters Converts legacy INI-style parameters to JSON format
Schema Migration Adds new 10.x tables, columns, and indexes
Data Migration Fixes menus, access levels, languages, templates, teachers, scripture references, and media paths
Rebuild Assets Rebuilds ACL permissions for all Proclaim records
Verify Checks all tables are present and removes legacy 9.x artifacts

Each step shows a status badge (Pending / Running / Done / Error). If a step fails, you can use the Retry button next to that step to re-run it without starting over.

5. Run Image Migration

After the database wizard completes, click Go to Image Tools. This takes you to the Image Tools tab where you should:

  1. Click Start Migration in the Image Migration section
  2. Wait for the migration to complete — this moves images from the old images/com_biblestudy/ folder structure to the new images/com_proclaim/ layout

This step is only needed if your 9.x site stored images in the legacy folder path. If you always used absolute server paths or a CDN, you can skip this.

6. Review templates

After migration, visit Components → Proclaim → Templates and open each template. Verify that your layout and display settings are correct. The wizard preserves all template parameters, but it is worth confirming visually.

7. Test the frontend

Visit your site's frontend and test:

  • Message/sermon listings
  • Individual message detail pages
  • Teacher pages
  • Series pages
  • Any Proclaim modules (mod_proclaim)

Alternative Path: Backup & Restore

If you prefer a clean Joomla 5 installation without migrating the full Joomla 3 database, use Proclaim's built-in backup/restore to transfer only the Proclaim data.

Step-by-step

1. Export from your 9.x site

On your Joomla 3 site with Proclaim 9.x:

  1. Go to Components → Biblestudy → Administration → Backup
  2. Click Download Backup to save the .sql file to your computer
  3. Note the backup filename — it includes the version number for reference

2. Copy media files

Download your media files from the Joomla 3 site via FTP or file manager:

Source (Joomla 3) Destination (Joomla 5)
images/biblestudy/ images/com_proclaim/
images/com_biblestudy/ images/com_proclaim/
Custom image paths used in media files Same paths on new server

If your media files are hosted externally (YouTube, Vimeo, SoundCloud, etc.), you only need to copy locally-stored images and thumbnails.

3. Install Proclaim 10.x on Joomla 5

Install Proclaim 10.x on your new Joomla 5 site through the Extension Manager. Complete the initial setup wizard — this creates the 10.x database schema.

4. Import the backup

  1. Go to Components → Proclaim → Administration → Backup tab
  2. Choose Upload File and select your 9.x backup .sql file
  3. Click Import

The restore process automatically detects the 9.x schema version and runs all necessary migrations:

  • Converts INI parameters to JSON format
  • Creates new tables and columns introduced in 10.x
  • Migrates scripture references to the junction table format
  • Fixes legacy media file paths (images/biblestudy/ → media/com_proclaim/)
  • Populates multi-teacher junction table from legacy single teacher_id field
  • Deduplicates teacher records and generates unique aliases
  • Migrates deprecated player types to HTML5
  • Sets empty access levels to Public and empty language fields to All
  • Seeds Bible translation data for the scripture popup feature

5. Upload media files

Upload the media files you copied in step 2 to the new server:

  • Place images in images/com_proclaim/ on the Joomla 5 site
  • If you had custom paths, recreate the same structure

6. Recreate site menus

Proclaim menu item view names changed between 9.x and 10.x. If you're creating menus from scratch on the new site, use the new view names:

Old 9.x View New 10.x View Description
studieslist cwmsermons Message/sermon listing
studydetails cwmsermon Single message detail
serieslist cwmseriesdisplays Series listing
seriesdetail cwmseriesdisplay Single series detail
teacherlist cwmteachers Teacher listing
teacherdisplay cwmteacher Single teacher page

If you migrated your Joomla 3 database instead of using backup/restore, the Upgrade Wizard automatically updates existing menu items with the new view names.

7. Update modules

Proclaim module names changed in 10.x:

Old 9.x Module New 10.x Module
mod_biblestudy mod_proclaim

If you previously used the mod_biblestudy module, create a new mod_proclaim module on your Joomla 5 site and configure it with the same settings.

8. Verify

Follow the Post-Upgrade Checklist below.

What the Migration Does

This section describes what happens to your data during migration, regardless of which path you use.

Parameter Format Conversion

Proclaim 9.x stored component and template parameters in Joomla 3's INI format. Migration converts all parameters to JSON format used by Joomla 5+. This affects the params column in most tables.

Scripture Reference Migration

9.x stored up to 2 scripture references as individual columns on each message (booknumber, chapter_begin, verse_begin, chapter_end, verse_end, and their *2 variants). 10.x uses a junction table (#__bsms_study_scriptures) supporting unlimited references per message.

Migration copies all existing references to the junction table. The legacy columns are preserved for backward compatibility but are no longer used for display.

Teacher Migration

9.x stored a single teacher_id per message. 10.x supports multiple teachers per message via a junction table (#__bsms_study_teachers).

Migration:

  1. Populates the junction table from the legacy teacher_id column
  2. Deduplicates teachers with identical names (keeps the lowest ID, reassigns all references)
  3. Generates unique URL-safe aliases for all teachers

Template Parameter Migration

Template parameters are renamed and reformatted:

  • Color values: 0x hex prefix → # hex prefix
  • Parameter key renames (typo corrections, prefix updates)
  • New default parameters added for features introduced in 10.x (pagination styles, view settings, etc.)
  • Media image paths updated from legacy locations

Media File Path Migration

File paths in media file parameters are updated:

Old Path New Path
images/biblestudy/ media/com_proclaim/
images/com_biblestudy/ media/com_proclaim/

Player Type Migration

Deprecated media player types are converted to the HTML5 internal player:

Old Player New Player
Player 3 (AV Plugin) Player 1 (HTML5 Internal)
Player 7 (Legacy Audio) Player 1 (HTML5 Internal)

Access Level and Language Defaults

Records with blank access levels are set to Public (view level 1). Records with blank language fields are set to All (*).

Legacy Component Cleanup

If upgrading via the database migration path, the installer automatically:

  • Removes the old com_biblestudy component record
  • Uninstalls legacy modules (mod_biblestudy, mod_biblestudy_podcast)
  • Uninstalls legacy plugins (biblestudysearch, jbspodcast, jbsbackup)
  • Updates Joomla menu items from com_biblestudy to com_proclaim

Manual Database Operations

If neither the Upgrade Wizard nor the Backup/Restore path works for your situation, you can perform the migration manually using SQL. This is an advanced procedure and requires database administration skills.

Prerequisites

  • phpMyAdmin or MySQL CLI access to the Joomla 5 database
  • The Joomla 3 database dump (or the #__bsms_* tables already imported)
  • Proclaim 10.x installed on the Joomla 5 site (creates the target schema)

Step 1: Import 9.x tables

Import your Joomla 3 #__bsms_* tables into the Joomla 5 database. If using phpMyAdmin, import only the Proclaim tables from your database dump.

Step 2: Run schema migrations

Execute the SQL migration files from administrator/components/com_proclaim/sql/updates/mysql/ in date order. Each file is named with a date prefix (e.g., 10.1.0-20251225.sql). These add new columns, tables, and indexes.

Step 3: Convert parameters

If your 9.x data has INI-format parameters, convert them to JSON. This typically affects:

  • #__bsms_admin (component settings)
  • #__bsms_templates (template parameters)
  • #__bsms_servers (server parameters)
  • #__bsms_mediafiles (media file parameters)

Step 4: Fix data integrity

Run the following data fixups (these match what CwmmigrationHelper does automatically):

-- Set empty access levels to Public (1)
UPDATE #__bsms_studies SET access = 1 WHERE access IS NULL OR access = 0;
UPDATE #__bsms_teachers SET access = 1 WHERE access IS NULL OR access = 0;
-- (repeat for: series, servers, mediafiles, podcast, topics, templatecode, comments, messagetype, books)

-- Set empty language to All
UPDATE #__bsms_studies SET language = '*' WHERE language IS NULL OR language = '';
UPDATE #__bsms_teachers SET language = '*' WHERE language IS NULL OR language = '';
UPDATE #__bsms_series SET language = '*' WHERE language IS NULL OR language = '';
UPDATE #__bsms_podcast SET language = '*' WHERE language IS NULL OR language = '';
UPDATE #__bsms_topics SET language = '*' WHERE language IS NULL OR language = '';

-- Populate multi-teacher junction table from legacy single teacher_id
INSERT IGNORE INTO #__bsms_study_teachers (study_id, teacher_id, ordering)
SELECT id, teacher_id, 1 FROM #__bsms_studies WHERE teacher_id IS NOT NULL AND teacher_id > 0;

-- Migrate deprecated player types to HTML5
UPDATE #__bsms_mediafiles
SET params = REPLACE(params, '"player":"3"', '"player":"1"')
WHERE params LIKE '%"player":"3"%';
UPDATE #__bsms_mediafiles
SET params = REPLACE(params, '"player":"7"', '"player":"1"')
WHERE params LIKE '%"player":"7"%';

-- Fix legacy media file paths in params
UPDATE #__bsms_mediafiles
SET params = REPLACE(params, 'images/biblestudy/', 'media/com_proclaim/')
WHERE params LIKE '%images/biblestudy/%';
UPDATE #__bsms_mediafiles
SET params = REPLACE(params, 'images/com_biblestudy/', 'media/com_proclaim/')
WHERE params LIKE '%images/com_biblestudy/%';

Step 5: Rebuild assets

After data migration, rebuild the Joomla ACL asset tree for Proclaim. From the Joomla admin, go to System → Global Configuration, save without changes — this triggers an asset rebuild. Or run the rebuild from Proclaim's Admin Center.

Step 6: Verify

Check these tables exist and have data:

Table Purpose
#__bsms_studies Messages/sermons
#__bsms_teachers Teachers
#__bsms_series Series
#__bsms_mediafiles Media file records
#__bsms_servers Server configurations
#__bsms_templates Display templates
#__bsms_templatecode Template code files
#__bsms_topics Topics
#__bsms_podcast Podcasts
#__bsms_locations Locations
#__bsms_comments Comments
#__bsms_books Bible books
#__bsms_study_topics Message-topic associations
#__bsms_study_teachers Message-teacher associations
#__bsms_study_scriptures Message-scripture references
#__bsms_bible_translations Bible translation registry

Running Upgrade Steps Individually

If the Upgrade Wizard fails at a specific step, you can run each step individually using its Retry button. You can also trigger each step directly via the browser URL bar (with a valid session token):

index.php?option=com_proclaim&task=cwmadmin.upgradeBackupXHR&TOKEN=1
index.php?option=com_proclaim&task=cwmadmin.upgradeParamsXHR&TOKEN=1
index.php?option=com_proclaim&task=cwmadmin.upgradeSchemaXHR&TOKEN=1
index.php?option=com_proclaim&task=cwmadmin.upgradeDataXHR&TOKEN=1
index.php?option=com_proclaim&task=cwmadmin.upgradeAssetsXHR&TOKEN=1
index.php?option=com_proclaim&task=cwmadmin.upgradeVerifyXHR&TOKEN=1

Replace TOKEN with the form token from the page source (<input type="hidden" name="..."> in the admin form).

What each PHP helper does

Step PHP class Key method
Backup CwmbackupController upgradeBackupXHR()
Params CwmmigrationHelper migrateParams()
Schema CwmmigrationHelper runSchemaMigrations()
Data CwmmigrationHelper runDataMigrations()
Assets CwmmigrationHelper rebuildAssets()
Verify CwmmigrationHelper verifySchema()

All helpers are located in admin/src/Helper/.

Legacy Versions (before 9.x)

Versions before 9.2.0 cannot be directly migrated to 10.x. The recommended path:

Starting Version Steps
9.0.x – 9.1.x Update to 9.2.8 on Joomla 3 first, then follow this guide
7.0.x – 8.x Install Proclaim 9.2.8 on Joomla 3, run its built-in migration, then follow this guide
6.0.8 – 6.2.x Install Proclaim 9.2.8 on Joomla 3 (handles 6.0.8+ automatically), then follow this guide
6.0.x and earlier Schema too different — no automated path. Manual SQL export/transform required.

Known Migration Issues

9.x version too old

If you see "Your 9.x installation must be at version 9.2.0 or later", update your Joomla 3 site to the latest 9.x release before migrating.

Schema step fails: table already exists

This is safe to retry. The schema migration uses IF NOT EXISTS guards for all table creation. Re-running it will not cause duplicate data.

Data step warns about missing teachers or scriptures

These are warnings, not errors. The data step logs sub-step results and continues. After the wizard completes, check the Proclaim message list and verify that teacher assignments and scripture references appear correctly.

Backup file not created

The backup writes to administrator/components/com_proclaim/backups/. Ensure this directory is writable. If it is not, either fix permissions or skip the backup step (not recommended) — the Upgrade Wizard will still proceed.

Large database timeout

If migration times out on large databases (1000+ messages), increase PHP's max_execution_time to at least 300 seconds. The backup/restore path handles large datasets better than the wizard because the SQL import runs directly against the database.

Images not displaying after migration

Ensure media files were copied to the correct location (images/com_proclaim/ on the Joomla 5 site). The migration updates path references in the database, but the actual files must be moved manually.

Post-Upgrade Checklist

  • Wizard completed all 6 steps with "Done" badges (or backup/restore completed successfully)
  • Image Migration run from the Image Tools tab (if using wizard path)
  • Media files copied to images/com_proclaim/ (if using backup/restore path)
  • All templates reviewed in the template editor
  • Frontend sermon listing loads correctly
  • Frontend message detail page loads correctly
  • Teachers and series pages load correctly
  • mod_proclaim module displays correctly (if used)
  • Analytics tab shows play/view counts as expected
  • Menu items point to correct views

Rollback

If the migration fails and you need to roll back:

  1. The Safety Backup step creates a full database backup. You can find the backup file in administrator/components/com_proclaim/backups/.
  2. Use the Proclaim Backup/Restore feature (Admin Center → Backup/Restore tab) to restore this backup.
  3. Or manually restore the .sql backup file via phpMyAdmin or the CLI.

Getting Help

Getting Started

Guides

Development

Help Screens

Clone this wiki locally