Skip to main content
OJS for Everyone Logo
OJS for EveryoneThe Practical GuidebookRSYN Research LLP

OJS Migration Guide: Moving from OJS 3.3.x.x to OJS 3.4.y.y

Role: Site Administrator
Time: 45–90 minutes
Source: OJS 3.3.0-x (any 3.3 patch release)
Target: OJS 3.4.0-8 (latest 3.4 series release)

Back up before proceeding

Before running any upgrade, take a full backup of your database and files directory. Upgrades cannot be automatically reversed.

What Changed in OJS 3.4​

OJS 3.4 introduced several significant architectural changes that affect migration:

AreaChange
DOI systemDOIs moved from a plugin to a built-in first-class feature; the legacy DOI plugin is removed
Submission workflowSubmission wizard redesigned; new contributor/metadata step
Database schemaMultiple new tables and column changes for the new DOI system
PHP requirementMinimum raised to PHP 8.0 (PHP 8.1+ recommended)
MySQL requirementMinimum raised to MySQL 8.0
PostgreSQL requirementMinimum raised to PostgreSQL 12 (14+ recommended)
Plugin APISeveral legacy hooks deprecated; plugin updates required
Email systemMailable system introduced; email templates restructured
REST APIv1 endpoints expanded; submission and file endpoints changed
Job queueBackground jobs system introduced (optional scheduler)

Pre-Migration Checklist​

  • Confirm you are running the latest 3.3.x.x release (3.3.0-19); apply any pending 3.3 patches first
  • Full database backup: mysqldump -u ojsuser -p ojs > ojs_backup_$(date +%Y%m%d).sql
  • Files directory backup: tar -czf ojs-files-$(date +%Y%m%d).tar.gz /var/www/ojs-files
  • Config backup: cp config.inc.php config.inc.php.bak
  • Verify PHP is 8.0 or higher (php -v)
  • Verify MySQL is 8.0+ or PostgreSQL is 12+
  • Disable the DOI Plugin (it will be removed by the upgrade): Administration → Website → Plugins → Generic Plugins → DOI → Disable
  • Note all other active plugins
  • Test on a staging server before applying to production

Migration Steps​

Step 1 — Update to Latest OJS 3.3.x.x​

If you are not on the latest 3.3 patch release, upgrade there first:

# Check current version
php tools/upgrade.php check

Step 2 — Put the Site in Maintenance Mode​

Edit config.inc.php:

[general]
installed = On
; Add this line to prevent access during upgrade
maintenance = On

Or restrict access at the webserver level.

Step 3 — Download OJS 3.4​

cd /tmp
wget https://pkp.sfu.ca/software/ojs/download/ojs-3.4.0-8.tar.gz
tar -xzf ojs-3.4.0-8.tar.gz

Step 4 — Replace Application Files​

# Backup your config
cp /var/www/html/ojs/config.inc.php /tmp/config.inc.php.bak

# Replace application files, preserving config, public/, and cache/
rsync -av --delete \
  --exclude='config.inc.php' \
  --exclude='public/' \
  --exclude='cache/' \
  --exclude='.htaccess' \
  /tmp/ojs-3.4.0-8/ /var/www/html/ojs/

# Restore config
cp /tmp/config.inc.php.bak /var/www/html/ojs/config.inc.php

Step 5 — Run the Upgrade Script​

cd /var/www/html/ojs
php tools/upgrade.php upgrade
DOI migration

The upgrade script automatically migrates any DOIs registered through the old DOI plugin into the new built-in DOI system. Review the output carefully for any DOI migration warnings.

Monitor the output closely. A successful upgrade ends with:

Successfully upgraded Open Journal Systems.

Step 6 — Clear All Caches​

php lib/pkp/tools/cacheClear.php

Or use Administration → Clear Caches in the admin panel.

Step 7 — Update File Permissions​

chown -R www-data:www-data /var/www/html/ojs
find /var/www/html/ojs -type f -name "*.php" -exec chmod 644 {} \;
find /var/www/html/ojs -type d -exec chmod 755 {} \;

Step 8 — Re-enable and Update Plugins​

Many plugins require updates for OJS 3.4 compatibility. For each plugin:

  1. Check the plugin's GitHub repository for a 3.4-compatible release
  2. Download and install the updated version
  3. Re-enable the plugin

See the Plugin Upgrade Guide for a compatibility matrix.

Step 9 — Configure the New DOI System​

OJS 3.4 replaces the DOI plugin with a built-in DOI management system:

  1. Go to Settings → Distribution → DOIs
  2. Enable DOIs for the desired content types (Articles, Issues, Galleys)
  3. Set your DOI prefix (e.g., 10.12345)
  4. Configure the DOI suffix pattern
  5. If using CrossRef, go to Tools → Import/Export → CrossRef XML Export to reconfigure your credentials

Step 10 — Configure the Job Queue (Optional)​

OJS 3.4 introduces a job queue for background processing:

# Add to crontab to process jobs every minute
* * * * * cd /var/www/html/ojs && php lib/pkp/tools/jobs.php run >> /var/log/ojs-jobs.log 2>&1

Or enable the built-in task runner in config.inc.php:

[general]
scheduled_tasks = On

Step 11 — Disable Maintenance Mode​

Remove or comment out the maintenance = On line in config.inc.php.

Post-Migration Verification Checklist​

  • Site loads without errors at the main URL
  • Administrator can log in
  • All journals appear under Administration → Hosted Journals
  • Existing submissions appear in the correct workflow stages
  • Published articles are accessible with their original URLs
  • Galley files (PDF, HTML) download correctly
  • DOIs are visible on article pages and in the DOI settings panel
  • Email sending works (test from Settings → Website → Emails)
  • Statistics display correctly
  • CrossRef/DataCite export plugin functions (if used)

Common Issues​

IssueCauseSolution
"Unknown column" SQL errorUpgrade script stopped partwayRe-run php tools/upgrade.php upgrade
DOI plugin still showing after upgradePlugin files not fully replacedDelete plugins/generic/doi if it persists; DOIs are now built-in
Email templates missingMailable system restructured templatesGo to Settings → Workflow → Emails and reset templates to defaults
Submission wizard brokenCached JS/CSS from old versionClear browser cache and run php lib/pkp/tools/cacheClear.php
"Class not found" PHP errorsComposer autoloader not rebuiltRun composer install --no-dev from the OJS root
Plugin incompatibility errorsPlugin built for OJS 3.3Disable plugin; find 3.4-compatible version
Job queue not processingCron not configuredAdd cron entry or enable scheduled_tasks in config

Key Differences to Communicate to Journal Managers​

After upgrading, brief your Journal Managers on these changes:

  1. New submission wizard — the contributor entry step is now separate from metadata
  2. DOI management — DOI settings are now under Settings → Distribution → DOIs (not a plugin)
  3. Email templates — the Mailable system groups emails by workflow event; templates may need review
  4. Review forms — no changes, but reassign reviewers if any are in limbo states
  5. Statistics — COUNTER 5 reports are now available alongside COUNTER 4

Next Steps​

After a successful migration to OJS 3.4, continue upgrading to 3.5:

  1. Follow the general Upgrading OJS guide
  2. Then apply the OJS 3.5.0.x → 3.5.0.4 Migration Guide

Further Reading​