SP Upgrade - User Guide

The whole process step-by-step

Scenario Definitions

You can do the whole process on the same host where the 1.5 site lies, or on a different development host, or even on your PC using tools like XAMPP. You can also use the same database as the source site, or different, or even have the Joomla! files on different host, and the database to another. There are almost unlimited scenarios, so we had to just pick one and describe it. We chose the scenario to work on the same host where the 1.5 site lies, and use different database.

So for the purpose of this guide let's assume the imaginary Joomla! 1.5 source site elements.

In our scenario we will do the whole process on the same host, using a different database. The steps of the process in summary would be the follow:

1. Install a new Joomla! site, that from now on we will call the destination site.
2. Install SP Upgrade on the new site.
3. Connect to the source 1.5 database.
4. Transfer core Joomla! data.
5. Copy images.
6. Install new template.
7. Transfer extensions.
8. Move the new site live.

Install new site

Backup

The first thing to do before anything, is to backup the source 1.5 site, and that should include folder public_html, and the database. SP Upgrade does not any how affect the source site, but you might do any mistake that is not related with the component itself.

WARNING: Do not proceed with the next steps, unless you are sure that you have a valid backup and ability to restore.

It is recommended when you start the migration process, to keep a freeze period for the menus, modules, and article categories. You can continue adding new users, and articles.

New Database

From the control panel you must create a new database and database user, that will be used from the new site. Let's assume that the name of the new database is db_destination. Even though you might use only English language, it is recommended to have the database language encoding to UTF-8.

New Folder

Create a new folder under directory /home/public_html/ where the site's files will be kept. Let's assume that new folder name is new. 

That means the path to the new site will be /home/public_html/new/ and the url of the new site will be http://www.kainotomo.com/new

Install

Download the original English Joomla! installation file from http://www.joomla.org. If you use a different language from English, we still recommend to download the original English version, since in rare occasions the translation packages might introduce problems. You can install any language you wish after you are done. The same goes for any ready template installation file you might have. It would be for the best to install the template, later.

Note that above is just recommendation, and you could use any Joomla! file you wish. We just tested with the English version.

Next upload and uncompressed the installation Joomla! zip file in the new folder. Open a browser and visit URL http://www.kainotomo.com/new to continue with installation process. You should choose the newly created database and the database user.

It would be for the best, when you are asked, not to install any sample data. If you decide to install any sample data, there should be no problem, but the margin that there might be a mixed up of your categories and articles.

For more information of how to install Joomla! read this: http://docs.joomla.org/Installing_Joomla! 

Install/Configure SP Upgrade

When you are done installing the new Joomla! site, the next step is to install SP Upgrade on the new site, and connected to the source 1.5 source database.

Installing SP Upgrade is just like stalling any other extension in Joomla!. Just go to the extensions manager in backend, and upload the package zip file that you downloaded from our site.

After the successful installation of the component, a new menu will be created in the backend, where you can visit it. When you visit for the first time the component, you will see a red message, that you are not connected to the source database and FTP.

Before you try to connect, you have to first know the source database name and user credentials.

Those details are stored in the source site file configuration.php. The full path of the file should be: /home/public_html/configuration.php

Just open the file from your control panel, file manager, and copy/paste in SP Upgrade options the follow:

1. public host - usually that should be localhost
2. public $user = 'username';
3. public $password = 'xxxxx';
4. public $db = 'dbname';
5. var $dbprefix = 'xxx_'; 

when you save the component options, normally the connection with the source database should be established, and a green message will appear that the connection is successful.

You can also try to connect with the FTP, even though is not that necessary. The FTP connection is only used to copy the images folder, from the source site to replace the one in the destination site. That is something that you can easily do from the file manager.

Transfer data

SP Upgrade is having three different transfer views. The first is to copy the core Joomla! data (categories, articles, users, etc.), The second is for the extensions that are natively supported, and the third is for the extensions that are not supported.

Transfer core Joomla! data

to transfer the core Joomla! data, all you have to do is to go to the corresponding view, and click the button Transfer All. Normally, after some time all the core Joomla! data will be transferred automatically. If for any reason the process stops, that might be for any reason, timeout, full memory, etc., all you have to do is to press again the button transfer all, and normally the process would continue from where it stopped.

Transfer images

If you managed to connect the FTP, and just select the images and click the button transfer. If you did not manage to connect with FTP, then all you have to do is from your file manager, copy the images folder from the source site to replace the one in the destination.

Template

You can try to convert the template SP Upgrade, but it is recommended to use a new bootstrap compatible template. The reason for that is to take advantage the responsiveness so your site will be mobile friendly.

If you want to try convert the template, first you have to connect the FTP. Then you are in the corresponding field the name of the template folder that is located in the source site, and press the button transfer. When complete, the convert the template will be located under the TMP folder, so you can install it from the extensions manager from there.

If you decide to use a new template, then make sure that the modules are having the possible new positions based on the new template. That you can do from the backend, modules.

Extensions

The general process for the extensions is the follow:

1. in options make sure to choose option replace id
2. from database view, select all the extension's tables, and transfer
3. install the extension

Take the new site live

After you finish with testing the new site, and you wish to go live, the first thing you should do, is again to backup everything.

If you did not keep a freeze period for everything, then you should try transferring the items again. SP Upgrade keeps history log, therefore any new item that is update in the old 1.5 site, will be copied to the new site.

Take the new site live do the follow from the control panel file manager:

1. make sure that files configuration.php both in folders /home/public_html and /home/public_html/new having access 644, and not 444
2. select all files and folders of the old 1.5 site from folder /home/public_html and move them to a backup directory. The reason that you should move, and not copy, it's because unlike copy, the move is just the process of some milliseconds. If you choose to copy, and then delete, then the process might take a long time, depended on your sites size.
3. Choose everything from /home/public_html/new and move them in /home/public_html
4. That's It!!!

And do not forget, that if you need any assistance, you may search our site's documentation, or contact with us.

Installation

 Uninstallation

You can uninstall the component just like any other Joomla! component. In your site's back-end, just go to Extensions Manager, click on Uninstall. In the Filter area type SP and click on Search. Several entries appear. Select the entry where the Type is Package. Do not select the other entries; they are removed automatically. Now click on Uninstall. This will completely remove extension including all

Introduction

 In no case an item will overwrite an existing item with the same id during transfer if you choose it. There is also a restriction in Joomla! where you cannot have the same alias of an item under the same parent. Taking these facts into consideration there are two important options you have to decide before the transfer.

If there is duplicate id, whether:

1. to transfer the item with new id, (recommended for already existing destination site with extensions, or other data installed)
2. replace existing items (recommended for new empty destination sites)
3. or not transfer at all.

The component keep history of what is already transferred. This is necessary to keep track in case you have a disruption of the process for any reason (timeout, memory, network)

It is strongly recommended to backup your database before proceed with the transfer, just to be on the safe side.

Another very good and more detailed guide you can find here: http://www.ostraining.com/blog/joomla/sp-upgrade/

History Log

There are two ways to filter the data. By the component type, and the result. Remember that an item is considered transferred when it's status is 'Transferred and finalized'

To delete history log based on the filters just filter what you wish and press button 'Delete History'

Configuration

General Options

Same IDs Handling: Choose how to treat items with ids that already exist in the destination database.

1. Transfer items and save with new IDs, or
2. Do not transfer item, or
3. Replace existing items.

Note: The option fore replace existing items is not valid for users.

Batch: The number of items to transfer in each cycle.

Database Connection

Those are the database credentials of the source database. Those credentials can be found in your source site configuration.php file.

Host: In case both your databases are on the same host then write localhost. In case of remote transfer here you have to write the remote source host name, or IP. In case you have trouble identify what is this, you should contact your host provider.

Database Name: The source database name.

User Name: The user name of the source database. This is not the Joomla admin user.

Password: Password of the user to the source database.

Database Tables Prefix: The source database tables prefix name. Something like xxxxx_

FTP Connection

Those are the FTP credentials of the source site. They are necessary to enable ability to transfer files, like images, templates and other extensions media files.

FTP Host: In case both your sites are on the same host then write localhost. In case of remote transfer here you have to write the remote source host name, or IP. In case you have trouble identify what is this, you should contact your host provider.

FTP Port: Usually this is 21. 

FTP User Name: The FTP user name of the source host.

Password: Password of the FTP user to the source site.

FTP Root: That could be / or any other sub-directory that is present on the source site.

Core Joomla! Data Transfer View

Go back to options and correct the database credentials.

Just choose what you want to transfer and press button transfer. If the connection is healthy then the 'Transfer' button will become enabled and below screen we appear:

You have the option to transfer all items of what you choose, or selected items based on their ids. You may choose individual ids, or range, or a combination of both. For example:

3,10-56,68,100-145

Will transfer items with ids: 3 and 68, and range of id's between 10 to 56, and range 100 to 145. If you leave empty the ids field then all items will be transferred.

Also you may press button Clear to clean corresponding field, or Choose to visually choose individual items. The choose button will open a well known window depended on the type of items to choose with search and filtering capabilities. See below of example of choosing articles. Similar dialogues exist for all items.

Choosing ids could be helpful if you do not wish to bring all the data from the source site.

After the transfer of items you just choose all and leave the ids fields empty and press button finalize. This step will fix the links in case you chose to bring items with new ids.