Introduction
Since GenHelm supplies source code for most of the GenHelm system runtime, and since GenHelm provides tools that allow you to create your own models and dollar functions, it is important to ensure that any customizations that you have made to your GenHelm installation are not overwritten when you install a newer version of GenHelm. To help guard against accidentally replacing customized components, GenHelm provides an installation wizard that makes it easy to see which components are being replaced by a new installation and which ones have been modified by your own web developers.
Preparing to Install
If you are an active GenHelm subscriber, you will be periodically notified of new GenHelm releases which may include new enhancements and/or corrections to previously released components. Eligible customers will be sent a link to the installation files which can be downloaded using this link. The installation files are divided into three groups and include a version number. For example, the following files represent the installation files for GenHelm version 1.2.5.
genhelm_v1.2.5.zip
system_v1.2.5.zip
sakilademo_v1.2.5.zip (optional)
If you have installed an earlier version of GenHelm you must copy at least the first two files to the sandbox folder named private_data/genhelm/install/installation_zips as shown here:
Once these files have been uploaded to your server (or saved locally if you are installing under Windows or a Mac) you can proceed to the next step.
Assign Sufficient Privileges
In order to use the upgrade wizard, your user id must belong to the site-admin group with the role of installer. Use the user model to check your user record to ensure that your Group/Role information includes this combination.
If you need to make this change, you will need to use the login page to log back into GenHelm in order for the change to take effect.
Launching the Upgrade Wizard
To launch the upgrade wizard program, add install/wizard to the genhelm url used in your sandbox. You will be required to log in to access this page. This will present a screen like the one below. It is recommended that you install the system upgrade first, then proceed to install the genhelm update and optionally the sakilademo update.
Backing Up Existing Installation Files
To install a newer system version, follow these steps:
- Select system in the drop-down
- Enter the version number that you have copied to the install/installation_zips folder
- Click the button labelled "1. Backup"
At this point, the upgrade wizard will compare the contents of the uploaded zip file with the corresponding files that are installed on the sandbox web server. It will copy any identically named files that have changed to a backup zip file in case you accidentally overwrite something during the installation. This procedure can take up to 10 minutes to complete so do not Interrupt this process. You will see the spinning hourglass until the backup is completed.
At the completion of the backup process, you will see a screen similar to the one below which provides a summary of the files that have been backed up prior to installing the current installation file. The backup file is stored in the folder private_data/genhelm/pre_install_backups. You can see in the message below that the backup was named pre_system_v1.2.5_bkup001.zip. You should only need to press the backup button once per installation file.
Installing Upgraded Files
In the lower portion of the screen, after pressing the Backup button, you will see the installation files that don't match those that are currently installed. In the case of GenHelm xml specification files, the right-most column shows the ID of the user who last saved the file. If this ID is indicated as genhelm, it means that the file has not been modified locally since it was installed by a previous GenHelm installation. In this case, the Install column defaults to checked so the existing file will be replaced by the updated file contained on the latest installation zip.
On the other hand, if the file was last saved by a user other then genhelm, this means that you, or a developer on your team, has modified this file. These files should be carefully reviewed to ascertain whether you want to replace the file with the updated version on the installation zip file. Doing so will delete the installed file along with any custom changes (however the backup will be retained in case you need to refer back to it). In most cases, you will want to create a merged version of these files that contain both the changes that have been made locally as well as the changes that are contained in the upgraded file on the installation zip. Depending on which file has more modifications, you should either choose to install the new file and reapply your customizations (using information contained in the backup zip) or you can avoid installing the new file and manually add in changes from the new installation zip. For certain files, such as site_settings, you will generally just keep the existing installed file since the only difference will be that you have added your security keys to this file.
Note that the files in the locate folder are used internally by the GenHelm IDE to find unqualified specification files and these files should generally be upgraded to the latest versions.
After reviewing and confirming that the correct files have been checked, click the button labelled "2. Install".
This will copy the selected files from the installation zip to your web server and provide a summary like the one shown below.
Install the GenHelm Updated Files
Repeat the process above pointing to the genhelm installation site.
Install the SakilaDemo Updated Files
If you have installed the sakilademo site, repeat the process above to upgrade this demo site.
Review Installation Log
At any time, you can click the Review Install Logs link to see the list of files that have been backed up and/or installed.
