Migrating + Going Live

How to Migrate

The difference in code between Joomla 3 (J3) and Joomla 4 (J4) is significant. The Joomla Project has taken care that Joomla core components can be migrated from J3 to J4 via a "one click update". It's the third-party extensions that create the potential issues. Each third-party extension needs to be assessed as to its compatibility with J4. For more information on migration, see https://docs.joomla.org/Why_Migrate and follow the funnel/buttons at the bottom of each page that take you through self-assessment, planning, and step by step instructions.

The docs do not take into account every single third party extension, nor the strategy to migrate your specific instance(s). You may need to contact the third-party developers of your extensions. You may need to seek expert assistance for your migration.

If you currently have third-party extensions that haven't been made compatible with J4, start seeking alternatives to those extensions. Chances are slim that they will be made J4 compatible if they aren't by now.

Ways to Migrate

There are at least two ways to migrate from J3 to J4.

1. Using the "one-click update" from com_joomlaupdate (Extensions > Joomla Update > Options > Joomla Next)
2. Do a fresh build in J4 and transfer all the data over using a third-party extension like SP Transfer (https://www.kainotomo.com/products/sp-transfer/). There are other migration extensions which can be seen at https://extensions.joomla.org/category/migration-a-conversion/.

How you decide to do your migration will depend on the third-party extensions in use, how many migrations the site has been through (which often leaves leftovers), and any redesign you have in mind. The Joomla sites using Wise in the US will use option 2 above. They need a fresh start.

Changing from the J4 default Home Dashboard/Menu to the same structure it was in J3

The Joomla 4 dashboard is quite different from Joomla 3. If you'd like to have the sidebar menu structure be the same in J4 as it was in J3, you can do that. Here's how:

1. From the Home Dashboard, click 'Modules'.
   
2. Click on the drop-down next to the word 'Site' and select 'Administrator' from the list.
   
3. Type the word "menu" in the search box and select 'Admin Menu'.
   
4. Click on the Choose Preset drop-down and select 'Preset - Alternative Main Menu'.
   
5. Click 'Save & Close' from the Top Toolbar.
6. Now your Administrator Menu will be the same as it was before. For the purposes of this documentation, we'll use the Alternative Main Menu.

Wise Specific Considerations in Migration

1. Never, ever do a life cycle migration on a production site. Ever. Create a dev site of your J3 site to do the migration on. Take lots of backups throughout the process. LOTS of backups!
2. You may need to do a few test runs of your migration. It's ok. Better to do test runs and plan for third-party extension issues than think it will go perfectly the first time. If it does go perfectly the first time, you'll be so pleased!
3. With your copy/dev site in J3 established, you'll need to uninstall the J3 Wise extension in order to do the "one click update" to J4. It's ok, all your settings and modules and everything are still in your PROD/live site to refer to.
4. When your site is running J4, install the J4 Wise extension.
5. Enable the Wise Authentication Plugin.
6. Your current J3 template may or may not be compatible with J4. Many off the shelf templates like YooTheme Pro or Gantry 5 templates are compatible with J4. If you are using a custom built template, chances are that it is not compatible with J4. You will need to select a different, J4 compatible template in order to migrate to J4.
7. If you do the "one click update" to J4 with a compatible template, you will need to check the Template Overrides. If you follow the guidelines we've given, you won't need any of the overrides you've needed in the past. This will prevent many problems that have happened in the past.
8. If you do the "one click update" to J4, you will need to delete the iframe wrapper for /catalogus. There is a new menu item for the Wise Wrapper in J4.

Contact Information

If you have any questions, please contact Zoccolo if they are doing your migration or you can open a ticket with OCLC.

This documentation was written by Jenn Gress, OCLC Joomla Administrator for Wise.