Joomla! Developer Blog

Migrating content to Joomla 1.5

May 19th, 2006 by davidgal

Joomla 1.5 does not provide an upgrade path from earlier versions. Converting an older site to a Joomla 1.5 site requires creation of a new empty site using Joomla 1.5 and then populating the new site with the content from the old site. This migration of content is not a one-to-one process and involves conversions and modifications to the content dump.

There are two ways to perform the migration:

  • An automated method of migration has been provided which uses a migrator component to create the migration dump out of the old site (Mambo 4.5.x up to Joomla 1.0.x) and a smart import facility in the Joomla 1.5 Installation that performs required conversions and modifications during the installation process.
  • Migration can be performed manually. This involves exporting the required tables, manually performing required conversions and modifications and then importing the content to the new site after it is installed.

    A detailed description of both methods follows.


    Automated migration

    This is a two phased process using two tools. The first tool is a migrator component named ‘com_migrator’. This component has been contributed by Harald Baer and is based on his ‘eBackup’ component. The migrator needs to be installed on the old site and when activated it prepares the required export dump. The second tool is used during the Joomla 1.5 installation process. The exported content dump is loaded to the new site and all conversions and modification are performed “on-the-fly”.

    Step 1 - Using com_migrator:

  • Install the component on the old site.
  • Select the component in the component menu of the administrator.
  • Click on the ‘Dump it’ icon. Three exported gzipped export scripts will be created. The first is a complete backup of the old site. The second is the migration content of all core elements which will be imported to the new site. The third is a backup of all 3PD component tables.
  • Click on the download icon of the particular exports files needed and store locally.
  • Multiple export sets can be created.
  • The exported data is not modified in anyway and the original encoding is preserved. This makes the com_migrator tool a recommended tool to use for manual migration as well.

    Step 2 - Using the migration facility during Joomla 1.5 installation:

  • In step 6 - Configuration select the ‘Load Migration Script’ option in the ‘Load Sample Data, Restore or Migrate Backed Up Content’ section of the page.
  • Enter the table prefix used in the content dump. For example: ‘mos’ or ‘mos_’ are acceptable values.
  • Select the encoding of the dumped content in the dropdown list. This should be the encoding used on the pages of the old site. (As defined in the _ISO variable in the language file or as seen in the browser page info/encoding/source)
  • Browse the local host and select the migration export and click on ‘Upload and Execute’
  • A success message should appear or alternately a listing of db errors
  • Complete the other required fields in the Configuration step such as Site Name and Admin details and advance to the final step of installation. (Admin details will be ignored as the imported data will take priority. Please remember admin name and password from the old site)

    What does the automated migration do?

  • It migrates all core content records in the database (i.e. content, weblinks, banners, contacts, newsfeeds, polls and users).
  • It reconstructs menus with menu items that link to core content (not 3PD components).
  • It appends all core module records from the old site to the module table of the new site. Original module records are set to ‘unpublished’. All parameter settings are preserved. The user will need to reset positions, order and publish settings.

    What doesn’t the automated migration do?

  • It does not migrate database records for 3PD extensions. If versions of these components are to be installed in the new site, it is recommended to perform a manual migration of the component data after the component is installed in the Joomla 1.5 site. (As mentioned the com_migrator prepares a dump of all 3PD tables).
  • It does not migrate non-db content such as banner images, files, photos etc.
  • It does not make coffee

    Manual Migration

    First a word of warning! The popular tool, ‘phpMyAdmin’ performs unrequested and usually incorrect encoding conversions during export of site data. There is currently no way to control this. For this reason it is NOT recommended to use phpMyAdmin for migration. The reason for this is unclear but the tool appears to assume the encoding of the database which in many cases is ‘latin1_swedish_ci’ (the default) and has no connection to the actual encoding that was used in the site. The result is usually corruption of all extended ascii characters.

    Preparing data for a manual migration includes encoding conversion to utf-8, accommodating for added fields in Joomla 1.5 database schema, renaming of two fields and possibly renaming the table prefix. Following are some guidelines for manual migration bearing in mind that there “is more than one way to skin a cat”.

    Encoding conversion:
    This can be done during export (if the export tools supports it), off-line on the sql script using an appropriate editor that can ’save as utf-8′ or during import (this works OK with phpMyAdmin).

    A good sanity check is to load the converted sql file in an editor. If the editor is in the utf-8 mode (usually seen in the status bar) and the content is readable - then you probably got it right. When doing an editor based conversion, the BOM (bit order marker) option should NOT be used as this adds several unwanted bytes at the top of the file and will cause a parsing error.

    Accommodating for new fields in Joomla 1.5 db schema:
    All that is needed is to ensure that:

  • Database table structure of the old site should NOT be included in the dump. The last thing we want to do is to bring the old db table structure into the new database.
  • INSERT statements should be ‘complete’, i.e. include field list and then value list. The shortcut INSERT statements with value list only should NOT be used as db errors will occur when the new fields are encountered.

    Renamed fields:
    There are only two field names that need to be renamed in appropriate INSERT statements:

  • In the ‘jos_core_acl_aro’ table the first field needs to be renamed from ‘aro_id’ to ‘id’.
  • In the ‘jos_core_acl_aro_groups’ table the first field needs to be renamed from ‘group_id’ to ‘id’.

    Which tables to import?
    The list below includes tables that relate to core content and they can be safely populated with the migrated data. Note that the ‘jos_usertypes’ table is no longer used in Joomla 1.5.

    Menu and module tables can be reconstructed with relevant records from the old site. You need to know what you are doing here. If in doubt it might be a better idea just to reconfigure module parameters and menu structure using the administrator interface. Menu records that relate to ‘content_typed’ are no longer valid as this type of content is no longer recognised.

    The tip of the day is “be prudent and keep a good backup”

    Core data tables:

    • jos_banner
    jos_bannerclient
    jos_bannerfinish
    jos_categories
    jos_contact_details
    jos_content
    jos_content_frontpage
    jos_content_rating
    jos_core_acl_aro
    jos_core_acl_groups_aro_map
    jos_core_log_items
    jos_core_log_searches
    jos_messages
    jos_messages_cfg
    jos_newsfeeds
    jos_poll_data
    jos_poll_date
    jos_poll_menu
    jos_polls
    jos_sections
    jos_users
    jos_weblinks

     

    Copyright © 2006