How to install ShipperHQ on Magento 1

Overview

This is the comprehensive guide to installing or upgrading your ShipperHQ Magento 1 install. For instructions on installing or upgrading ShipperHQ for Magento 2, please see here.

Please note that the steps have changed slightly for the release of SHQ version 2.181, so any upgrades or installs of v2.181 or newer will be affected. Please follow the instructions carefully, as any missed steps can cause issues with your install.

Once this process of installing ShipperHQ is complete, you can move on to configuration of the extension within Magento.

Getting The Extension

You can download the latest ShipperHQ extension for Magento 1 in the public repo: https://github.com/shipperhq/magento1

Latest Version

To follow the latest versions of the extension, you can watch the public repo at https://github.com/shipperhq/magento1

Video Walkthrough

Main Installation Process

1. Switch off the Magento Compiler if enabled under System->Tools->Compilation
2. Ensure Cache is enabled in Admin under System -> Cache Management
3. Extract the Zip archive(s)
4. Copy the contents of the app directory (except for the “etc” directory, which will be copied last) from the extracted Zip into the app directory in your Magento base directory
5. Copy the contents of the other directories present in the extracted Zip (for example, “lib” and “skin”) into their respective directories within your Magento base directory (except for the “docs” directory, which is documentation only).
6. Copy over the contents of the app/etc directory from the extracted Zip (omitted from the steps above) into the app/etc directory in your Magento base directory. (Copying this last greatly reduces the chance of SQL not running correctly.)
7. Log out of admin and back in. If you do not do this you will get 404 Access Denied errors
8. Disable cache in admin
   
9. Flush the Magento cache storage in cache management by clicking the ‘Flush Magento Cache’ Button. (Or you can manually remove /var/cache and var/session contents.)
10. Open frontend of website to force extension to load (this will ensure that the SQL updates within extension are performed).
11. If you’re using the compiler you need to recompile via System->Tools->Compilation. If you do not you will see an error similar to ‘Call to a member function toOptionArray() on a non-object…’ when accessing shipping methods. You may also see Fatal Errors for missing files
12. You have now installed your extension and should see it present in relevant area of backend
13. Re-enable cache in admin and refresh

Setup

By default, all of the modules will be enabled. This is a safety net because having extra modules turned on is safer than having needed modules turned off. When you use the synchronize feature unused modules will be disabled. Please see one of the below sections, which will apply depending on whether you are a new customer or upgrading from a new or older installation. Once you have completed this setup you will be ready to begin configuration of the extension.

New or Recent Customers (Upgrading from SHQ > 2.181)

On new installs the modules will turn themselves on and off whenever the user Synchronizes SHQ. If they change features in the SHQ dashboard then the next time they Synchronize the modules will be adjusted again. Synchronize should show these screens:

• The features that need to be disabled should be listed:
• After pressing Synchronize the list should be empty:
• If WSA Logger is turned on there will be a message in the log showing which features were turned on/off.
• Later when the customer changes their SHQ features the changes will show up in the sync list. In this case I turned on the Freight and Pickup features:

Older Returning Customers (Upgrading from SHQ < 2.181)

To reduce the risk of breaking an existing site, modules will not automatically disable themselves for customers upgrading from an earlier version. This feature has to be explicitly turned on for them.

Under Config > Shipping Methods > ShipperHQ the Disable Unused Modules feature will be disabled by default for customers who have upgraded from a previous version of SHQ (it’s on by default for customers who install fresh)

When the feature is turned off, the customer will see a list of modules that should be turned on/off on the Sync page. When they run Sync they will be notified that the modules could not be automatically enabled and given a list of features they should manually check (instructions below) to make sure they’re turned on.

The customer may want to turn on the Disable Unused Modules feature, and we should encourage them to do so. But before turning this feature on check

• if the customer has customized ShipperHQ in any way.
• If they are running a customized checkout or post-order system that specifically depends on ShipperHQ

If they have done either of these then their developers need to carefully check that the customized code does not require any of the extra modules, and if so can that code handle the modules possibly being turned off. If they cannot determine if having a module shutoff will break a customization this feature should be left off and they should follow the manual enable/disable instructions below.

If the customer is fairly confident that they have no customizations that rely on a SHQ extra feature, then they can turn on the Disable Unused Modules setting and their site will now automatically update itself at Sync time.

Other Installation Processes

Manually Enabling/Disabling Modules

If the Disabled Unused Modules feature is disabled then Synchronize will still list the modules it thinks should be turned on or off. The customer can use this as a prompt to enable or disable modules themselves manually.

Modules are disabled by changing the app/etc/modules/MODULENAME.xml file

Inside the file the line that says <active>true/false</active> should be updated. Set the value to true to turn the module on, set it to false to turn it off

(Example: This file will turn the Freight feature off)

After changing these settings the customer should refresh their Configuration Cache

Migrating from Magento 1 to Magento 2

When migrating from Magento 1 to Magento 2 there are some additional steps for the migration of the ShipperHQ Magento 1 extension to the Magento 2 extension as the files are completely different. Instructions for this process can be found in this document.

Troubleshooting

• “HALP! I ran synchronize and my site broke!!!!!”
  • 
  • First make sure to refresh caches
  • If it’s still broken the customer has a customization that’s expecting one of the features we just shut off to be turned on. Turn them back on using the manual instructions above then turn off the Disable Unused Modules feature.
  • If you can’t determine precisely which module needs to be turned on, turn them all on. It’s better to have too many enabled then to have too few.
• “I ran Synchronize and I got an error about missing modules!”
  • 
  • Possibly the Disable Unused Modules feature is turned off. Use the steps above to decide if the customer can turn it on and synchronize again.
  • If Disable Unused Modules is already on and the customer still got this error then there is something blocking the sync from doing it’s job. Turn Disable Unused Modules off and follow the manual instructions.

Post-Installation Steps

In order to successfully connect your Magento eCommerce site to ShipperHQ you’ll need to configure your website in ShipperHQ. The final step is to configure the ShipperHQ Magento extension.