Note: This blog post is from 2014. Some content, links and indeed comments from others may be outdated--though not necessarily. Corrections are welcome, in the comments. I may revise the content if necessary.Have you ever faced the challenge of needing to migrate the CF Admin settings (datasources, mappings, scheduled tasks, etc.) from one machine to another, and from one CF version to a newer one? Did you know that there is an "import wizard" that you can (with proper configuration) run at any time to import settings from one release to another?
Before I discuss that, you may know of a couple of other solutions for this challenge: the CF admin ColdFusion Archive/CAR mechanism, available in some but not all editions (more below), and this same "import wizard" which runs at the end of CF installation, importing settings from an older CF version if found on the same box.
But what if either of those solutions don't work for you, and you have dozens of dsn's, scheduled tasks, mappings, or other settings you want to get from one machine/version to another?
You are NOT stuck having to manually copy settings from one screen to another! (And you should be very careful about the common hack solution of copying neo*.xml files from one instance to another, which may not always work and may break things.)
In this entry I'll discuss how you CAN indeed import the CF admin settings from nearly ANY release of CF into nearly ANY OTHER release of CF, in a fully supported way, and which CAN be done even after installation of a new CF release. (I say "nearly", because I worked with someone wanting to do this import of CF7 settings into CF10, and that large a jump was was not supported.)
I'll also mention an important potential gotcha to beware, as well as how to to get around that.
This is NOT a hidden gem in CF11, though do note a related one
First let me note that this is NOT a hidden gem in CF11. It's NOT NEW to CF11. You can do this in ANY release, but I class it as a hidden gem because many people are unaware of it.
That said, before I proceed, let me make sure you know that in my last blog entry, I mentioned a hidden gem that IS NEW in CF11: one can now run the ColdFusion Archive (car) feature in CF Standard, as well as CF Enterprise/Trial/Developer edition.
But as I mentioned there, that won't help if you have a CF10 or earlier Standard edition whose settings you want to import into CF11, since you can't run the the CAR feature in CF10 or earlier Standard editions to create the CAR file to import.
The solution: re-running the migration wizard
To repeat, if you install a newer version of ColdFusion on a machine with an older version of CF installed, the installer will automatically run a "migration wizard" as its last step (technically the first step before it opens the Administrator), and it will offer to import the CF Admin settings from the old release into the new one. That's of course very nice.
But what if you are putting the new release on a different machine? That's where this solution comes in: you can re-run the migration wizard at any time.
That's the part that many seem never to have known about, though it's indeed been documented for years. (But since there's no interface, folks miss it, even experienced folks offering help on how to migrate settings when the CAR feature is unavailable.)
The 4 simple steps
So how easy it it? 4 Simple steps:
- copy your neo*.xml files from a previous release (typically on some other machine)
- place them in a particular folder within the instance on the server where you want to import them (details below)
- modify the \lib\adminconfig.xml file in the new version to tell it to re-run the wizard (again see the docs linked to below for details of what to change and where to find it, etc)
- log into (or click any link in) the Admin which will cause it to prompt to run/re-run this migration wizard (assuming the steps above were done right)
- if there are any errors (or you may wonder if there are) with the import, see the migration.log and migrationexception.log files in the CF logs folder)
It really is that easy, and it's documented in the "Installing CF" manual. Here are links for the 3 recent releases.
(The steps have not really changed much in recent releases, but watch out that they are mistaken in the CF10 and above versions of the docs below in referring to the "new" server's path as "cf_webapp_new_installation_root_directory/WEB-INF/cfusion/lib". In 10 and above, that should be "cf_webapp_new_installation_root_directory/cfusion/lib", or change cfusion to your instancename if using instances.):
- CF2016 docs admin import page (CF11 docs have gone away, use CF2016)
- CF10 docs admin import page
- CF9 docs admin import page
- (In CF8, it was discussed only in the context of updating a J2EE edition of CF, but the steps really were not unique to that.)
So I hope that may help some of you, who maybe needed to move settings from one machine to another.
And again, you can rerun the wizard at any time, even after installation--though that comes with a potential gotcha.
Does this import DSN passwords?
Yep, it does, and in my experience they often do then work just fine. But you should definitely do a "verify all" (in the DSN page) to make sure they do work.
If all of them fail, you may need to re-type the passwords (but the verification error may indicate that instead the DB can't be reached, and that may be a firewall issue, indicating a need to tell the DB to allow this new CF server to acces it.)
But if some verify while others fail, you may want to check in the old CF admin (if you can still get to it) to see where they do or do not verify there.
A potential gotcha: JVM settings not imported
Note that since the wizard only looks at the neo*.xml files, that does not therefore import the settings implemented in the "java and jvm" page of the old server. You would need to look closely at that in your old and new server to reconcile settings (the jvm settings are within the jvm.config file on the old server.)
A potential gotcha: Do you really want to import ALL the settings?
Note first that the process requires that you have and import ALL the neo-*.xml files from the previous release. It won't let you put in just one needed file.
Second, it also presumes to take ALL the settings from those files and import them into the new release. Unlike the CAR file mechanism, you don't get to pick and choose to export/import only SOME settings.
This might be fine on a new install, but it may not be what you want if you've already started tweaking things in the new release. In particular, with CF10 and 11, doing this may overwrite some settings that you tried to make more secure, such as if you enabled the "secure profile". So do be careful.
[Update: I have noticed that at some point, either in CF2016 or perhaps even in an update of 11, the import wizard now warns that it will NOT import settings that would override settings controlled by the "secure profile". That's a two-edged sword, if you presumed that "all settings" on the old machine would be imported to the new one.)