February 22, 2006

Migrating the Project

Last week's post reviewed some of the options for the Compare and Report process. Now that we've done the compare (with or without the reports), we are ready to complete the project migration.

The view provided by the Upgrade tab is specifically designed for this step. We should select each object type in turn and look at the results to ensure that the expected actions will be performed.

First consider the comparison results. An object will have a status in both the source database (the one we're logged into) and the target database. For example, it could be a delivered object that we have modified. In this case the compare result might be "*Changed/Changed." The most important thing to notice here is the little asterisk, which means "custom." You might even see something like "*Unchanged/Unchanged." How could a custom object be "unchanged"? This relates back to the Comparison option discussed last week. The Comparison option gives a cutoff release or date. Objects changed since that cutoff point are "Changed" and others are "Unchanged." So an old customization could be listed as "*Unchanged." Again, in my opinion, it is usually not necessary to be concerned with this. Most of the time we can ignore the difference between "Changed" and "Unchanged" and simply focus on whether an object has been customized. With that simplification in mind, there are really four results in each database: (Un)Changed, customized (*), Absent, and Same.

An object comparing as Same/Same won't usually be migrated. Therefore, App Designer clears the Upgrade checkbox. For all other results, we must ensure that the Upgrade checkbox is set or cleared as appropriate. This is usually pretty simple to do. Just scan down the column looking for asterisks and "Absent."

You might decide to clear the Upgrade checkbox to keep an object from migrating. But be careful here. Remember that the next time you or anybody else runs the Compare and Report, the checkbox could be set again. It might be better to remove the object from the project to prevent an accidental migration.

An object comparing as "Absent/(anything)" presents a special situation. "Migrating" this object means that we will delete it from the target database. The proposed action will be listed as "Delete." However, the Upgrade checkbox will not be set. App Designer is afraid to delete objects without your OK. (This is one of the two things that App Designer is afraid to do. The other is an online table ALTER. I don't understand the hesitancy there either.) I believe that in almost all cases, the Upgrade box should be checked in order to allow the deletion to occur.

Yes, I can hear the objection. Why delete an object? It can't hurt to just leave it out there, right? That's often but not always true. Suppose, for example, that it's a PeopleCode program. Due to some customization, the program does not exist in the source database. If we just leave it alone in the target, though, it will execute. If we don't want this code to execute in the source, why would we want to leave it in the target?

(Another way to "delete" a PeopleCode program without running into this little obstacle is to replace its code with a comment indicating that the program has been deleted. This leaves something in the program, and so the object is not being physically deleted. It's also good documentation. But if you are just developing something and realize that a program you recently wrote is not needed, it's better to just delete it to keep the database clean.)

Other types of objects can also be "Absent" in the source database, even though they are a member of the project. Here's how that happens. You can attach an object to the project and then physically delete the object. This is done using File | Delete, or in the case of PeopleCode, by erasing all of the code from a program. Even for other objects that won't interfere if you leave them intact, it is probably better to delete them so that your two databases remain in sync. Otherwise these objects will show up as differences when you run a full database compare. You will then need to reconcile the differences and probably won't remember why the objects were deleted from the source database in the first place. Deletes also occur with updates delivered by PeopleSoft.

Now that the Upgrade checkboxes have all been set or cleared as appropriate, it's finally time to do the actual migration. Remember that an action will be performed only if the Upgrade checkbox is checked and the Done checkbox is clear. On the Copy panel you will see a Reset Done Flags option. "Reset" always sounded to me like something that would be done after the copy, but it's not. It really means that the Done flags will be cleared before the copy. If you want to push the entire project, check this option. If you are doing a partial migration of a few objects after a previous successful migration, clear it.

Until next time...