Hidden Gem: Importing CF Admin settings in ANY release via 'import wizard', even AFTER installation

Note: This blog post is from 2014. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.

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 few simple steps

So how easy it it? Just a few simple steps:

1. create a particular folder (as expected by the migration process) within the instance on the server where you want to import them (more details below)
2. copy your neo*.xml files from the lib folder of your previous release (typically on some other machine). That would be cfusion/lib for CF10 and above, if using the cfusion instance, or naming another instance if necessary
3. place those into the newly created folder on the new CF version
4. note that if your neo xml files hold passwords, those would have been encrypted by the CF admin of your old version. You need to include the seed.properties file (also in the lib folder of your old version), so that the new version can decrypt those--and it will encrypt them in the new CF version using the seed.properties of the new version
5. 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)
6. 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)
7. 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 (though I add some gotchas to beware, below). And the simple process is documented in the "Installing CF" manual. Here are links for past and recent releases.

(The steps have not really changed much in recent releases, but watch out if any may refer 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". And change cfusion to your instancename if using instances.):

• CF2021 docs for admin migration
• CF2018 docs admin import page
• 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. (In older CF versions, you didn't even need to worry about the seed.properties file, but later CF versions required that, so I have updated my steps above to indicate that, since I originally wrote this post.) 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 beware that a DB verification error may indicate that instead the DB can't be reached which could be a firewall issue, indicating a need to tell the DB to allow this new CF server to access it.)

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.)

For more content like this from Charlie Arehart:

• Signup to get his blog posts by email:
• Follow his blog RSS feed
• View the rest of his blog posts
• View his blog posts on the Adobe CF portal

Need more help with problems?

• If you may prefer direct help, rather than digging around here/elsewhere or via comments, he can help via his online consulting services
• See that page for more on how he can help a) over the web, safely and securely, b) usually very quickly, c) teaching you along the way, and d) with satisfaction guaranteed