Upgrading from Gold to AbleCommerce 9

What you need before upgrading -

1. A license key for the new version will be required. Please request a version 9 license key using your most recent order.

2. A backup of your AbleCommerce encryption key from the existing installation.
   
   Note: If you are upgrading from AbleCommerce 7 to an older version of 9.0.1, 9.0.2, 9.0.3, or 9.0.4, then be aware that restoring your encryption keys will require an additional step. This is due to the fact that AbleCommerce 7 has two key parts and the newer versions have just one.
   
   Expand this link to view special instructions for AbleCommerce 7 encryption keys.There is a small PowerShell script to combine key parts of the AC7 encryption key into one file.
   
   Please download the combine.ps1 file (MD5:  50a6ac3cc6cb1dd6ef8deec49832a491) and extract the contents. Obtain the two key parts from your encryption backup.
   
   There are detailed comments about how to use this script below:
   
   a) Place the combine.ps1, keypart1.bin, and keypart2.bin into a directory on your computer.
   b) Right-Click combine.ps1 script and choose to Run With PowerShell
   c) Once the script finishes, it will generate a key.bin file in the same directory.
   d) Use this newly generated key.bin file to restore the encryption key in AbleCommerce9. << This step is only necessary for an upgrade to version 9.0.1 - 9.0.4

3. A backup of your AbleCommerce database restored as a new database. You will need to know the database name, user credentials, and location by server name or IP address.
   
   Supported versions: AbleCommerce Gold R10, R11, and R12 may upgrade to any version of AbleCommerce 9
   AbleCommerce 7.0.3 through Gold R12 may upgrade directly to AbleCommerce 9.0.6 or latest version.

4. Review the Pre-Upgrade steps below and complete anything that is applicable.

Notable Changes:

• Image sizes have significantly increased in size. Your existing images can still be used

• A new feature called Ship Groups allows merchants to create unique shipping locations without having to create duplicate warehouses.

• Each user will need to reset their password. Password formats will be upgraded to SHA256. This happens automatically on first login. Merchants should notify their customers prior to, or upon upgrading.

• The catalog URL structure changed to improve SEO.

• The store setting to disable postal codes for small countries has the opposite behavior.

• TaxCloud's instant tax exemption certificate feature will no longer be available.  

• Some of the older payment gateways have not been fully converted. This is a work in progress, and will likely occur once we know which gateways are still in use.

• Authorize.net gateway settings need to be transferred to Authorize.net CIM gateway.

• If you had previously applied the unsupported FedEx connector, then you will need to contact us by requesting the FedEx integration from your order.

1) Download AbleCommerce application

To install the AbleCommerce application, you will need to have an active software subscription for your license. To check your existing license, you can submit a request through your order and we'll do it for you, or you can view the License details from the Security menu within AbleCommerce.

To obtain the download, login to your Customer Account area.  From there, click on the Downloads tab to see the available software downloads.  Always select the latest build available to you, unless you have a reason not to do so.

e.g. AbleCommerce9-{buildnumber}-WAP.zip

2) Request a License Key for version 9.0.x

AbleCommerce v9 has a new license model which limits the number of Admin users. As an existing Gold customer with a current subscription, you will be entitled to the UNLIMITED admin user license. To request your keys, find the latest order and submit a request with the name or IP address of the development site you will be using for the upgrade.

At the same time, we will issue a new production license key for your future upgrade to AC9.

NOTE:  An installation running in DEMO/DEVELOPER MODE is not valid for the upgrade.  Make sure you have a license key before continuing.  The key type can be issued with Development or Live. For more information, please License Keys.

3) Install AbleCommerce

1. Extract the contents of the download.

2. Follow the instructions for a new installation.

   1. Open the Installation Guide in a new window. Make sure to review the new system requirements as they are different from older versions.

   2. Begin completing the steps in the guide, except you will pause at Step 2. Configure and Connect to the Database.

   3. At the secondary Step C) Select the Install Type, choose the option to Upgrade Database

   4. You will be asked to confirm the backup procedure.
      PLEASE NOTE: It is very important that you do NOT upgrade an existing database without first restoring it to a new database.

3. Once the upgrade process completes, a confirmation page will be displayed with a link to the Merchant Administration. Login with your existing username and password.
   
   Remember, due to the encryption upgrade, you will be required to reset your password on the first login.
   
   If you receive errors during the database upgrade, please post a message to the AbleCommerce Forums.
   

4) Copy existing images and assets

All of your images and digital files should be located in the following folders of your <installpath>.

1. • \App_Data\DigitalGoods\

   • \Assets\

   • \Assets\ProductImages\

Copy all files to the new installation location. The paths will remain the same.

5)  Email Templates

The email templates have been updated in the new version, but you may still use your email templates from Gold if you have customized them. Otherwise, we recommend that you use the new email templates.

To use your customized email templates, copy them from -

• \App_Data\EmailTemplates\1\

To the same location of the new installation location. The names will remain the same.

• \App_Data\EmailTemplates\1\

NOTE: The URLs in the new version no longer end in .aspx, so any links in the old email templates will need to be updated to the new format and tested.

Tech Note: A new email template is included for multifactor (2-factor) authentication services (MFA). The "Google 2FA QR Code.html" file is required if you enable Google's MFA feature.

Pre-Upgrade Steps

Before upgrading, keep in mind that some payment gateways and shipping gateways are no longer supported in the new version. You will need to check and see if you are using one of the gateways that has been deprecated and decide how to proceed.

• FedEx (supported only through a separate plug-in that needs to be installed post-upgrade)

• DHL is no longer supported

• Check here for current list of payment gateways.

Another possible issue can arise if you are upgrading from an older version of SQL 2000 database. There are field type changes that must be made before upgrading.

Please open a support ticket if you need assistance with any of these issues.

Post-Upgrade Steps

Your new Merchant Dashboard will have a section showing any warnings or alerts that need to be taken care of.

1) CHECK FOR A MACHINE KEY

Open the web.config for your AbleCommerce Gold installation and see if a machine key exists.

If it does, then you will need to  specify a machine key in the web.config for the new version.

If you do not need a machine key, then continue to the next step.

2) ENABLE SSL

Make sure to re-enable SSL. The setting is in a new location.

Within the menu, go to the Configure > Security > SSL Settings page.

You have the option to secure all pages, use the default SSL configuration, or use your own settings.

3) RESTORE ENCRYPTION KEY

Restore a backup of your encryption key (.bin) from AbleCommerce Gold.

Find the Configure > Security > Encryption Key page from the menu.

In the Backup or Restore Encryption Key section, choose the key backup file and press the Restore Key button.

4) CHOOSE CAPTCHA METHOD

There are two CAPTCHA options available from the Configure > Security > Passwords page. The "CAPTCHA services section" has the configuration settings for Google's reCAPTCHA service. A test account is in use for demonstration purposes only. You'll need to obtain your own credentials and update them within the CAPTCHA services section. If you do not want to use Google's free service, then simply change the option to "Use standard image CAPTCHA" instead.

5) REPLACE DUPLICATE WAREHOUSES WITH SHIP GROUPS

This is a new feature which will eliminate the need to have multiple warehouses to create unique shipping scenarios.

If you have multiple warehouses with the same address, then you should review the changes you'll need to make to use the new feature.

1) Open two browser windows, (side-by-side) and go to the Configure > Shipping > Warehouses page in one, and the Configure > Shipping > Ship Groups page in the other.

2) For each warehouse that has the same address, create a new Ship Group using the same name as the warehouse.
Do not remove the extra warehouses at this time.

3) Once all the Ship Groups are created, click on the (0) indicator in the Products column for the first Ship Group.

a) Open the Advanced Search Options section of the search form.

b) Find the Warehouse selection, and choose the warehouse name that matches the Ship Group you are editing.

c) Press the Search button and select 'Unassigned Products' from the drop-down.

d) In the products results, confirm the number of products matches the warehouse assignment (check with your other browser).

e) If the number of results exceeds 20, change the Show selection to "100" or "Show All", but a reasonable amount of records needs to be selected so you can make the mass assignments.

f) At the top of the first column, check the checkbox to select all results. The Update button should activate.

g) Press Update button and choose the option 'Assign Selected Products'. Wait for the operation to complete. Once all records are assigned, there should be a message in red indicating there are no additional records in the results. Press the Back button.

h) Continue by repeating for each new Ship Group, until all have products assigned.

i) Confirm again that the number of products assigned to your warehouses matches the products assigned to your new Ship Groups.

4) Delete the duplicate warehouses. As you remove each one, there is an option to reassign the products to a new warehouse. Select your default warehouse and press Delete. Repeat until all duplicate warehouses are removed.   

5) The last step involves assigning Shipping Methods to the Ship Groups.  To do this, we suggest you review your existing Gold store.

The Ship Group feature was added so you can reduce the number of shipment options displayed to the customer by combining shipping methods that are common to the products within that shipment. To utilize this new feature in the best manner, you'll need to review your shipping method to warehouse assignments in Gold.

If a shipping method was assigned to a particular warehouse in Gold, then assign it to the matching Ship Group.

If a shipping method can be used in more than one Ship Group, then make sure to assign it to each of them, or make it applicable to All Ship Groups.

A new "Special Condition" shipping option is now available for each product. The available options are to 'calculate shipping costs separately' and add the calculated amount into the total shipping cost, or you can select a new option to indicate that the 'Item Ships Separately', in which case it will always be in its own shipment.

FINAL TESTING

Above all, test your store and make sure that systems for email, shipping, tax, and payments are all working.

Please post upgrade issues to a forum that we have setup for this purpose.

Store Design - Customize!

There are a few steps that can be taken to customize your store after upgrading. You can try it yourself, or contact us for information on upgrade services.

Set a Theme

1. From the Website > Design > Themes page, copy the default Sample Theme and give it a new name.  
   
   This will keep a backup of the original store theme and allow you to make changes to your own theme. You can also use the Download icon to save a .zip file containing all files and folders for the theme.

2. Select your new theme and press the Set Default Theme button.

3. Take a self-guided tour of the new Website administration menu and its features.  Go to Website > Design > and click the help link in the upper-right corner of each page for Layouts, Page Templates, Inner Templates, Widgets, and Boards.
   This will help you gain an understanding of the page structure before beginning customizations.  

Update your Store Logo

The first step will be to upload your Store Logo for the full-size website, small-size mobile devices, and customer invoices.

1. From the Website > Design > Store Logos page, there are three types of store images that are used to display your store logo. Hover over the existing images to get an approximate size for each of the main store logo, mobile logo, and printable invoice logo.

2. Delete the existing sample logo first, then drag your own logo to the empty image-drop area. Save.
   
   Repeat for each logo type.

3. Clear your cache and preview your storefront. You should see the sample images replaced with your own.
   
   Tech Note: The 3 logo images are located in the ../Themes/{YourThemeName}/Content/images/ folder. Each image uses a name that is reserved by the application. Use "logo.gif, logo.jpg, or logo.png" for the main website logo image; likewise, use valid images for the "mobilelogo and printlogo" for automatic image assignment.

Choose a Store Header and Footer (optional)

At this time, we offer only a few choices for the store header and footer, but we welcome you to create your own custom design.

If you do not want to select a different header of footer at this time, continue to the next section, "Add your Contact Information..."

If you would like to change to a different header or footer, we provide instructions on how to apply the change to multiple pages or a single page.

To apply a different header or footer to multiple pages, follow the instructions provided in the Merchant Guide:

1. From the Website > Design > Page Templates page, a list of page templates is shown. This is a good starting point.

2. Click on the HELP link in the upper-right corner of the page.

Note: The merchant guide has several pages that can walk you through examples of customizing your store. If you are new to AbleCommerce 9, then it might be a good idea to review this information before beginning.

Add your Contact Information in the HTML Snippets

Replace our sample contact information with your own.

1. From the Website > HTML Snippets page, edit each of the snippets by replacing the sample content with your own.

1. Contact Info is used in the top-most row of the header board. At a minimum, update the email and phone number to your own.

2. Footer Links are used in the footer boards, depending on the background color being dark or light. To update the sample content, edit Footer Links (Dark) with your own contact information. Remove, add, or change the links within the sample content as needed. The links provided in the "My Account" column of the footer are working and do not need their URL's altered.

3. Edit the Copyright (Dark) snippet. There is a list of payment method icons that can be adjusted to match your store's offerings.

Tip: The sample data includes two header boards and two footer boards. Just swap out the boards from any page template and edit the content as needed.

Edit your Content Pages to remove old code

Remove any references to ConLib objects within your existing content pages. Please read through all steps before beginning.

1. From the Website > Content Pages page, you should have a listing with a Home Page, Contact Us page, and any other pages that you had previously created within AbleCommerce Gold.

2. Edit any pages from the upgrade that contain code like [[ConLib:FeaturedProductsGrid]]. This will no longer display in the new CMS system. For the most part, almost all of these "ConLib" controls are now available as widgets. Some of the names have changed a bit, but each widget is documented with a description of its function, and the best part is that you'll have much more control over what is displayed with each one.
   
   To replace the code that was removed with a similar, or matching widget, you'll need to modify an inner template.  If the template is, or will be shared, then you can make a copy if you like.
   
   Let's start by editing the home page.
   
   From the Website > Design > Inner Templates page, find and edit the "Home Page" inner template. Take a quick look at the Layout tab..just take note of the simple inside layout..now go to the Content tab. You should see two widgets: Webpage Content and Featured Products.
   
   To make changes, press the Edit Content button.
   
   Feel free to add new widgets, change any widget settings, or rearrange the ordering. Save your changes. Now view your new home page.

Increase Image Upload Sizes (optional)

A good responsive website design should use large images because they expand or collapse in size. You may want to adjust the default image upload sizes, or keep your existing settings.  This will only change the size of new images when the 'upload and resize' feature is used. It will not change the size of your existing images.

The upgrade did not change your existing image settings. To change these values, go to the Configure> Store > Image Settings page.

The new recommended settings are as follows:

Icon Image width 75 and height 75

Thumbnail image width 270 and height 180

*Standard image width *2048 and height *1365

Defaults for options are 75 by 75

*If you change the settings, make sure to upload images that are greater than the Standard image width and height set.

Tips for the new Storefront Design features

• For every object (category, product, content page) in the store, you can select a different page template and inner template. To keep things simple and easy to manage, you can set your own default templates for each type of page. This is done from the Website > Design > Page Templates page

• The page template determines the overall page layout and typically includes shared content for all the pages using it. The page template is used to establish the header, footer, body, and any sidebars.

• The body is an area of the page template that is reserved to display content for the inner template. The inner template can be used by one page to do something unique, or it can be shared by several pages. Each page within the store can be assigned its own inner template.  

• An inner template includes its own inside layout with any mix of HTML and/or widgets. The purpose of the inner template is to display the body of the page, whereas the page template determines the overall page layout and what content will be shown in outer shared components, such as a header, footer, or sidebar.

• Widgets can be used in page templates, inner templates, and boards, and many serve a specific function in the store. Surround them with your HTML Snippets and create a totally unique page design.

• Widget settings that are inserted and changed on the admin side will override the application's default settings. Widgets that are changed on the retail side will override all settings, but apply to only the page they are changed on.

• When adding new widgets, take care to select widgets from a compatible category.

• If you plan to change a layout that has existing content, make a note of the zone name (e.g. Main) before removing it from the template. After editing the layout (with or without new zones), you can simply enter the name of the existing zone (e.g. Main) and it will be reinserted in the template with any existing content still in place.

If you need to help with customizations, please contact us.