5 Steps to OJS 3: Upgrade Planning for Service Providers
We’ve recently been asked for advice on how to best plan for upgrading to OJS 3. OJS 3 is a significant upgrade from the old OJS 2.x line, which means you will need to do some careful planning with your editors to ensure a smooth process.
In many ways, the changes are more human resources related (i.e., training and visual design) than technical, so you’ll want to build in time for that, as well as clear communications at each stage.
Here are the five steps we recommend to get you successfully to OJS 3.
Step 1: Sandbox Upgrade
Have your technical staff familiarize themselves with the upgrade steps included in the download files with the latest version of OJS 3, available from the PKP website.
Create a sandbox where you can perform a test upgrade. This is also a good time to make a backup of your installation.
To make a sandbox, you’ll need to unpack the new version of OJS 3 into a new area on your web server (where it won’t interfere with your existing OJS 2 install), and create copies of your database, files directory, and public directory to use for the OJS 3 sandbox.
Performing a sandbox upgrade will give you an indication of how long the upgrade process will take, and whether any additional cleanup or tweaking will be required. It can also provide an opportunity to tour some of the new features in OJS 3.
In order to prevent your OJS 3 sandbox from being accidentally accessed or indexed, we recommend limiting access to the sandbox to only authorized users via a NoIndex directive or basic authentication provided by your webserver. Both of these are typically accomplished using a .htaccess file, but the details will depend on your web server configuration.
You may also wish to prevent the OJS 3 sandbox installation from sending emails to real people while you complete your evaluation and review. You can do this by changing the email addresses in your sandbox database using this SQL query:
UPDATE users SET email = CONCAT(email, 'test');
Next, edit your config.inc.php configuration file in the sandbox installation to add the details from your existing OJS 2 install, but make sure to specify the copies of your database and files directory rather than the production versions in use by your existing OJS 2 install. Follow the instructions in docs/UPGRADE to upgrade the database. (This will also rearrange your files directory, which is why it’s important to make a copy!)
If the upgrade completes successfully, login to the OJS 3 sandbox install and review that all submissions and files are present and that everything is displaying correctly.
Common issues you may face include:
- Fatal error messages during the upgrade process. This usually indicates that there was a data inconsistency in your OJS 2.x database; search the PKP Community Forum for similar messages.
- Warnings of the form “PHP Notice: unserialize(): Error at offset…” This indicates that you may have accidentally changed the character set configuration in your config.inc.php or while creating your sandbox database.
In this video, Alec Smecher gives an overview of the upgrade process:
If you have any questions, post them to the PKP Community Forum. Once you are satisfied that everything looks good, proceed with the next step.
Step 2: Announce the Upgrade
Let your editors know that you are planning an upgrade to OJS 3 in X weeks from today (give a specific date). Let them know that their journal will go offline on that day between specific hours (e.g., between 9am and noon) while the system is upgraded. (The sandbox upgrade should give you a sense of how long the upgrade script takes to run.)
The number of weeks between this announcement and going live is up to you, but a minimum of 4 is recommended, possibly longer if it is occurring at a busier time of the year for the journal.
As part of your announcement, provide your editors with a link to What’s New in OJS 3 to give them a sense of the upcoming changes. You may want to review these changes with the editors as part of an in-person workshop. This can be a great opportunity to build a more direct relationship with your editors, as well as facilitate a community of practice among your editors, who may not know one another. Take advantage of this time to also introduce aspects of publishing they may have been missing, such as digital preservation (via the PKP PN), DOIs, ORCID, licensing, etc.
Provide your editors with links to PKP School courses on Setting up a Journal in OJS 3 and Editorial Workflow in OJS 3. You may choose to leave it to them to learn independently, or provide an in-person workshop.
It may also be a good time to review with the editors the current selection of themes (e.g., Default, Manuscript, Health Science, Traditional [currently in beta], etc.) to see if there is one that they would like to use. It is important to let them know that the current look of their OJS 2 journal will change as part of the upgrade. If they wish to create their own unique theme, take a look at the PKP Theme Guide to help them develop something unique that won’t impact future upgrades.
OJS 2.x themes and layout modifications are not easily transferable to OJS 3.x, but OJS 3.x does include some great new tools to make attractive design easier and more maintainable.
With respect to journal data, editors can be assured that all articles published in OJS 2.x as well as all submissions, peer reviews, and user accounts (including usernames and passwords) will remain in place in OJS 3 after the upgrade.
Finally, provide the editorial team with a link to the OJS 3 sandbox to give everyone an opportunity to review the upgraded data and to start experimenting with the new user interface and working through available training materials.
Step 3: Confirm they are Ready
In the week before the scheduled upgrade, confirm with all of your editors that they are ready to go. Ideally, they are all prepared. Now is the time to decide whether to delay or stay on schedule.
Step 4: Go Live
On the set day, at the set time, take your OJS 2.x journal offline, and follow the instructions in docs/UPGRADE to upgrade the software. Ensure that you make a complete backup of your database and ‘files’ folder before starting the backup process. When the upgrade completes successfully, inform the editors so they can login and start working.
If your OJS installation doesn’t already have the ‘files’ folder located outside of the web accessible OJS installation, please move it now. Failure to meet this requirement is the only significant security risk faced by OJS journals. See the “Recommended Configuration” section of the README document included in your OJS download files for details.
Step 5: Evaluate, and Prepare for Further Training
Follow up with the editors after the upgrade has been completed to ensure everything went well and that they are satisfied with the process. Catch any concerns now and make any necessary changes.
It has been our experience that, regardless of the amount of pre-upgrade training and preparation you provide, you will find that your user community will still have many, many new questions for you. Some of their questions could just as easily have been asked during the pre-upgrade process, but it seems that they are often asked once the upgrade has been completed.
Regardless, you will almost certainly find yourself answering additional questions after the upgrade has been completed, and it may be a good practice to prepare in advance for this, perhaps with additional post-upgrade training opportunities.
We’d love to hear your experiences with upgrading to OJS 3, and if there is anything we can do to make the process easier for you. Please drop us a note on the Community Forum, and keep asking us questions there.
If these steps are more than what you have time for, PKP Publishing Services provides a variety of support options to assist you with your upgrade process and day-to-day platform management, from hourly consultation to full hosting support. For more information, contact us at firstname.lastname@example.org, or take a look at our support options at https://pkpservices.sfu.ca.