Plugin Upgrade Guide

This guide explains how to identify, update, and validate OJS plugins when upgrading across OJS versions. It complements the individual migration guides by focusing specifically on plugin lifecycle management.

Focus versions

This guide covers plugin compatibility across OJS 3.3, OJS 3.4, and OJS 3.5 (including 3.5.0.4+). OJS 2.x plugins are not compatible with any OJS 3.x version.

Why Plugins Need to Be Upgraded

OJS plugins are tightly coupled to the OJS framework through:

• PKP-lib hooks — the internal event system that plugins subscribe to
• Template overrides — Smarty/Twig template files that change with each release
• Database interactions — plugins may query or extend the OJS schema
• Composer dependencies — PHP library versions bundled with OJS change across releases

When OJS upgrades any of these layers, plugins built for older versions may fail silently or throw fatal errors.

Pre-Upgrade Plugin Workflow

Follow this checklist before upgrading OJS:

1. List all active plugins — Administration → Website → Plugins (note name and version of each enabled plugin)
2. Disable all custom or community plugins — leave only PKP core plugins enabled
3. Run the OJS upgrade
4. Test core functionality without any custom plugins
5. Re-enable plugins one by one, checking for errors after each

Checking Plugin Compatibility

Method 1: Plugin's GitHub Repository

Most PKP plugins follow a branch naming convention tied to OJS versions:

Branch / Tag	Compatible OJS version
stable-3_3_0	OJS 3.3.x.x
stable-3_4_0	OJS 3.4.y.y
stable-3_5_0	OJS 3.5.x.x
main	Latest development / nightly

Check the plugin's GitHub repository for the latest release on the branch matching your OJS version.

Method 2: Plugin version.xml

Each installed plugin contains a version.xml file that declares its compatible application versions:

cat /var/www/html/ojs/plugins/generic/myplugin/version.xml

Look for the <application> and <release> values.

Method 3: PKP Plugin Gallery

Browse https://pkp.sfu.ca/ojs/ojs_plugins.html and filter by OJS version.

How to Upgrade a Plugin

Option A — Upgrade via the OJS Plugin Manager (Recommended)

1. Go to Website → Plugins → Plugin Gallery
2. Find the plugin and click Upgrade if a newer version is available
3. OJS will download and install the update automatically

Option B — Manual Upgrade via ZIP

1. Download the plugin release ZIP from GitHub (use the stable-3_5_0 branch tag)
2. In OJS: Website → Plugins → Upload a new plugin
3. Upload the ZIP file
4. The new version overwrites the existing installation

Option C — Manual Upgrade via SSH

# Navigate to the plugin directory
cd /var/www/html/ojs/plugins/generic/orcidProfile

# Pull the latest compatible release
git fetch origin
git checkout stable-3_5_0
git pull

# Or replace with a fresh download
cd /var/www/html/ojs/plugins/generic
rm -rf orcidProfile
wget https://github.com/pkp/orcidProfile/archive/refs/tags/v3.5.0.1.tar.gz
tar -xzf v3.5.0.1.tar.gz
mv orcidProfile-3.5.0.1 orcidProfile

After upgrading via SSH, clear the OJS plugin cache:

cd /var/www/html/ojs
php lib/pkp/tools/cacheClear.php

Plugin Compatibility Matrix

OJS 3.3 → OJS 3.4 → OJS 3.5.0.4

Plugin	OJS 3.3	OJS 3.4	OJS 3.5.0.4	Notes
ORCID Profile	✅	✅	✅	Re-authorise OAuth after each upgrade
CrossRef Export	✅	✅	✅	—
DOI Plugin	✅	❌ Removed	❌ Built-in	DOIs are built-in from OJS 3.4; uninstall this plugin before upgrading to 3.4
Funding	✅	✅	✅	—
Google Analytics	✅	✅	✅	—
Matomo (Piwik)	✅	✅	✅	—
PDF.js Viewer	✅	✅	✅	Fixed in 3.5.0.4 for HTTPS + strict CSP
JATS Parser	✅	✅	✅	Upgrade to latest stable
Lens Galley	✅	⚠️	⚠️	Limited maintenance; test carefully
Browse By Section	✅	✅	✅	—
Keyword Cloud	✅	✅	✅	—
Custom Block Manager	✅	✅	✅	Built-in from 3.4; no separate install needed
Hypothesis	✅	✅	✅	—
ClamAV Scanner	✅	✅	✅	—
Crossref Reference Linking	✅	✅	✅	—
Plagiarism (iThenticate)	✅	✅	✅	—
Stripe Payment	✅	✅	✅	Reconfigure payment credentials after upgrade
PayPal Payment	✅	✅	✅	—
OpenAIRE	✅	⚠️	⚠️	Check for 3.4/3.5 release
Shariff	✅	✅	✅	—
ROR	⚠️	✅	✅	Introduced in OJS 3.4 era
Reviewer Credits	✅	✅	✅	—
Static Pages	✅	✅	✅	—
Web Feed	✅	✅	✅	—
Usage Stats	✅	✅	✅	COUNTER 5 support added in 3.4
Quick Submit	✅	✅	✅	—
Native XML Import/Export	✅	✅	✅	Export format changed in 3.4 — re-export for new format
Subscription SSO	✅	⚠️	⚠️	Community-maintained; test carefully

Legend:
✅ Fully compatible — ⚠️ Partial or untested — ❌ Removed or replaced

Special Cases

DOI Plugin Removal (OJS 3.3 → OJS 3.4)

The standalone DOI plugin (plugins/generic/doi) was removed in OJS 3.4. DOI management is now a built-in feature under Settings → Distribution → DOIs.

Before upgrading to OJS 3.4:

1. Go to Website → Plugins
2. Find DOI under Generic Plugins
3. Click Disable (do not delete yet — the upgrade script migrates existing DOIs)
4. After running the upgrade, confirm DOIs appear in Settings → Distribution → DOIs
5. Then you may delete the old plugin files:

   rm -rf /var/www/html/ojs/plugins/generic/doi

Custom Block Manager (OJS 3.4+)

The Custom Block Manager is now a built-in component. If you installed it as a separate plugin on OJS 3.3, it will be superseded by the built-in version after upgrading to 3.4. Remove the standalone plugin after upgrading.

Native XML Export Format Changes

The Native XML export format changed between OJS 3.3 and 3.4. Files exported from OJS 3.3 cannot be directly imported into OJS 3.4+. Re-export your data after upgrading if you need to move articles between installations.

Troubleshooting Plugin Issues

Symptom	Likely Cause	Fix
Plugin shows "Failed" in dashboard	Incompatible with current OJS version	Disable plugin; find compatible release
Fatal PHP error after enabling plugin	Conflicting class names with updated PKP-lib	Update plugin to latest stable release
Plugin settings page blank	Template override incompatible	Clear caches; update plugin
Plugin gallery shows "Up to date" but plugin is broken	Plugin gallery not yet updated	Check plugin's GitHub for newer release and install manually
Plugin works but causes 500 errors on certain pages	Hook signature changed	Report to plugin developer; disable temporarily

Plugin Configuration After Upgrade

Some plugins require reconfiguration after an OJS upgrade, even if they were previously working:

Plugin	What to Reconfigure
ORCID Profile	Re-register OAuth application on ORCID developer portal if callback URLs changed
CrossRef Export	Verify depositor credentials and DOI prefix
Stripe / PayPal	Verify API keys (test mode vs live mode)
Google Analytics	Confirm measurement ID is still in settings
ClamAV Scanner	Verify ClamAV daemon path if server was updated
Matomo	Verify tracker URL and site ID

Further Reading

• PKP Plugin Gallery — Browse all officially listed OJS plugins
• PKP GitHub – Plugin Repositories — Plugin source code and release tags
• PKP Forum – Plugins & Themes — Community plugin Q&A
• Plugins Reference (this guidebook) — Overview of built-in and community plugins