It is always recommended that you backup all data and code belonging to the version that you wish to upgrade. Ensure you have backups before proceeding.

Install the new version alongside the old version (use a new database schema so that they don't collide). Installation using the graphical wizards is recommended for one-off installations but the silent installation may be preferable in highly-automated environments where installations need to be repeated several times.

This new installation will include the default version of the new storefront client and any new directories, configuration files, documentation and jars provided in the new version.

This new installation will provide an extremely useful reference platform that you can use for a variety of purposes such as verifying the behaviour of new features.

All the updated source code provided with KonaKart will be included in this new installation so if any of these items have been customised these customisations may need to be merged with the new versions.

An upgrade SQL file (one for each database type) is provided that needs to be run to upgrade the database from one version to the next. If you are jumping a few versions you must run each upgrade SQL file in sequence in order to prepare the database for the new version. The database upgrade scripts will not destroy your data (customers, orders, products etc) but it is highly-recommended to run the upgrade process on a test environment before applying it to any production database.

On Windows, (assuming KonaKart was installed in the default location), the database upgrade scripts for MySQL can be found in the following directory:

C:/KonaKart/database/MySQL

Having upgraded the database from the previous version you can verify that the new version of KonaKart runs fine against the upgraded database by changing the database parameters in the konakart.properties and konakartadmin.properties files in the new installation's webapps (konakart and konakartadmin webapps).

If you have custom code (including your own order total, shipping and payment modules, one-page-checkout code etc) that uses the KonaKart libraries you will need to recompile it against the new jars.

Exactly how you go about this task will depend on various factors including how you have structured your development environment and build system.

If you use the supplied ANT build files to build your custom code you should copy your custom sources across to the new custom directory and build from there. This will pick up the new ANT build file and the new libraries that will be required. Depending on what you have done in your custom code it is possible that you may have compilation errors to fix at this stage.

If you have your own build system in place for your custom code you should copy the dependent jars from the new installation to your custom build system and rebuild. Again, depending on what you have done in your custom code, it is possible that you may have compilation errors to fix at this stage.

Of all the upgrade tasks this can be the most complex as it involves the careful comparison of your storefront code with the storefront code in the new version.

Because of the backwards compatibility of the APIs in theory you should not need to change your modified storefront at all and it will continue working as before.

You only need to change your storefront code if you want to upgrade your storefront to the new storefront code which will use the new features introduced in the new version of KonaKart.

If you wish to upgrade your storefront you will have to merge your own changes with the new code in the following areas:

The best way to execute the merges will depend on how many changes you've made. If you have made a very large number of changes in these areas it's likely that the easiest option is to merge the new storefront features into your current storefront code. If, on the other hand, you have made very few changes to the storefront code, the best option is probably to merge those few changes into a copy of the new storefront code.

Sometimes changes are made to the webapp configuration files. An example is when JSON was introduced a new section was introduced into the web.xml file for the konakart webapp to define the new servlet.

These key configuration files should be compared with your current versions to assess whether the changes are required. Files to pay particular attention to are:

Some releases include an upgrade of tomcat. If you use tomcat for KonaKart you will probably want to upgrade to the same version of tomcat and move your current system across to the new tomcat installation.

Some releases use the same version of tomcat (as the previous version) but have modified configuration files that should be compared with your current versions to assess whether the changes are required. Files to pay particular attention to are:

Sometimes new releases provide new functionality that requires a new directory structure. An example is when Solr was first introduced a new solr directory was added at the base of the KonaKart home directory. Check your reference installation for any new directories and consider introducing them into your existing structure (where you place them will depend a lot on which App Server you happen to be using).

Most new releases introduce new message strings that may need to be translated into the languages you need to support in your system. The message files to consider are:

To help identify the new messages introduced between particular versions of KonaKart you can refer to the files in the ${KONAKART_HOME}/utils/kkMessages/new-Messages , ${KONAKART_HOME}/utils/kkMessages/new-AdminMessages and ${KONAKART_HOME}/utils/kkMessages/new-AdminHelpMessages directories. When new messages are introduced between the specified versions in the above 3 Message properties file types a file is created that contains only the newly introduced messages.

If a particular *Message_X.X.X.X_to_Y.Y.Y.Y.properties properties file is missing from the ${KONAKART_HOME}/utils/kkMessages/new-* directory it means that no new messages of that type were introduced between the two versions.

It is highly-recommended that the "doc" directory of the new installation is checked for the latest documentation. The User Guide will be updated for every release and additional documentation may be added to this directory covering specific areas. Note also that the javadoc will change in each new release so if you refer to a local copy for the javadoc you should reference that in the new installation under webapps/javadoc/ .

New panels are often added to the Admin App in new versions of KonaKart. You need to check that the roles that you have defined for your Admin App users are appropriate for your needs. You may find that you need to allow access to some or all of the new panels otherwise they will not become visible to your Admin App users. It can be useful to install a fresh copy of KonaKart alongside your development system (use a new database schema) to allow you to refer to the default set-up for the Admin App. This default set up will show you all the roles that are assigned to the admin@konakart.com user with a standard default installation.