The migration process

The migration process

The migration steps in detail

a) Checking and cleaning...

JUpgrade Page 4 - Step 1 panel.jpg

This first step runs a verification check for all the necessary requirements that jUpgrade needs to start the process. This includes checking for the presence of the cURL PHP library, verifying the ability to write to the site's root and /tmp folders,

If "Delete previous migration" is set to "Yes" in the Parameters screen, this step will also run a clean-up script that will remove any database tables, files or folders which were created or inserted during a previous migration or failed attempt. This used to be a manual affair, with specific instructions for users to remove these assets from their installations before trying again, but the process has now been automated to make life easier for all. (The manual cleanup process is listed in the "Troubleshooting" section.)

If you are experiencing difficulties moving beyond this step and you have manually confirmed that all requirements have been met, you can set "Skip Checks" to "Yes" to instruct jUpgrade to ignore the verification step and move straight on to the next step.

(Please note: the above "delete previous migration" setting only applies to the database with the currently defined "Prefix for new database" and the folder currently defined as the "Target Directory".)

(Please note: this step will be displayed as part of the "sequence", even if "Skip Checks" has been enabled", so as long as it proceeds to the next step there is no need for concern.)

b) Downloading Joomla 2.5...

JUpgrade Page 4 - Step 2 panel.jpg

The next step in the migration process is to download a copy of the latest version of Joomla! that will be used to upgrade the current site.

The Joomla! distributions available to upgrade to include Joomla! 1.7 and Joomla! 2.5. You can select the distribution to upgrade to from the Parameters screen.

What this step essentially does is download the latest version of the Joomla! distro from the main repository, place it inside the /tmp folder of your Joomla 1.5 directory and rename it to either or, depending on the selected distro.

The progress of the download is indicated by the total size of the distro (in bytes) as well as how much of it has been downloaded so far.

This implies you will need an internet connection to make the download, and you will need to ensure the /tmp folder is writable and that the admin has permission to modify the contents of the folder.

If there is no internet connection available, or you are experiencing difficulties downloading Joomla! or proceeding past this step, you can assist this part of the process by downloading the latest version of the distro of your choice (let's say Joomla! 2.5), rename the package according to the label that jUpgrade expects to find for the file (in this case ""), and copy it into the /tmp folder manually.

Then make sure you have set "Skip Download" to "Yes" in the Parameters screen. Doing so will instruct jUpgrade to bypass the need for downloading and expect to find the file it needs to work with within the /tmp folder.

(Please note: this step will be displayed as part of the "sequence", even if "Skip Download" has been enabled", so as long as it proceeds to the next step there is no need for concern.)

c) Decompressing package...

JUpgrade Page 4 - Step 3 panel.jpg

The next step in the migration process is to extract the contents of the Joomla! distro package in the /tmp folder into the folder defined as the "Target Directory" in the Parameters screen.

By default, the label for this folder is "jupgrade", but you can easily modify it to be labelled something else. The folder will be created within the root folder of the Joomla! 1.5 site, and the contents of the distro package will be unpacked into it: this leave the original 1.5 site intact and unharmed, and in case of a failed migration will be easily to remove and cleanup.

For the folder to be created and the contents extracted to it, the root folder of the site must be writable and the administrator have permissions to write to it. Lack of appropriate permission levels will mean the folder cannot be created and the contents cannot be unpacked, resulting in an error.

To compensate for those servers that are not geared for handling extraction of .zip packages, jUpgrade comes with the "PCLZip" library to deal with decompression.

Any errors encountered at this stage will likely involve either

  1. lack of appropriate permissions, for either the root folder or the admin (or both), or
  2. issues extracting from the .zip package, such as with corrupted or incomplete downloads

If you are experiencing issues with the decompression stage, you can assist this part of the process by manually extracting the contents of the Joomla! distro into a newly created folder that has the same label as the one set for "Target directory". Then make sure you have set "Skip Decompress" to "Yes" in the Parameters screen. Doing so will instruct jUpgrade to bypass the decompression stage and work with the new Joomla! files it expects to find in the "Target directory".

(Please note: this step will be displayed as part of the "sequence", even if "Skip Decompress" has been enabled", so as long as it proceeds to the next step there is no need for concern.)

d) Installing Joomla 2.5...

JUpgrade Page 4 - Step 4 panel.jpg

The next step in the migration process is to create the database tables for the newly extracted copy of Joomla! and to update its configuration.php file to include the relevant settings needed to make it accessible.

The new install creates tables within the Joomla 1.5 database using the "Prefix for new database" stored in the Parameters screen. (An option to install to a different database will be available in the near future.) This implies that the administrator has the necessary permissions to edit the database and make new tables.

The configuration.php file includes all the essential settings required for Joomla! to interface with the database, set up the site according to the Global Configuration settings and more. In a fresh new install, this file comes with default values for all the necessary settings, and when jUpgrade reaches this step it updates the values of the following settings:

public $dbtype = 'mysqli'; - the mode in which the MySQL engine handles Joomla! queries (default is 'mysql')
public $host = 'localhost'; - the hostname, or location, of the server (can be 'localhost' or for remote installs ''
public $user = 'username'; - the username for the account connecting to the database
public $password = 'password'; - the password for the account
public $db = 'j1525a'; - the name of the database the tables for this Joomla! site are kept
public $dbprefix = 'j25_'; - the prefix for the tables containing this Joomla! site's content

Once the database tables have been prepared for the migrated content, and the configuration.php file updated to make the new Joomla! install accessible, jUpgrade can proceed to the next step.

e) Upgrading progress...

JUpgrade Page 4 - Step 5 panel.jpg

The next step in the migration process is to transfer the content from the Joomla! 1.5 database to the new 2.5 database. jUpgrade focuses primarily on content for the core components that come with Joomla, but has a step later in the process for transferring content of third party components.

The content for core components is transferred in a specific order, and jUpgrade will display updates to the sections being transfered with "Migrating ..." notices. The content is migrated as follows:

  1. User information - registered user accounts and their group access levels
  2. Modules - records for installed modules, any module parameters and menu associations
    (Please note: this only transfers database settings and references, it does NOT transfer module files or folders because the same module written for 1.5 will not work within 2.5 and might break the site. To resolve this, install a 2.5 version of the same module (in which case any stored parameters will be used) or, if it doesn't exist, seek an alternative 2.5-compatible module that will do the same job.)
  3. Categories - all sections and categories listed in the "Section Manager" and "Category Manager"
    (Please note: since Joomla 1.6, sections are no longer available; therefore to compensate for this during the migration process, all sections will be migrated as "main level categories" while all categories assigned to them will appear as "sub-categories". While category IDs can be maintained during the migration, categories that used to be sections will have different IDs and links referring to them must be refreshed and updated.)
  4. Content - all articles listed in the "Article Manager", including those marked as "Featured" ("Frontpage" in Joomla! 2.5)
  5. Menus - all menus listed in the "Menu Manager" (and all the menu items for each)
  6. Banners - any banners that have been created and the banner categories that they have been organized into
  7. Contacts - any contacts that have been stored and the contact categories that they have been organized into
  8. Newsfeeds - any newsfeeds that have been created and the newsfeed categories that they have been organized into
  9. Weblinks - any weblinks that have been stored and the weblink categories that they have been organized into

At the moment jUpgrade is designed to migrate all available data for the core components listed above sequentially, whether they have any information to migrate or not. (An option to select which components to migrate data for will be available in a future version.)

There may come an instance where the process will get stuck while migrating data for a specific component and (with "Debug mode" enabled) an error similar to "Migrating undefined" or "[undefined][undefined]" will be displayed. In general it is caused when

  • a migrate_xxx.php file that is being requested for by jUpgrade is not available or accessible
  • the database table from which content is being transferred is corrupt or has been modified (jUpgrade requires that no modifications have been made to any of the core tables themselves, otherwise the migration can run into problems when dealing with custom fields)
  • the migration runs into an issue attempting to copy content over to a database which already has content (from a previous migration, failed or not).

More information on resolving this error is available in the "Troubleshooting" section, however the quick solution is to remove all the tables created for the new Joomla! install during the migration and run jUpgrade again.

Once the content for all the above components has been successfully been copied over from the Joomla! 1.5 database to the new 2.5 one, jUpgrade is ready to move on to the next step of the process.

f) Copying templates

JUpgrade Page 4 - Step 6 panel.jpg

The next step in the migration process is to copy over any templates that have been installed in the Joomla! 1.5 site to the new Joomla! 2.5 site. There are some considerations to bear in mind when copying templates over however, as the changes in architecture between 1.5 and 2.5 have brought the need for some manual intervention on the administrator's part.

In general, templates designed for Joomla! 1.5 and 2.5 are almost identical in structure:

  • they are installed into the "{root}/templates" folder ("{root}/administrator/templates" folder for admin templates)
  • they share the same structure for CSS files, Javascript files and HTML overrides
  • they have the same module positions and work visually identically

They also each have a "template_details.xml" file which contains the information Joomla! needs to recognize it as a template and load it accordingly as well as any template parameters that are available. What differs is the tags used within their respective XML files to identify certain aspect of the template and its controls.

Because each version of Joomla! parses the "template_details.xml" file differently, the 1.5 version will need to be updated to the 2.5 style in order to work. Not doing this results in 2.5 being unable to read the template, therefore not load it, and with no idea where to load content and modules "breaks" the front-end of the site with a plain white screen.

jUpgrade can copy the 1.5 templates to the 2.5 site whole, making sure that all the files and folders necessary for the template to display and function are present and intact. And while it also copies over the "template_details.xml" file as part of the set, it copies it as is; jUpgrade does *not* do any conversion of the tags. (An option to convert the "template_details.xml" file during migration is being explored and may feature in a future version of jUpgrade.)

Therefore the administrator is required to update the file manually to the 2.5 style tags. Attempting to use this template within 2.5 prior to this update will result in the white screen mentioned above on the front end.

A note regarding template module assignments: in the Parameters screen there is an option to "Keep Original Positions". The reason for the inclusion of this setting is that with the default Joomla! templates, such as "JA Purity" and "Beez", have different names between 1.5 and 2.5 for module positions. With this set to "No", the template position names will be modified according to their 2.5 template equivalent. This option is only relevant to those administrators who use either of these default Joomla! templates for their site.

There is an option to "Skip Templates" in the Parameters screen, and skipping this step of the migration can be useful when:

  • you have no need to use the 1.5 template in the 2.5 site
  • a native 2.5 version of the template exists and will save the trouble
  • there is no one available to do the "template_details.xml" conversion

Once the template transfer step has been successfully completed, or skipped if so selected, jUpgrade can proceed to the next step.

g) Copying images/media files...

JUpgrade Page 4 - Step 7 panel.jpg

The next step in the migration process is copying over the images folder and all the media within from the 1.5 site to the 2.5 site. The way jUpgrade handles this is by renaming the original default 2.5 "images" folder to "images.old" and copies the 1.5 "images" folder in its entirety to stand in its place.

This ensures that any components which store their images and media within this folder will be able to display them on the front end without interruption to the site. Images used for Joomla articles, for example, would now be displayed.

This step implies the administrator's permissions to edit and create folders and copy files, so any issues at this point would most likely be due to permissions, however if the migration has reached this stage there should be no issues.

After the images folder has successfully been copied over, jUpgrade is ready to move on to the last step.

h) Upgrading 3rd party extensions...

JUpgrade Page 4 - Step 8 panel.jpg

The last step of the migration process is to migrate the content of any third party components that have been installed in the Joomla! 1.5 site.

jUpgrade comes with a framework built-in that developers can use to define the tables and fields relevant to their component which should be transferred during the migration. These details are stored in a pair of files which jUpgrade refers to when looking for specific component data to transfer.

There are currently 15 components which jUpgrade supports, and more information on how to create migration template files for a specific component is available in the "Third party extension support and development" page.

Many people get confused as to why the components that jUpgrade supports are not automatically made available in the 2.5 site, and even though are "migrated" are not present in the components menu. There is an expectation, for example, that when K2 is migrated from the 1.5 site to the 2.5 site, not only will the data have been transferred, but that K2 is also "pre-installed" and working perfectly in the new site.

The reality is that this is not possible, mainly due to the differences in the code syntax between the way components for 1.5 and 2.5 are written. Among the updates to 2.5 were changes in function names and syntax structure, meaning the author of the 1.5 component would have to update their code manually to support the new 2.5 style.

This is a similar case to 1.5 templates which need to have the tags updated within their "template_details.xml" files, and an option to automatically convert the tags during migration is possible. It is far more difficult to automate such a conversion for 1.5 component code, especially with so many different variables to take into account and the expectation for a "perfect result".

Therefore it is important to note here that for those supported components, jUpgrade only migrates the data stored for each one; it does *not* copy the files and folders of the component from the 1.5 site to the 2.5 site. Doing so would be pointless, as the 1.5 component code would not parse correctly in 2.5 and "break".

This is why the native 2.5 versions of each "migrated component" need to be installed after the migration is complete. jUpgrade transfers the content for the component and prepares it for use, the administrator must install the component that will now make use of it in the proper 2.5 context.

After the third party component data is successfully transferred, the migration is complete.

i) Upgrade finished!

JUpgrade Page 4 - Step 9 panel.jpg

The final step of the migration process confirms when the upgrade has been successfully completed, and displays shortcut links for the administrator to access the new Joomla! 2.5 installation. You can visit the front-end of the new install using the "Site" link, while the "Administrator" link will direct you to the back-end. With a successful migration, you should be able to log into the new site using the same username and password as the old one.


Quick contact

If you need to contact us below the tracks offer direct contact: