OJS 2 to OJS 3 Upgrade Guide
Version 1.2
July 17, 2024
Copyright: Public Knowledge Project
This work is openly licensed via
CC BY-NC-SA
This guide provides an overview of best practices for upgrading Open Journal Systems (OJS) version 2.x to version 3.3.0, including troubleshooting guidelines for common upgrade problems. It is intended as a complementary guide to the How to Upgrade and Troubleshooting documentation. Before proceeding, please review this documentation to learn about the OJS upgrade workflow and how to work with your OJS installation.
Prerequisites: Backups and Environment
In preparation for the workflow documented below, you will need to complete a full backup of your OJS install before starting. In addition to this initial backup, you will need to take a full backup of your OJS install after each upgrade step has been completed. These backups will allow you to revert your install to a previous version if needed, make required adjustments to your install to fix upgrade errors, and then try the upgrade step again. The How to Upgrade documentation includes detailed instructions for backing up your OJS install. If you need to restore your install to a pre-upgrade version, the OJS config file, database, as well as the private and public files folders will need to be restored from backup.
If an upgrade fails with an error message, times out, or doesnāt full complete, you will need to revert your OJS install to the pre-upgrade version using your backup. After you have reverted your install to the pre-upgrade version, you will need to resolve the upgrade errors, and then try another upgrade attempt. This process may need to be repeated several times until the upgrade completes successfully. An upgrade will be successful if you see the following message: Successfully upgraded to version X.X.X.X
It is recommended that each upgrade step documented below is executed directly on the server via the command-line rather than via the web browser. This will allow you to control and monitor the execution of the OJS upgrade script. To ensure that the upgrade script has adequate memory available and does not time out, the following PHP CLI settings are recommended when running the OJS upgrade script:
php -d memory_limit=-1 tools/upgrade.php upgrade
Prerequisites: OJS Database
Character Encoding and Collation Settings
Before starting, inspect your OJS database and take note of your MySQL character set and collation settings:
SHOW VARIABLES LIKE 'char%';
SHOW VARIABLES LIKE 'collation%';
The result of the first query will confirm if you are using the latin1
, utf8
or utf8mb4
character set in MySQL. The result of the second query will provide you with information about your MySQL collation settings. Your MySQL connection and collation settings should be consistent with your OJS database character set.
For example, if your OJS database is using the latin1
character set, then you should also be using a compatible collation, e.g. latin1_general_ci
or latin1_swedish_ci
. Alternatively, if your OJS database is using the legacy utf8
character encoding, then the collation should be utf8_general_ci
or utf8_unicode_ci
. And if your OJS database is using the newer utf8mb4
character set then you should be using one of the supported collations for this character set, e.g. utf8mb4_general_ci
or utf8mb4_0900_ai_ci
.
Delete Search Index Data
The OJS search index tables contain a lot of data and this data should be deleted from your OJS database before starting the OJS 2.x upgrade process. This will significantly reduce the size of the OJS database and will reduce the time to execute upgrade steps and to create backups of your OJS install. After the final upgrade step to OJS 3.3.0 has been completed, the search indexes will be rebuilt, which will re-populate the search index tables in your OJS database (no data will be lost).
To delete search index data from your OJS database you will need to connect to your OJS database and execute the following MySQL commands:
TRUNCATE submission_search_objects;
TRUNCATE submission_search_object_keywords;
TRUNCATE submission_search_keyword_list;
Determine MySQL Engine
OJS 3.3.0 cannot be used with the MySQL MyISAM
engine and requires InnoDB
database tables. To check if you need to convert your existing MyISAM
tables to InnoDB
, connect to your OJS database and run the following query, replacing OJS_DBNAME
with the name of your OJS database:
SELECT DISTINCT Engine, COUNT(0) FROM information_schema.tables WHERE table_schema = 'OJS_DBNAME'
If the Engine
column in the query result includes MyISAM
then you will need to convert your MyISAM
databases tables to InnoDB
using the workflow described in the āConvert MyISAM to InnoDB Tablesā section below. Conversely, if the Engine
column in the query result includes only the InnoDB
engine then no table conversion is needed and you can proceed directly to the section āGrant REFERENCES Privilegeā.
Convert MyISAM to InnoDB Tables
This workflow only needs to be completed if you have confirmed that you have one or more MyISAM
tables in your OJS database. To convert your OJS 2.x database from MyISAM
tables to InnoDB
tables you will need to complete the following steps:
- Dump your OJS database into a text file, e.g. via
mysqldump
- Open the database dump text file using a UTF8-compatible text editor, e.g.
vi
- Replace all
MyISAM
withInnoDB
table definitions in the database dump
- Save the updated database dump text file
- Import the updated database dump into a new OJS database
The following workflow describes each of the above steps in detail.
First, you will need to generate a database dump for your OJS database and save it to a text file, e.g. ojs_database.sql
Now you can convert all table definitions in the database dump file using a text editor. For example, in the vi
text editor you can open your MySQL database dump and execute the following search-and-replace command. The goal is to replace each MyISAM
table definition with the InnoDB
engine for all MyISAM
database tables. You will be prompted to review and confirm each replacement for each table definition.
:%s/ENGINE=MyISAM/ENGINE=InnoDB/gc
The next step will be to delete your OJS database in MySQL since it will still contain the legacy MyISAM
table definitions. We will then create a new OJS database to receive the updated InnoDB
table definitions and import the converted database dump file into the new OJS database.
To delete your existing OJS database and create a new, empty OJS database, the following MySQL commands will need to be executed using a MySQL user account with DROP
and CREATE
privileges, e.g. either the OJS MySQL user or the MySQL root user.
You will need to replace your database name OJS_DBNAME
and character set OJS_DBCHARSET
with their actual values:
DROP DATABASE OJS_DBNAME;
CREATE DATABASE OJS_DBNAME DEFAULT CHARSET 'OJS_DBCHARSET';
Now that you have a new, empty OJS database, you can import your OJS database data using the updated MySQL database dump file that includes the new InnoDB
table definitions.
For the MySQL import command below, you will need to replace your database connection settings OJS_DBNAME
and OJS_DBUSER
, character set setting OJS_DBCHARSET
, and database dump filename OJS_DBDUMPFILE
with their actual values:
mysql OJS_DBNAME -u OJS_DBUSER -p --default-character-set=OJS_DBCHARSET < OJS_DBDUMPFILE
You will be prompted for the database password for the OJS MySQL user as defined in your OJS config.inc.php
file. Depending on the size of your OJS database, the import command may require substantial time to complete, e.g. up to 1 hour or more for very large databases.
Grant REFERENCES Privilege
The OJS database user will need the REFERENCES
privilege granted via MySQL in preparation for the upgrade to OJS 3.3.0.
The MySQL command below will need to be executed using a MySQL user account with the GRANT
privileges, e.g. the MySQL root user account. You will need to replace OJS_DBNAME
, OJS_DBUSER
, and OJS_DBPASSWD
with the values for your OJS database as defined in config.inc.php
:
GRANT REFERENCES ON OJS_DBNAME.* TO OJS_DBUSER@'localhost' IDENTIFIED BY 'OJS_DBPASSWD';
Preparation Checklist
Before proceeding to the first upgrade step, the following tasks should now be completed:
- Backup OJS 2.x webroot, files folder, public folder, and database
- Determine OJS database character set and collations settings
- Delete search index data from the OJS database
- Ensure all tables are using the InnoDB engine in the OJS database
- Grant REFERENCES privilege to the OJS database user
First Steps: Getting to OJS 2.4.8-5
If your install is running a version older than OJS 2.4.6 then you will first need to upgrade it to OJS 2.4.6. Versions older than OJS 2.4.6 are missing a required column in the sessions
table and the upgrade to OJS 2.4.6 adds this missing column.
If your install is running OJS 2.4.6 or newer, you will need to upgrade it to OJS 2.4.8-5. This upgrade will need to be run using a legacy version of PHP 7.x (PHP 8.x will not work).
Safety Bridge: OJS 3.2.1-5
Once your install is running OJS 2.4.8-5, you are ready to make the jump to OJS 3.2.1-5.
If your journal publishes article cover images, please ensure that you apply this patch to your OJS 3.2.1-5 install if you are deploying it via the release tarball. The patch was added after OJS 3.2.1-5 was released and provides a fix for an OJS 2.x upgrade bug with article cover images.
Before you begin the upgrade to OJS 3.2.1-5, you will need to review your OJS 2.4.8-5 supplementary files.
Supplementary Files: Submission Files or Public Galleys?
In preparation for the OJS 3.2.1-5 upgrade, you will need to decide how supplementary files should be migrated from OJS 2.4.8-5. By default, the OJS 3.2.1-5 upgrade will convert all supplementary files into article galleys that will be accessible to readers via the article landing page.
Depending on how editors and authors have been using supplementary files in OJS 2.x, this conversion to article galleys may not be appropriate or well suited for your journal. For example, some journals running OJS 2.x use supplementary files to store author agreements, competing interest statements, and lists of recommended reviewers ā these documents are considered private and are not intended for public access. In OJS 2.x, if a journal disabled the Reading Tools feature then links to supplementary files were excluded from the article landing page.
If you wish to disable the conversion of supplementary files to public galleys during the upgrade to OJS 3.2.1-5, and instead convert supplementary files to private submission files in OJS 3.2.1-5, then you will need to apply a patch to your OJS 3.2.1-5 install before starting the upgrade from OJS 2.4.8-5.
After the upgrade to OJS 3.2.1-5 has been completed, please review a sample of articles that include supplementary files to ensure that these files have been migrated correctly from OJS 2.4.8-5, i.e. to ensure that supplementary files are either publicly visible as article galleys or hidden from public access and stored as private submission files in OJS 3.2.1-5.
Final Step: OJS 3.3.0
Once you have successfully upgraded to OJS 3.2.1-5 then you can upgrade to the latest OJS 3.3.0 release, which includes long-term support from PKP.
In general, the upgrade from OJS 3.2.1 to OJS 3.3.0 should finish relatively quickly since there are no updates to the OJS private files folder where submission files and galley files are stored.
Rebuild Search Index
Since we deleted the OJS search index data before starting the upgrade workflow, we now need to rebuild the search index via the following PHP command, executed in the OJS webroot folder:
php tools/rebuildSearchIndex.php
Troubleshooting Common Problems
Plugin Version Errors
- Problem: The last step in the upgrade,
addPluginVersions
, will fail if there is a plugin in the OJS plugins folder that is out of sync with the plugin version in the database. If the plugin version in the plugins folder is older than the plugin version recorded in the database, the OJS upgrade script will return a āCannot Downgrade Pluginā error.
- Solution: Since updating plugin versions is the last step in the OJS upgrade script, the above error indicates that OJS has completed the upgrade with the exception of final plugin version checks. At this stage you can proceed in one of two ways:
- Manually update the OJS
versions
table and insert a new row for the OJS 3.3.0 version, ensuring that you mark this version of OJS as the current version. This will manually finalize the upgrade to OJS 3.3.0.
You can do this by running the following two MySQL queries:UPDATE versions SET current = '0' WHERE product = āojs2ā;
In the MySQL query below, please adjust the four OJS version parameters to match the actual version that you are upgrading to. The query below assumes OJS 3.3.0-17.
INSERT INTO versions VALUES ('3', '3', '0', '17', now(), '1', 'core', 'ojs2', '', '0', '1');
After the
versions
table has been manually updated, you can delete the specific plugin that caused the error from the OJS plugins folder and then manually re-install the plugin as Journal Manager via the OJS Plugin Gallery. In addition, all other plugins marked as available for upgrade in the Plugin Gallery should be upgraded via the Plugin Gallery to the latest plugin version compatible with OJS 3.3.0.
- Alternatively, you can delete the specific plugin that caused the error from the OJS plugins folder, roll back your install to OJS 3.2.1 using your pre-upgrade backup, and re-run the upgrade to 3.3.0. Depending on how many plugins are causing upgrade errors, you may need to repeat this step multiple times. After the upgrade to OJS 3.3.0 has successfully completed, you will need to manually install all plugins that were deleted from the OJS plugins folder as Journal Manager via the OJS Plugin Gallery. In addition, all other plugins marked as available for upgrade in the Plugin Gallery should be upgraded to the latest version compatible with OJS 3.3.0.
- Manually update the OJS
Null Review Round IDs
- Problem: The upgrade from OJS 3.2.1 to OJS 3.3.0 fails due to null
review_round_ids
in thereview_assignments
table.
- Solution: First, roll back your install to OJS 3.2.1 using your pre-upgrade backup. Once the database has been restored, run the following
UPDATE
query in MySQL to manually setreview_round_id
in thereview_assignments
table:UPDATE review_assignments, review_rounds SET review_assignments.review_round_id = review_rounds.review_round_id WHERE review_assignments.submission_id = review_rounds.submission_id AND review_assignments.round = review_rounds.round;
Following the above
UPDATE
, you can check if there are any remaining nullreview_round_id
columns remaining via the followingSELECT
query:SELECT * FROM review_assignments WHERE review_round_id IS NULL;
If the above query returns one or more rows then you will need to inspect each row manually and determine whether the row corresponds to any valid submissions in your OJS install. If they do not, then the null rows can be deleted from the
review_assignments
table.
TinyMCE
- Problem: Occasionally the TinyMCE plugin may not be installed or enabled after the upgrade. This leads to āAPI Key Missingā notification errors when viewing the OJS 3.x dashboard, as well as broken input and settings forms.
- Solution: In OJS 3.x, as Journal Manager enable the TinyMCE plugin via Settings > Website > Plugins.
Language Settings
- Problem: Occasionally a journal will not upgrade/migrate itās installed language settings (UI settings, submission languages, metadata language settings). In OJS 3.x, this can be seen if you load the dashboard as Journal Manager or Editor ā many tabs will be missing input and settings forms.
- Solution: In OJS 3.x, as Journal Manager enable all journal languages via Settings > Journal.
Database Character Encoding Issues
- Problem: The OJS database includes a mix of Latin1 and UTF8 tables or Latin1 tables with UTF8 data that result in display errors with accented characters on the journal homepage, article pages, or in search results.
- Solution: You will need to review your OJS database to identify the source of the error and correct your database to ensure that you have consistency across your character encoding, collation, and stored data. Please review the Character Encoding section in the PKP Docs Troubleshooting Guide.
MySQL Foreign Key Errors
- Problem: MySQL queries fail with foreign key errors.
- Solution: OJS 3.3.0 requires
InnoDB
database tables. If your MySQL database is usingMyISAM
tables, you will need to convert these toInnoDB
before running the upgrade to OJS 3.3.0. Please see the āConvert MyISAM to InnoDB Tablesā section for additional information.
MySQL Privilege Errors
- Problem: MySQL queries fail with reference permission errors.
- Solution: The OJS database user account will need the
REFERENCES
privilege granted in preparation for the upgrade from 3.2.1 to 3.3.0. Please see the āGrant REFERENCES Privilegeā section for additional information.
Additional Resources
If you encounter problems that are not covered by this guide, you can find additional resolution suggestions via the PKP Forum, which are contributed by the global OJS user community and PKP staff. If your forum search does not produce any relevant results, please consider posting your question and error report.