Once you have reviewed the features of OJS 3 and decided you want to proceed with the upgrade, you will need to do some careful planning to ensure a smooth process, minimal disruption to your publication schedule, and a happy editorial staff. Many of the changes are human resources related (i.e., training and visual design), as well as technical, so clear communication is important at every stage.
The major steps in completing an upgrade are as follows:
This chapter focuses on the initial planning and human resources steps of the upgrade process. The next chapter covers technical steps.
Development of OJS is ongoing and new versions with new features are released every few months. You can be strategic in deciding when to upgrade based on when desired features will be available. For example, if a particular plugin is important to your users and it will not be available for OJS 3 until next year, you may want to wait until next year to do your major upgrade. You may also want to wait until a new release of OJS has been fully tested and bug-free, which is sometimes not the case immediately after its official release. However, if OJS 3 has all of the main features you need, scheduling the upgrade will involve other considerations which are outlined in this chapter.
For additional resources outlining the new features in OJS 3 and upgrade-related documents, see the Additional Resources section at the end of this guide.
Generally you should upgrade to the latest version of OJS. However, if the latest version is a new major release (e.g., OJS 3.1.0, OJS 3.2.0), you may want to wait until the next minor release is available (e.g., OJS 3.1.0-1; OJS 3.2.0-1) because usually a new major release has a few unexpected bugs that will be fixed in the first minor release that follows. Check the PKP website for news about releases when making this decision.
⚠️ The OJS 2.x to 3.x upgrade tools are only supported up to OJS 3.2.0-x. If you are upgrading from OJS 2.x to 3.x, we recommend upgrading to the most recent release of OJS 3.2.0. Once that is complete, upgrade from there to newer releases.
Taking into account the steps involved, create a plan and timeline for the upgrade.
Depending on whether you are an institution or publisher that hosts or supports multiple journals or if you are an administrator of a single journal, you may communicate directly with a journal’s editorial team or with a main contact at each journal who then communicates or supports an editorial team. Announce the upgrade to your editorial team or journal contacts. The upgrade will mainly affect Journal Managers, Editors, and Section Editors. They should be informed of the upcoming change, receive information about how to use the new version of OJS, and have input into the upgrade timeline. Reviewers and Authors are unlikely to be affected by the upgrade and will notice little change in their workflows.
Determine what training and support will be needed by your editorial team before and after the upgrade and how it will be provided.
The recommended server requirements for OJS 3.2.0 are:
As PKP does not have the resources to test every possible combination of software versions and platforms, no guarantee of correct operation or support is implied. We welcome feedback from users who have deployed OJS on systems other than those listed above.
Before proceeding with your upgrade it is strongly advised that you do an inventory of your journal.
During the upgrade the following items will automatically be moved from OJS 2 to OJS 3:
It is advisable that you save a copy all the data that appears on your journal pages to be re-entered into OJS 3. It might also be useful to have screenshots of all the Journal Setup from OJS 2 for reference. You will notice that there have been a number of changes that were made between OJS 2 and OJS 3, so information entered in Setup in OJS 2 will need to be entered in different places within OJS 3.
Items that will need to be re-created once you’ve upgraded to OJS 3 include the following:
We recommend that you save any customizations you made to the sandbox (images, CSS, texts) locally to re-upload as necessary to the final production version.
If your OJS 2 installation has links to uploaded PDFs or other files (e.g., subscription forms, agreements) these will need to be re-uploaded to the Publisher Library and updated in the hyperlink. The OJS 2 files directory will no longer be functional after the upgrade.
The upgrade from OJS 2 to 3 is also an opportunity to clean up any users that may be spam users, which is a common issue in OJS, particularly for instances that existed before PKP implemented reCAPTCHA on account registration. There are several ways to identify these users, but one option is through the email domains used when the user signed up. Using the following SQL query, you or your system administrator can identify the domains in order to identify possible spam users:
SELECT substring_index(email, '@', -1) domain, COUNT(*) email_count
FROM users
GROUP BY substring_index(email, '@', -1)
-- If you want to sort as well:
ORDER BY email_count DESC, domain;
Once you’ve identified the domains that are connected to spam users, you can use these to create a list of usernames to clean up with a query:
SELECT * FROM users
WHERE email LIKE "%@spam.com"
OR email LIKE "%morespam.com"
...
With this list of usernames, you can then use OJS’s built-in user merging tool (in your OJS directory at tools/mergeUsers.php) to clean up users.We created a small bash script to do this, and PKP also has a process that they recommend. You’ll need to create a user account that all accounts can be merged into if one doesn’t already exist. Keep in mind that while it’s nearly impossible to find all the spam users in a large instance of OJS, you may be able to significantly clean these up, thereby reducing the amount of data in your instance and making it easier for journal teams to manage their users. It is important to use the merging tool instead of deleting spam users from the users table, as deleting users can produce major errors in your installation.
For more information about the technical steps for upgrading your system, see the Technical Upgrade guide.
See the section below under Upgrading Your OJS Instance - Step 1 - Perform a Sandbox Upgrade
Have all journal team members who regularly use the site (e.g., Journal Managers, Editors, and Section Editors) review the sandbox site and provide feedback. This is an excellent time to provide training in using the new system if you plan to do so. If you discover that critical functionality is not available in the new version, consider postponing the upgrade or brainstorm ways to accommodate the differences in functionality.
This is an excellent time to review the journal’s workflow. The journal team may want to take advantage of new features or just improve the existing workflow while training the team on using the new system.
Make sure that the journal team understands that changes made to the sandbox site will not be incorporated into the production site upon upgrade. Keep a list of all changes to the content and structure requested during the review of the sandbox site so that these can be applied to the production site immediately after the upgrade.
OJS 3 handles theming for the website differently than earlier versions of the software, so the look and feel of your journal will change. You will have new options for customizing this aspect of your journal site through the current selection of themes.
If you have applied custom theming to your journal in OJS 2, that theme will not display properly in OJS 3. You may opt to use one of the available themes in OJS 3 or create a new custom theme that works with OJS 3. If you create a new custom theme, you should develop this prior to the upgrade so that you can put it in place on the production site immediately after the upgrade. Please refer to PKP’s Designing Your Journal guide for help in creating a custom look and feel for your journal. PKP’s Theming Guide can be used to develop a custom theme for your journal.
Though you have been communicating with the various team members throughout this process, it is important to check in with each individual team member to confirm they are ready to proceed with the upgrade. Upgrading from OJS 2 to OJS 3 is a major change that, depending on the journal, can involve many stakeholders with big or small roles in the upgrade. Check in with each team member to confirm they are ready for the upgrade.
Once you are ready to proceed with the upgrade, communicate to the journal team(s):
If the upgrade involves downtime or a freeze for new content, make sure to request email receipt confirmation once the dates are announced.