corner black line corner
black line
the Hazel Logo Hazel Enterprise: The Internet Merchandising System The Netsville Logo
start red bar Home News Info Features Examples Purchase Support Contact Us end red bar
Documentation: Upgrading

Hazel is mostly backward-compatible, but those upgrading their Hazel executable should be aware of changes which may affect them. Upgrading within the same major version is generally free. See our download page for information on accessing the latest Hazel for your platform.

Hazel 3.x to 4.x

H4 continues the path of backwards destruction by erasing past lapses of judgement. Some of these changes may seem cosmetic. So Hazel's a little vain.

New %HZU_FORM Token

(Added 5-Jan-2004) Hazel's new and improved state-tracking mechanism embeds the shopper's unique identifier into her URL when necessary. In checkout templates (particularly view.html and checkout.html, you should use %HZU_FORM|%HZU_MAIN as your form targets, instead of just %HZU_MAIN. With such, Hazel will use the newer %HZU_FORM if it exists (including all state tracking info), or fall back to the old "plain" URL if for some reason you decide to fall back to H3 or an earlier beta build.

This may fix your problems if you're getting "Still Looking" errors when switching from the nonsecure to secure server, particularly if your secure server uses a domain different from your nonsecure (eg. an ISP shared secure server.)

Products and Options Filenames

The Hazel products and options files now have a default name of products.txt and options.txt. You can change this default by adding a PRODUCTS_FILE and OPTIONS_FILE field to your hazel.config with the filename, but we suggest keeping the new extensions. They make loading and editing the files in some operating systems easier, and better identify them as simple text files and not a structured binary database.

New Default Template Names

H3 was distributed with a TEMPLATE_NAME_FORMAT in its hazel.config which forced the new preferred %s.html format for templates over the old hazel_%s.html format. Now the shorter is the default, so all you oldbies need to change those template names. Just remove the hazel_ prefix from all the HTML files in your root templates directory.

New Log Names

Pre-H4, if Hazel found a hazel.log file in her working directory (usually the same directory as the CGI), she would dump all manner of data into it as she processed requests. That could lead to some really huge files.

Now it's split into three files: hazel.log for simple records of catalog hits, hazel.err for things you should probably fix, hazel.dep for HZML (and other) deprecation messages (eg. "change %HZM_WORD to %HZH_WORD"), and hazel.bug for debugging data you probably want to ignore.

New Search Engine Nomenclature

The search engine has undergone the most changes of any other Hazel organ. Your best bet in upgrading is to download one of the H4 distribution matches.html templates and adjust it to fit your look-n-feel.

Hazel 3.2 to an Update

Post-3.2 updates removed much hoary backwards compatibility in preparation for the upcoming 4.0.

Out With the Old...

%HZU_FINISH, formerly used to point to the checkout URL of Hazel, is no longer supported. This was a 1.x compatibility option, and should be found only in 1997 and earlier catalogs. If present in your Hazel templates, replace with %HZU_MAIN.

The following config file field names have been changed.

Old New

Custom Templates

If you are passing a template field to force Hazel to use a custom template for a particular action, that template must now be located in a custom subdirectory of your hazel-cat folder. (You may set FLAT_PASSED_TEMPLATES to 1 in your hazel.config to avoid moving the templates, but that may go away in the future.)

Hazel 3.1 to Hazel 3.2

Only one issue here, and the change is backed out in a later version. It's a terrible mistake I wish we could just put behind us!

Missing Shipping Methods

Hazel gets cranky if passed a SHIP_METHOD field value for which a corresponding rules file does not exist in her hazel-cat/rules/shipping/ directory. This may affect you if you've been using hidden fields to force a SHIP_METHOD value such as "n/a".

The simple solution is to add ALLOW_MISSING_SHIPPING_RULES:1 line to your hazel.config file. That'll shut her up.

The proper solution is to remove those hidden fields (probably from your checkout template) and instead remove (or comment out) the SHIP_METHOD line in your hazel-cat/rules/field.rules file.

This change becomes inconsequential as of 3.216, wherein the behaviour was "rethunk" and Hazel no longer complains of missing shipping rules files.

Hazel 3.0 to Hazel 3.1

There are no issues associated with moving from any 3.0 version of Hazel to the official 3.1 version.

Hazel 2.x to Hazel 3.0

Upgrading to Hazel 3.0 from Hazel 2.0 is generally painless. Just stick your new key into your config file, then upload the new hazel.cgi, and you're ready! There are a few things you'll need to know which are outlined below. The first section deals with (relatively) important issues, while the rest of the document deals with things which might interest the more compulsive upgraders amongst you.

Hazel_Key Config Field

As of version 3.0, Hazel is available in two basic flavors -- "hardgoods" and "softgoods". Consequently, there are now two basic keys for Hazel. Instead of a single HAZEL_KEY, there is now a HARDGOODS_KEY and a SOFTGOODS_KEY in the config file.

The `message' Template

Hazel has a new template! It's called the "message" template and it's used when Hazel needs to tell the shopper something which isn't rightly classified as an "error", and thus inappropriate for the error template. You don't really need to download anything new to fix this -- just upload a copy of your error template as "hazel_message.html" (or "message.html" if you changed your filenames). You can then edit it to be less apocalyptic.

The Update Action

The UPDATE action has been deprecated. While it is still supported, its behaviour is somewhat erratic. Instead of trusting Hazel to guess what action was previously performed and repeat it, just use the action appropriate to the template. For example, in your view template, replace SUBMIT_ACTION_UPDATE with SUBMIT_ACTION_VIEW. On your checkout template, use SUBMIT_ACTION_CHECKOUT, and so on.

Brand Recognition

As of Hazel 3.0, the string "hazel" must be included in your HAZEL_NAME config file variable, and thus the filename of your Hazel CGI itself.

ATS and Hazel 3.0

If you are using the old ATS payment methods, you should upgrade to the latest Global Commerce system when you move to Hazel 3.0.

hazel_template.html is now template.html

Previously, Hazel templates were named "hazel_foo.html". We're trying to get rid of that superfluous "hazel_" prefix, but didn't want to break old catalogs, so we added a config field TEMPLATE_NAME_FORMAT. It's default value in the Hazel 3.0 distribution is "%s.html", which means, for example, the view template is named "view.html" rather than the old "hazel_view.html". If you want to shorten your template names, do the following...

  1. Rename the templates in your hazel-cat/templates directory from "hazel_foo.html" to "foo.html". This only affects those HTML templates beginning with "hazel_" in the root templates directory.
  2. Add the line TEMPLATE_NAME_FORMAT:%s.html to your config file.

MSIE & Quiet-Add

The good news? Microsoft fixed the 4.0 version of their browser so that it now works with the Quiet Add feature! The bad news? The hack we used in Hazel 2.x to get around MSIE's lack of support now causes some kind of memory corruption in MSIE 4.0. That "hack" involved sending a simple document "body" along with the header which tells the browser to do nothing.

In Hazel 3.0, the default behaviour is to NOT send a body with that response. Unfortunately, this may now cause problems with versions of MSIE before 4.0.

Anyway, if you want things to work the way they did before, add the line NO_CONTENT_BODY:0 to your config file. Or you can just forget you ever read this section and move along before your mind is twisted into a tangled heap of frazzled neurons.

Card_Verificaton is now Check_CCN

The CARD_VERIFICATION field (which, when set, rules out syntactically invalid credit card numbers) is now known as CHECK_CCN. This to be consistent with the new CHECK_CCD (rule out bad credit card dates) and CHECK_EMAIL (rule out obviously invalid email addresses) fields, and because CARD_VERIFICATION was just too damn long.

Hazel will still recognize CARD_VERIFICATION, but you should change it to CHECK_CCN just to be good and proper.

Hazel_CGI_Bin Begone

The HAZEL_CGI_BIN config file field was the "relative URL" to your Hazel CGI directory. It used to be sent with cookies, to tell the browser where it was allowed to send the cookie. Many users didn't know what the Hell a relative URL was, and therefore set it incorrectly, and therefore didn't get any cookies from their shoppers. Now Hazel doesn't bother sending that URL, and lets the browser figure things out on its own. When she does need the relative URL, she figures it out herself based on the URL she already knows.

In a nutshell -- you can remove or comment HAZEL_CGI_BIN from your config file, but it shouldn't make a difference either way.

Empty Action Template

As of Hazel 3.0581, the EMPTY action no longer displays the empty template when the cart is emptied. Instead, it displays a short message using the `message' template.

As of 3.105, you can customize this message by creating a `custom' subdirectory in your hazel-cat/templates directory and adding a cart_emptied.html file.

Missing Shipping Rules

As of Hazel 3.119, a missing shipping rules file in a hardgoods catalog will cause Hazel to print an error message. Add ALLOW_MISSING_SHIPPING_RULES:1 to your hazel.config file to make Hazel ignore missing shipping files

Getting Started HZML Rules Extras Advanced Reference
Products File
Order Reporting
Known Problems
HZML Tokens
HZML Loops
Sales Tax
Input Fields
Search Engine
Optioned Products
Design Tips
Payment Methods
Regular Expressions
Perl API
HTML Basics
CGI and You

Hazel Home - Help Contents - Searchable Knowledge Base - Live Technical Support

black line
corner black line corner