Upgrading MIVA Merchant from version 4 to version 5

If you signed up for an ecommerce package with your hosting account and are still running MIVA Merchant 4, you can find instructions here for upgrading to MIVA Merchant 5. The original license you purchased will only work with version 4 and must be upgraded. A new license that will work with MIVA Merchant 5 can be purchased for a $50 license fee.

Overview

It is easy to transition from MIVA Merchant 4 to MIVA Merchant 5. Basically, you will use a new, free module to export your store to a file. When you run MIVA Merchant 5, the entire store will be imported. Copy the image files to a new directory, and install any new modules, and you're off and running. The following instructions will guide you through the process.

A store is moved to MIVA Merchant 5 via a provisioning file, provide.xml. This is a single XML file that contains all the information from a given store, including the products, categories, image references, customers, and so on.

Note, order information, including batches, is not transferred to the new store. You will need to process all orders before starting the upgrade process.

The URLs to the pages within your store will change. Information is included here to guide you in updating links and search engines.

Due to the significant differences between MIVA Merchant 5 and previous versions, third-party modules have significant differences. Some products you have purchased in the past may be redundant. For others, contact the module developers to assess compatibility issues and/or the need for upgrades.

The basic steps, which will be covered in detail below, are:

Get the Information from the MIVA Merchant 4 Store

• Put the MIVA Merchant 4 store into maintenance mode.
• Process any outstanding orders remaining in your MIVA Merchant 4 store.
• Create a provisioning file (provide.xml) for the store.
• Move the provisioning file to a safe place for use after MIVA Merchant 5 is installed.

Prepare Miva Merchant 5 for the New Store

• Contact ProHosting to purchase the new MIVA Merchant 5 license.
• ProHosting will install the new license prepare your account for MIVA Merchant 5.
• Register your new MIVA Merchant 5 license
• Add the store manager to the users list in MIVA Merchant 5.

Import the Store, Copy Images, and Install New Modules

• Move the provisioning file to the specified directory.
• Log in to MIVA Merchant 5, and the store will be created automatically.
• Copy the store image files into the store images directory for MIVA Merchant 5.
• Install any third-party modules, after checking with the developer regarding compatibility.

Announce Your New Store

• Update links to your store, from your Web site, or elsewhere.

Maintenance Mode

Put the MIVA Merchant 4 store into maintenance mode. Detailed instructions on working with Maintenance Mode are available in the Edit Store / Maintenance Mode Help topic.

Also see the suggested meta refresh technique, described below under Handle Links Coming in to The Store. By using this technique, you can direct shoppers to your new store.

Process Outstanding Orders

Note that orders placed in the old MIVA Merchant 4 store are not transferred to the new MIVA Merchant 5 store. You must process any outstanding order prior to upgrading to MIVA Merchant 5.

Create the Provisioning File (provide.xml) from Your MIVA Merchant 4 Store

First, At the Domain Level

You will need to download and save the Miva upgrade module to your local computer. This module can be found here. Save the file to any convenient location on your computer, and make a note of it.

Once you've saved the upgrade module to your local computer, please login to your store administration page. In the left navigation area, at the domain level, expand the Modules menu, and click Add Module. Click the round Upload File button to locate the file on your computer. Click Add to add the export module to your store.

Next, For Each Store Within the Domain

Once the appropriate module is installed at the domain level, it will be available in the Utilities area of each store in the domain.

In the left navigation area, under Stores, expand the menu for the store you want to export. Expand the Utilities submenu, then the Export Data submenu. Select Export Store to Miva Merchant 5.x.

Click Export, or change the name of the export file and then click Export. Check marks will indicate progress through list of tasks as they are completed. When the entire file has been created, Export Complete will appear at the bottom of the task list.

Note that if you name the file something other than provide.xml, it will need to be renamed back to provide.xml before it can be imported into your MIVA Merchant 5 store.

Move the File

In the store data directory for your MIVA Merchant 4 store, there will be an export folder, such as /mivadata/Merchant2/00000001/export, for the first store. In that directory, locate the file provide.xml (or a file by the name you specified).

Copy this file to your /protected folder for safe keeping until MIVA Merchant 5 has been installed on your account. This file will need to be placed back in the /mivadata folder after installation to help re-create the store.

MIVA Merchant 4 store folders will be renamed

Prior to calling ProHosting to purchase and install your new license, please verify that you have processed all remaining orders. The existing MIVA Merchant 4 store files will be renamed and moved to another location in case there are additional files that are needed.

Purchase MIVA Merchant 5 license

Contact one of our Techinal Support staff to indicate your desire to purchase a MIVA Merchant 5 license for your account.

Install License and prepare Account

Have our Technical Support staff install the MIVA Merchant 5 license and prepare your account so that you can install the new version of the software.

Register your new MIVA Merchant 5 license

Login to your Netadmin control panel and enter the ecommerce section by going here. You will then be asked to enter the registration infomation and register the new MIVA Merchant 5 license that you just purchased. This process will also install the MIVA Merchant 5 program on your account.

Add the Store Manager to the Users List in MIVA Merchant 5

Before the store can be created via the provisioning file, the user who was the store manager in MIVA Merchant 4 must exist in the new domain-level users list in new MIVA Merchant 5. A store cannot be imported if the manager is not present in the users list. The store manager's password in MIVA Merchant 5 does not need to match their old password.

If the MIVA Merchant 5 domain owner is also the store manager, they will already exist as a user. In that case, all you need to do is ensure that the spelling and capitalization is the same as it was in the MIVA Merchant 4 store.

To add a user, in the MIVA Merchant 5 administration interface, locate Users [Add] in the left navigation area. Click [Add].

If you want to designate a new store manager, either make that change in your existing store, before creating the provisioning file, or add the outgoing manager to the users list in MIVA Merchant 5 for the purpose of importing the store, then specify a new manager after the store has been imported.

Move Provisioning file to correct location

Move or copy the provisioning file you created earlier from the safe location (/protected was suggested) to the newly created /mivadata folder. This file should be named provide.xml, unless you named it something different in the process. You must rename it back to provide.xlm if this is the case. Note that there is now a mivadata.v4 folder in which the old MIVA Merchant 4 files are stored.

Log In to MIVA Merchant 5

When you log in to the new administration interface, MIVA Merchant will detect the provide.xml file, and will automatically import the store. A message will appear to inform you that MIVA Merchant is performing automated configuration operations. Do not close the browser window during the import process.

This will create the store, and populate it with the products, categories, settings, and so on that you exported from your MIVA Merchant 4 store.

Any errors (invalid codes, etc.) will be recorded in the /mivadata directory in a file named provide.log.

Once the file has been processed, it will be renamed provide.xml-processed-yyyymmdd-hhmm, where yyyymmdd is the date, and hhmm is the time that the provide.xml file was processed.

Copy the Store Image Files

For each MIVA Merchant 4 store, there will be a graphics directory containing all the images used in the store, including product images, category images, and the images used for buttons and navigation features. There is a separate graphics directory for each store, such as /html/merchant.v4/graphics/00000001 for the first store.

So that your images will appear in the new MIVA Merchant 5 store, copy all the files in the store graphics directory into the corresponding new store graphics directory, such as /html/mm5/graphics/00000001.

Note - Do not copy the entire /graphics directory, only each individual store directory. If you were to replace the entire MIVA Merchant 5 graphics directory with the one from Miva Merchant 4, it would overwrite the images used throughout the administration interface and wizards.

Install Any Third-party Modules

Because MIVA Merchant 5 and previous versions use significantly different database technology, most third-party modules designed for earlier versions will need to be upgraded. Some modules may no longer be necessary. Before adding any third-party module to your MIVA Merchant 5 system, contact the module developer to assess compatibility issues and/or the need for upgrades.

When you are ready to add new modules to the system, in the left navigation area, at the domain level, locate Modules [Add]. Click [Add]. Click the Upload button to locate the module file on your computer. Click Add to add the module to your store. Repeat for each new module.

Handle Links Coming in to The Store

Your own site, and others, including search engines, may link to your store, or even to individual product screens. Take advantage of these sources of shoppers by providing an easy way for them to continue to find your store.

Links from Your Own Web Site

If your MIVA Merchant store is incorporated into a Web site, update any links to reflect the new store URLs. To learn the URL for a store screen, go to that page directly, and make a note of it, or click the Links button, available throughout the administration interface, in the upper-right corner of many screens.

Update Any Search Engine Listings

If your store is listed with services that submit it to search sites, update your listings to include the new URLs.

Troubleshooting

If you encounter any of the following situations, try the following solutions.

I created the file, and logged in to MIVA Merchant 5, but it didn't create the store.

There are several possible reasons that the store would not be created. Depending on the situation, there may be a log file, provide.log, which you can open and read with any text editor.

• First, if you named the provisioning file anything other than provide.xml, be sure to change the name back to provide.xml. If the file name had been changed, log out of MIVA Merchant 5, and rename the provisioning file to provide.xml. When you log into MIVA Merchant 5 again, the store will be created.
• Check to see that the file is in the same directory where the Merchant5 directory is located (not in the Merchant5 directory). If the file was not in the that directory, log out of MIVA Merchant 5, and move the provisioning file, provide.xml, into the directory. When you log into MIVA Merchant 5 again, the store will be created.
• Confirm that the store manager from your version 4 store is in the user list for your version 5 domain.  Make sure the name is spelled and capitalized the same way. If the store manager is not found, the log file will include the error: User '<ManagerName>' not found. The many subsequent reported errors are only a result of the store not being created. To resolve this issue, create a user in MIVA Merchant 5 having the same name as that of the store manager, then log out of MIVA Merchant 5. Next, rename the provisioning file back to provide.xml (it will have been renamed to indicate that it was processed). Finally, log into MIVA Merchant 5, and the store will be created.

My store was created, but all the graphics are missing.

Remember that you must copy the image files into the new store graphics directory. They are not imported via the provisioning file (but all references to them are). Review the instructions above, under Copy the Store Image Files. Once you have copied the image files, refresh your browser window to see them appear in the new store.