Upgrading stores to Miva Merchant 5

The following information is for online merchants transitioning to Miva Merchant 5 from any version of Miva Merchant 4.

If you have a Miva Merchant 4 store, contact Miva Merchant, or your e-commerce hosting company, for information on upgrading your Miva Merchant license.

New users, who are just starting out in Miva Merchant 5, can disregard these instructions.


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.

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:

Prepare Miva Merchant 5 for the New Store
Get the Information from the Miva Merchant 4 Store
Import the Store, Copy Images, and Install New Modules
Announce Your New Store, Close Down the Old Store

The Miva Merchant 4 store is left intact following this process. It is not "upgraded" in the way that software applications are upgraded. That is, everything about the store (except for order information) is exported via the provisioning file, then imported into a new Miva Merchant 5 store. The upgrade license allows the two stores to be run side-by-side for up to six months, to give ample time for the transition.

Note that orders placed in the old Miva Merchant 4 store are not transferred to the new Miva Merchant 5 store. After you have upgraded to the new store, leave the old store in maintenance mode.

Additional stores are handled in the same way, one after another. That will be discussed below.

Detailed Instructions for Each Step

Install Miva Merchant 5

If your Miva Merchant 5 store is part of an e-commerce hosting package, the Web hosting company will have installed Miva Merchant 5 for you.

If your store is licensed direction from Miva Merchant, download the files from the FTP site, following the instructions in the upgrade e-mail message sent to you from Miva Merchant.

Run Setup for Miva Merchant 5

If your store is hosted by an e-commerce Web host, that company may have preconfigured the setup information for you.

Otherwise, go to the URL given at the end of the installation, and the setup process will begin automatically.

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.

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.

Leave it in this state until you are comfortable with the new store, and your have finished processing any open orders in the old store. Keeping the store "closed for maintenance" will prevent orders from being placed there after you have switched operations to your Miva Merchant 5 store. If orders were to be placed in both stores, inventory levels would get out of synch, and you would have two sets of data to maintain, and two sets of incoming orders to manage.

There is a 6-month transition period, during which your Miva Merchant 4 store remains fully functional. Once you are secure with the new Miva Merchant 5 store, and have completed any unfinished business in the old store, you can delete the store.

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.

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

First, At the Domain Level

If your store is part of a Web hosting package, contact the hosting company to get the upgrade module you will need for this step.

If your store is licensed direction from Miva Merchant, download the appropriate module upgrade5.mv (for Miva Merchant versions 4.00 to 4.13) or upgrade5.mvc (for Miva Merchant versions 4.14 to 5.00 ) from the Miva Merchant FTP site or the Miva Merchant Downloads page. You should have received the FTP information in an e-mail message from Miva Merchant.

Save the file to any convenient location on your computer, and make a note of it.

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, but you may want to change the name here to reflect the store name, such as MyStoreNo3Export.xml, if there are several stores in the domain.

Move the File

In the store data directory for your Miva Merchant 4 store, there will be an export folder, such as DATA\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 Miva Merchant 5.00 root data directory - the same directory where the Merchant2 and Merchant5 directories are located. If you specified a different name for the file earlier, rename it now to provide.xml.

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, an so on that you exported from your Miva Merchant 4 store.

Any errors (invalid codes, etc.) will be recorded in the Miva Merchant 5.00 data 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 (or Web)\Merchant2\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 (or Web)\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.

Meta Refresh - "Make a Note of Our New Address"

You can alert others to the change, and give them an opportunity to update their links or bookmarks, by using a HTML meta refresh tag in the maintenance message for the old store. This works much like a paper Change of Address card for a brick and mortar store. It alerts people to the fact you have a new address, and it is only available for a limited time.

When a shopper attempts to access any area of your store, they will see the maintenance message. After a few moments (an interval which you specify), they can be automatically taken to the storefront screen for your Miva Merchant 5 store.

Here is a simple example of a maintenance message that will send a visitor on to your new storefront. Insert your new store URL in place of the example URL shown here. Notice that content="10", in the first line, gives an approximately 10 second pause before going to the new screen. You can specify any amount of time you like. Keep in mind that people need longer to read text than you might expect.

<meta http-equiv="refresh" content="10; URL=http://www.mivamerchant.com/docs/merchant/mm5/DocsIndex.html">

%store_name% has moved to a new location. <br><br>

Please update your bookmarks, and visit us at:<br>

<a href="http://www.mivamerchant.com/docs/merchant/mm5/DocsIndex.html">Visit Our New Store</a><br>

Click the link above, or wait to be taken to the above site in about 10 seconds.

The message will appear, and send visitors to your new store, during the 6-month transition period, while your old store is left in maintenance mode.

Server Redirect - They Won't Even Notice a Change

If you manage your own server, you can use a server redirect. If your store is provided as part of an e-commerce package, contact your hosting company for assistance. The server redirect can be used in addition to the meta refresh described above, and should be, if your server or host supports it.

There are several advantages to using this method. First, the shopper is delivered to the exact page they were looking for, rather than being taken to the storefront. Second, you can keep the server redirect available as long as you like, where the meta refresh technique will only be available during the 6-month transition period from Miva Merchant 4 to 5.

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.

If you only have a few products listed, or just your storefront, manually update those listings to point to the updated URLs.

Process Any Outstanding Orders from your Miva Merchant 4 Store

Remember, order information is not transferred to the new store. Leave the old store in maintenance mode (to prevent shoppers from placing any new orders), and finish processing any orders that are still open in your old store. The old store will remain available to you for six months. That is, the license allows for a 6-month overlap period, when you can get the new store up and running, and close out the old one.

Updating Additional Stores

Log out of Miva Merchant 5.

Follow the same steps outlined above, beginning with creating the provisioning file. Remember to find the provisioning file, provide.xml, in the export directory for the store you are upgrading at the moment.

If you named the file anything other than provide.xml, rename it to provide.xml now.

Remember that the store manager must already be a user in your Miva Merchant 5 system before their store can be created.

When you are ready, log in to Miva Merchant 5 again, and the additional store will be created.

Be careful to copy any store images to the correct store graphics directory.


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.

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.

Related Topics:

Edit Store / Maintenance Mode