Upgrading Projects

You can only upgrade from a working 4.x project. If you are attempting to upgrade from an earlier version of FarCry you must upgrade to 4.x first.

Preparation

There are several significant changes between Farcry 4.x and 5.0. Hopefully we've made these changes relatively painless by automating most of them through the updater. However, given the number of automated changes we strongly recommend you put in the appropriate preparation for upgrading.

Todo List:

Backup your code base; the updater will make changes to your code
Backup your database; the updater will make numerous schema changes
Update ./farcry/core to the Fortress build
Check your CF mapping to make sure its pointing to the Fortress release
Make Sure You Have Everything Backed-up!

Did we mention that the updater will make changes to your data schema and code base?!

The Updater

Farcry 5.0 includes a redirection script in the farcryInit tag, located in your project's Application.cfm. The farcryInit tag was a 4.0 specific tag that was used only in 4.0 and so we've hijacked this tag to induce the upgrade. If you are attempting to run a 4.x based project through the 5.0 framework you will be prompted with the option to upgrade.

When you opt to upgrade, the 5.0 updater application is copied into your project's webroot and you are redirected to the first step in the updater wizard.

The Updater Is Secured

The upgrade has to be done from the local machine (127.0.0.1) by default. If you need to access it from another IP you will need to update the lAllowHosts variable found in /farcry/projects/YOURPROJECT/upgrader5.0.0/Application.cfm with the specific IP addresses you wish to upgrade from.

Todo list (not much – how nice!):

browse to the webroot of your project
select option to upgrade
follow through the steps of the wizard

The Webtop

A significant change in the framework has been to rename the ./core/admin directory to ./core/webtop. As a consequence, if you are using a web virtual to point to the webtop (typically /farcry) you will need to change this.

Todo list:

If required, rename the /farcry webserver mapping to /webtop; it now points to /farcry/core/webtop instead of /farcry/core/admin

Application.cfm Moves to Application.cfc

The framework has evolved to use the Application.cfc component instead of the Application.cfm and OnRequestEnd.cfm global templates. The old and new approaches will not work together and you may need to make some changes to complete the migration to the Application.cfc way of things.

In order to share project Application.cfc settings between the project, webtop, and plugins we externalise the constructor to a file in the project webroot called farcryConstructor.cfm. The updater should have faithfully transferred your FarCry specific variables to this file. However, you may need to adjust application time-out (default 2 days) and session time-out (default 1 hour) values if they differ from the updater defaults.

If you had project-specific code in the Application.cfm you may wish to consider placing it in one of the relevent project config files located in /projectdirectory/config.

The files available are:

serverSpecificVars.cfm; called only before application initialisation (ie. first time application is run after a restart or on application timeout)
serverSpecificVarsAfterInit.cfm; called only after application initialisation (ie. first time application is run after a restart or on application timeout)
serverSpecificRequestScope.cfm; called on every request

Miscellaneous Code Changes for Customised Projects

We've targeted the updater at "vanilla" installations of 4.x If you have a customised solution, where you have built extensions and custom functionality you may need to make some additional changes. We've listed those common issues we've encountered thus far. Feel free to raise additional issues you may have under farcry-beta forum (or directly through your Daemon support service).

Security Service

Information pertaining to Security Introduction.

login.cfm; custom login templates will need to be revised
replace any references to request.dmsec to application.factory.dmsec in your project/plugin code base
Custom User Directory implementations will likely need to be rewritten. An example LDAP/ActiveDirectory userdirectory plugin has been provided as an example

Troubleshooting

You may experience errors on the upgraded website. The first suggestion after the upgrade is to login to the webtop (using /webtop) go to admin > coapi utilities and make sure any undeployed properties are deployed. This could occur if the project was an early version of 4.x

Post Update Clean-Up

You need to delete the folder created in your project "upgrader5.0.0". Leaving it in place is a security hazard. If the installer has completed correctly this should have been deleted automatically. If for any reason it was not, delete it now.

Deprecated Code

Watch this space...

Upgrading with large user table.

After a few upgrades I have had trouble with the migration script. What happens is that half way through the upgrade it times out and just stops.I have found that a large user database will cause this. The fix is this.

in /core/packages/security/farcryUD.cfc comment out this line <cfset result = result & "User group membership: #migrateUserGroups(stUsers,stGroups)#<br/>" /> in method migrate.
run upgrade
after upgrade run this query. Need to replace this because upgrade script is too recourse intensive and runs out of memory for big tables

insert into farUser_agroups(parentid, data, typename, seq)
(select fu.objectid as parentid,fg.objectid as data, 'farGroup' as typename, 0 as seq from farUser fu
join dmUser du on fu.userid= du.userLogin
join dmUserToGroup dug on du.userid= dug.userid
join dmGroup dg on dug.groupid=dg.groupid
join farGroup fg on dg.groupName=fg.title)