Detailed Upgrade Instructions for AbleCommerce 5.5 CFMX

Latest Version: Service Release 2, Build 1389

Release Date: January 25th, 2007

Applies To: Existing installations of AbleCommerce 5.5 CFMX (build 1357 - 1379)

Downloads:

IMPORTANT: If you have previously upgraded to SR1 (build 1382), you should follow the SR2 upgrade instructions instead.

UPGRADE INFORMATION:

The SR1 release corrects a number of issues between builds 1357 and 1382.  It is highly recommended that you upgrade if you are still running a build earlier than 1382.  The SR2 release corrects a few issues between builds 1382 and 1389.  If you are experiencing any of the issues listed, you should upgrade to SR2.  Before upgrading, make sure you review the upgrade options below.

If you do not know which version or build you are running, then please see this  FAQ on our website.

 

Instructions for Upgrading a Customized or Live Store

(Use the alternate Simplified Instructions for a development store upgrade)

 

Before beginning, let us have a brief look at what has changed since build 1357, so the upgrade process will be better understood.

Password Management

User passwords are stored using 128 bit AES encryption. This change has affected various sections of AbleCommerce.  

Account, Password and Audit Log Policies

These new features allow you to enforce User Account policies, Password Policies and Audit Log policies. These are installation wide policies which will be effective for all stores in the installation. This change has affected some sections of AbleCommerce.

Updates to Product Batching

Significant Backend Changes

 

Potential Upgrade Issues:

As we can see from the summary of changes above, the session management has significantly changed. This change alone has a potential to significantly complicate the upgrade process. The good news is that the changes have been made in a way such that AbleCommerce falls back to legacy password/session mechanism in case of an error due to a missing database table or missing functionality. Moreover, the old methods and code still remain intact so that the old templates are mostly operational with new jar files. There may, however, be some issues that we will try to document as much as possible.

In defining the upgrade process, the main goal is to achieve it in a step-by-step manner, while keeping the existing functionality intact at each step and minimizing the down time.  Please read through the entire upgrade process before beginning.

 

DEFINITIONS

[INSTALL_DIR] - This is where you installed AbleCommerce.  This directory contains the AbleCommerce program files.  The default location is C:\Program Files\Able Solutions\acb\...

[CFMX_DIR] - This is the webroot (wwwroot folder) where your ColdFusion program is installed.  The default location may be similar to  C:\CFusionMX7\wwwroot\

[ACTEMP] - This is a temporary location of your choosing, where the new AbleCommerce program has been extracted to for the purpose of the upgrade.
 

 

Step 1) - Backup the Existing Installation

Before upgrading, the following items must be backed up:

 

Important: A complete backup is critical in case anything goes wrong during the upgrade, you can always return to the original state.

Step 2) - Download latest build

  1. Download the applicable file to the server. (see top of page)

  2. Extract the contents of the archive into a temporary folder which will be used to copy new files from.  For the purpose of this document, these files are referred to as the Service Release 1 files in the [ACTEMP] location.
     

Step 3) - Simple Non-Intrusive Steps

The first thing in the upgrade process is to complete any steps that have no, or minimal, effect on your existing installation. These steps are listed below:

  1. (OPTIONAL) Copy all new files that are added in Service Release 1 which were not present in build 1357. The files you can safely copy to your existing installation are listed below, in Appendix A. It is not necessary to stop or restart CFMX server for this copy operation.

  2. DO NOT ADD any JAR files to WEB-INF/lib yet. This will be done later.

  3. Whether you copy all new files at this stage, or not, you MUST however, copy the following 3 files from [ACTEMP] to [INSTALL_DIR]:

WARNING: DO NOT REPLACE the following (3) files at any time during the upgrade process.  

[INSTALL_DIR]\acb.cfm

[INSTALL_DIR]\WEB-INF\ablecommerce.key

[CFMX_DIR]\WEB-INF\web.xml

 

Step 4) - Synchronization of Files (Optional)

In Service Release 1, some JAR files in WEB-INF/lib have been renamed. You do not need to add the renamed files to your existing WEB-INF/lib.

These files are:

This step requires no action, except if you feel it necessary to keep file names synchronized with Service Release 1.

 

Step 5) - Add new JAR files

The following new JAR files have been added to WEB-INF/lib in Service Release 1.

You can simply copy them from [ACTEMP]/WEB-INF/lib to [CFMX_DIR]/WEB-INF/lib folder and [INSTALL_DIR]/WEB-INF/lib. You do not have to stop or restart your CFMX server for this operation.

 

Step 6) - Update existing JAR files

The following JAR files have been updated in Service Release 1. Although the JAR files are updated to newer versions, the previous versions of JAR files should also work. However, it is advised to remove the old JAR files and replace with these updated JAR files.

To Perform the JAR file upgrade -

  1. Copy the new JAR files from [ACTEMP]/WEB-INF/lib to [CFMX_DIR]/WEB-INF/lib. The files already have different names so you won't be overwriting any existing files.

  2. To synchronize the new JAR files with your existing installation, you should copy the new JAR files from [ACTEMP]/WEB-INF/lib to  [INSTALL_DIR]/WEB-INF/lib as well.

  3. Stop the CFMX server

  4. Remove the old files from [CFMX_DIR]/WEB-INF/lib, including crimson.jar

  5. Restart CFMX server

  6. Verify that your installation and store(s) are still working fine. If there are any problems, clear your ColdFusion cache (see FAQ) and retest.  If the issue persists, then you may want to roll this step back and post it to Ablecommerce Forums for discussion. If you think it’s a bug, post it to Bugs.ablecommerce.com .

 

Step 7) - Perform a safe file upgrade

Update the files which do not interfere with the normal operation of AbleCommerce. Copy them from [ACTEMP] to [INSTALL_DIR] making sure to place them in the applicable folder.

The files you can safely update without any issue are listed below:

 

Step 8) - Update the database upgrade scripts

Update the following two files in your existing AbleCommerce installation:

Copy them from [ACTEMP]\master\storegroup\ to [INSTALL_DIR]\master\storegroup\

 

Step 9) - Update the AbleCommerce JAR files

Up to this stage, you have already upgraded the JAR files except for the new Ablecommerce_xxx JARs. Your installation should be working fine without any problems. Now, we will proceed to the most important upgrade step. It involves two operations -

  1. Replacing the old ablecommerce_xxx.jar files with the new ones.

  2. Running the database upgrade scripts.

NOTE: Every effort has been made to keep the new JAR files in Service Release 1 backward compatible.  However, because of a large number of changes, there might be unknown regression issues which we may not have detected yet. Therefore, once you upgrade the JAR file, immediately verify that all your deployed stores are functioning properly. If something in your Master or Merchant Administration section is not working, it is not a big concern, it can be fixed with patience. If anything goes wrong on the retail side it can be problematic, so you may have to rollback in this case.

 

  1. Stop ColdFusionMX services.  

  2. Remove all .jar files whose name start with "ablecommerce5" from -

    [CFMX_DIR]/WEB-INF/lib/

  3. Copy the two .jar files whose name start with "ablecommerce5" -

    from [ACTEMP]/WEB-INF/lib/

    to [CFMX_DIR]/WEB-INF/lib/

    and also to [INSTALL_DIR]/WEB-INF/lib (to maintain synchronization)

  4. Restart ColdFusionMX services to register the new library files. Be sure to give CFMX time to start completely before going to the next step.

  5. Verify that your installation and store(s) are still working fine. If there are any problems, clear your ColdFusion cache (see FAQ) and retest.  If the issue persists, then you may want to roll this step back and post it to Ablecommerce Forums for discussion. If you think it’s a bug, post it to Bugs.ablecommerce.com .

 
Step 10) - Add/Update the ColdFusion Class files
 
  1. From the AbleCommerce install directory, copy the contents of 'classes' folder -

    from [INSTALL_DIR]/WEB-INF/classes/*.*

    to [CFMX_DIR]/WEB-INF/classes/
 

NOTE: When using CFMX in the 'multi-server' JRun configuration, you will need to add the WEB-INF/classes to the classpath in JRun by using the JMC or editing {Jrun4_home}/bin/jvm.config

 

Step 11) - Upgrade Database

After updating the AbleCommerce JAR files in the prior step, login to the Master Administration Menu and click on the Manage Store Groups menu item.

NOTE: The Service Release 1 upgrade may force you to change your password when logging in.  If this occurs, update your password following the new password rules.

Find and click either the “Upgrade All” link, or the "Upgrade" link under Actions to upgrade one database at a time. You will be presented with a page like the one shown below.

Read the information on this page, check the box if you have made your backups, and click the Next button.

The selected AbleCommerce database(s) will be upgraded as necessary. You will be able to watch the upgrade progress as it is reported on the screen during this process.

You should save a copy of the database upgrade report when it is completed. This can be used by AbleCommerce technicians to troubleshoot any potential issues after upgrading.

Check all your deployed stores on the upgraded AbleCommerce installation. Hopefully, nothing is broken. If anything is broken in your stores, you may have to rollback and restore your backups. Report any issues to Ablecommerce Forums for discussion. If you think it’s a bug, post it to Bugs.ablecommerce.com .

 

Congratulations!  If you have reached this point, you have already done the most important part of the upgrade. The rest of the upgrade process can be carried out slowly and steadily over a longer period of time.

 
 

Step 12) - Upgrading the remaining program files

Most likely you haven’t done any customizations in the master or admin sections of your current installation. If this is the case, simply copy the remaining files from Service Release 1.

  1. Copy all files from [ACTEMP]\master\ to [INSTALL_DIR]\master\

  2. Copy all files from [ACTEMP]\admin\ to [INSTALL_DIR]\admin\

  3. Copy all files from [ACTEMP]\templates\ to [INSTALL_DIR]\templates\

If you have done any customization in your master or admin section, follow the same upgrade procedure as described below for upgrading your store templates.

 

Step 13) - Upgrading the AbleCommerce store templates

The store templates have been updated to correct bugs and include necessary updates.  We strongly suggest upgrading the store templates as backwards compatibility cannot be guaranteed.

If you have been using the built-in Themes and Wizards, and have not customized your .cfm files directly, the store upgrade should be relatively easy. The following step will over-write all your store templates, includes, css files, etc.  

Warning: MAKE A BACKUP BEFORE PROCEEDING.  
You need to backup all files in the store folder (*.cfm, *.wzc, *.wzct) and all sub-folders (/includes, /css, /images, etc.)

DO NOT REPLACE the following (2) files at any time during the upgrade process.

[INSTALL_DIR]\stores\1\acb.cfm

[INSTALL_DIR]\stores\1\includes\storeid.cfm

(Actual location of store templates may vary)

By default, the templates for the first store are located here -

[INSTALL_DIR]/stores/1/*all files and sub-folders*

If you are not sure where your store files are located, click on the STORES icon from the Master Admin menu.  Then, click on the linked store name and you will view the Edit Store configuration page.  The physical path setting indicates the location of the store files.  Each store of the installation must be upgraded individually.  Repeat as needed.

  1. Login to the Merchant Admin Menu.
  2. Click on "Store Settings" from the left-column menu.
  3. From the menu, check the box next to "Update Template" and click Finish.
  4. From the server, find your store backup set.
  5. Sort the files by Type, then highlight and Copy all the files with the extension *.wzc and *.wzct (e.g. index.wzc and/or index.wzct)
  6. Paste these into the current store folder, overwriting any existing wzc and wzct files.
  7. Copy the "storeheader.cfm" and "storefooter.cfm" from the store backup set.
  8. Paste these into the current store \includes\ folder, overwriting the existing files.
  9. Copy the entire contents from the store \images\ backup set.
  10. Paste these into the current store \images folder.  If asked, choose to NOT overwrite the newer images.
  11. Reload the store home page. You should now see the new version of the templates with your themes, headers, footers, and wizard options from the original store.

Suggestions for upgrading a store with customized templates -

Most of the store template customizations can be done via wizards and style sheets.  So, if you haven’t done any customization other than using wizards and css files, you can simply replace all your existing .cfm files (except acb.cfm and includes/storeid.cfm) with the new files from Service Release 1. However, you must take the following things into account when replacing files.

If you have done major customizations that you do not want to lose, then follow this procedure:

  1. Identify the original build you started working with. We assume it is build 1357, but it could be a later build.

  2. Compare the un-modified template files of build 1357 to the template files of Service Release 1 using a file comparison utility. A good discussion on file comparison utilities can be found at http://forums.ablecommerce.com/viewtopic.php?p=5936

  3. Incorporate the new changes, identified by the comparison utility, into your current store files. Most of the time, if the change is related to some display issue, you may not even want to make that change. In that case you can just ignore the change.

     

Appendix A

The files you can safely copy from Service Release 1 to your existing AbleCommerce installation are: