Pre-Conversion Tasks

You can and should do a number of things before converting older solutions to FileMaker 8. Your pre-conversion tasks vary somewhat from solution to solution, but some categories of tasks are still common to most solutions.

Our comments here are aimed at people who are converting older relational (multifile) systems of some complexity. The purpose of doing any pre-conversion work at all is to make the post-conversion work go more smoothly; for single-file and simple relational solutions, you might not need to have rigorous conversion plans like this in place.

Also, by conversion here, we mean beta conversion rather than alpha conversion. In fact, many of the pre-conversion tasks that we discuss will cause you to want to make new alpha sets of the files. The simple difference between alpha and beta conversion files (as you'll recall from earlier in the chapter) is that alpha files are meant to be experimented with and thrown away, whereas beta files are intended to be turned into your new solution.

Prepare for Conversion

Converting a solution entails much more than the physical creation of new, upgraded files; you need to prepare both yourself and your environment for the conversion. The process goes faster and smoother if you spend a bit of time up front planning out the details. The specific preparation tasks you should do include the following:

• Set up a test environment Install FileMaker 8 on the machine that you plan to use to actually perform the conversion and do testing. If you are networking your solution, having FileMaker Server 8 installed on a nonproduction server is important during testing.
• Acquire any necessary hardware and software You may need to upgrade machines and/or operating systems before you can deploy a FileMaker 8 solution. Be sure that you get the ball rolling on this task early on in your conversion process because it can cause deployment delays. If you use plug-ins in your solution, check with their vendors to learn about any compatibility issues.
• Learn FileMaker 8 We strongly recommend that you spend a fair amount of time learning FileMaker 8 and perhaps even develop a few new solutions entirely with it prior to converting your old systems. The learning curve is considerable; if a conversion project is your first exposure to the new FileMaker 7 and 8 features, it is certain to take you longer and be more difficult than if you had previous experience.
• Read the conversion documentation FileMaker's website has a number of documents and white papers that discuss different aspects of conversion. Check http://www.filemaker.com/support/whitepapers.html for documents relevant to conversion.

Document Your Solution

The more familiar you are with a solution, the better your conversion will go. Even if you're the sole creator of a system, having up-to-date documentation comes in handy during the conversion process. We recommend having at least the following items:

• An ER diagram If you've never taken the time to formally create an ER diagram of your system, now's the time. For a refresher on creating ER diagrams, please see Chapter 5, "Relational Database Design."
• Printouts of field definitions, scripts, and layouts You may balk at the thought of actually printing out and organizing all these documents, and some people may indeed find that creating PDFs rather than printing works well for them. Many subtle changes take place during conversion, and it's very helpful when looking at a script or calculation formula to be able to compare it with the original. One nice thing about hard copies, of course, is that you can annotate them as you go. You may, for instance, check off buttons on screen shots of layouts as you test them, noting whether everything worked as planned or needs post-conversion attention. The printouts become both your testing plan and your post-conversion audit trail.
• An access privilege matrix This is simply an overview of the privilege settings in your current files. Create it in a database, spreadsheet, or text documentit really doesn't matter.

If you use FileMaker Pro Advanced, you may want to create a Database Design Report of your old solution as part of your documentation process. Third-party tools such as MetaData Magic (from New Millennium Communications), Brushfire (from Chaparral Software), and Analyzer (from Waves in Motion) also are excellent documentation tools and are all highly recommended.

Fix File References

Whenever you link one FileMaker file with another, FileMaker uses a file reference stored in File A to locate File B. The operations that may require file references include defining relationships, performing external scripts, creating value lists based on the contents of fields in another file, performing an Open script step, and scripting an import from another file.

File references are visible and editable in FileMaker 7 and 8 for the first time. In previous versions, they existed, but were hidden "under the hood." When you convert files created in earlier versions, all the old file references are suddenly visible. You may be in for a bit of shock, in fact, when you examine file references in a converted solution and discover a hornet's nest you never knew existed.

Absolute Paths

To understand how that hornet's nest was created and why it can be difficult to untangle, you must understand how FileMaker managed file references in previous versions of the product. Prior to FileMaker Pro 5.5, all file references were stored as absolute paths: When you define a link from File A to File B, FileMaker remembers the full path to File B. On Mac OS X, that might look like /Macintosh HD/Documents/myDatabases/File B. On Windows, the full path could be something like C:/myDatabases/File B. If the link were to a hosted file, the link might include the IP address of the hosted file, as in 192.168.100.87/File B. If the hosted file were on the same subnet as the person defining the link, then the IP address wouldn't be stored; an asterisk would appear in the file reference instead.

The main problem with absolute references is that they tend to cause problems when you move files from one machine to another or rename files or folders. In those cases, FileMaker would pop up a message to the user saying, in effect, "I can't find File B...where is it?" You would re-establish the reference by pointing to the moved or renamed file. But rather than replace the previous reference, FileMaker would store the new path as an additional search path for the given link. If you had a file that had been developed over the course of many years and/or on many different machines, you may have had dozens of absolute paths stored in your files. If you ever had problems in previous versions where FileMaker would seemingly irrationally open the wrong copy of a given file, it was likely because there was an obsolete file reference higher up in the search order.

Another problem with file references in previous versions of FileMaker is that different linking operations might produce entirely new references. For instance, say you had created a relationship from File A to File B while the files were both open on your local computer. A file reference containing the path to File B would be stored. Then you moved the files to a server where they were hosted with FileMaker Server, and from your desktop you created a script in File A that called a subscript in File B. An entirely new file reference was created for the external script call.

Relative Paths

FileMaker Pro 5.5 introduced the option to store only a relative path when creating links between files. This went a long way to solve the problems caused by renaming or moving files. Rather than locate File B with a full path reference, a relative reference simply indicates the path to get to File B from File A. For example, the relative path may be ../File B, which would indicate that FileMaker should look for File B in File A's parent directory.

Conversion of File References

So what happens to all of these obsolete and redundant file references during conversion? The conversion routine does try to do some consolidating and eliminating of file references that are no longer needed, but in most cases, you'll still end up with a bit of a mess. As an example, Figure 18.4 shows the file references from a converted solution. The names of converted file references are simply set to the filename plus a counter if there are multiple references to a given file. Notice that there are no less than five separate references to the Mainmenu file. The fact that there isn't a "Mainmenu 3" or "Mainmenu 4" makes it clear that in fact the conversion routine did identify those as unneeded. The conversion log also explicitly identifies any file references that are removed during conversion.

Figure 18.4. In a solution that's been around for a few years, it's likely that you have a lot of redundant and obsolete file references.

There are several potential problems that you may experience using a converted solution with file reference problems. The first is speed: FileMaker looks for files in the locations specified by the file references, in the order in which they appear. A complex solution with obsolete file references may take many times longer to open than one with clean file references. (The extra time is taken up as FileMaker scans fruitlessly through the obsolete references trying to find the file.)

After conversion, you can, of course, manually change all the obsolete paths to updated, relative paths. In a complex solution, this may require manually editing hundreds of references. After you're finished, you'll have solved the problem of obsolete references, but not that of redundant references.

The problem with redundant references is maintenance. If you have five file references that all point to the same file, every time you set up a link to a file, you have to choose which of those five references to use. If you ever need to update the reference, you need to update it in five places. That may be an acceptable short-term solution, but eventually, you'll want to eliminate the redundant file references.

Simply deleting redundant file references can have potentially disastrous consequences. Every link that uses that reference, be it an external table occurrence, a value list, or an external script call, will be broken and will need to be repaired manually. The proper way to remove redundant file references is as follows:

Be sure to make a backup of your system before you start playing with file references; a small mistake such as deleting the wrong one can have far-reaching consequences.

MetadataMagic to the Rescue

Cleaning up file references in a converted solution can be a very time-consuming and frustrating process. Thankfully, there's a tool called MetadataMagic, distributed by New Millennium Communications (www.nmci.com), which enables you to clean up file references in your system prior to conversion. The File Reference Fixer, one of the tools of MetadataMagic, provides several options for modifying file references. If you use the Auto-Fix function, only the most recently created relative path to a file is retained, and all internal links are updated to use that reference. Obsolete file references are then removed from the files.

In a complex solution, you may be better off using the Consolidate and/or Set Relative-Only functions. For instance, if you have files that span multiple FileMaker Servers or are located in multiple folders, the Consolidate function simply changes multiple and/or redundant references to a single file references.

If you clean up file references in your old solution, the conversion process takes less time and you're left without a severe post-conversion headache. Figure 18.5 shows the post-conversion file references of the same file depicted in Figure 18.4, but this time the file references were cleaned up before conversion with MetadataMagic.

Figure 18.5. If you run File Reference Fixer before conversion, the file references in your new files are much easier to troubleshoot and maintain.

It's easy to see the improvement here. All the file references are now simple relative paths, equally well suited for deployment as a single-user solution or by FileMaker Server. Before using File Reference Fixer, be sure to read the documentation and practice on a set of test files.

Do Some Housekeeping

In addition to file references, other potential post-conversion problems can be avoided if you do a bit of pre-conversion work. You can actually identify much pre-conversion work by examining the alpha conversion files. You may, for instance, discover you have objects with illegal names, which are placed in between curly brackets during conversion. These can be changed in the original system so that by the time you're ready to do your beta conversion, they're no longer an issue. By doing as much work as possible in the pre-beta conversion stage, you'll reduce the amount of time and work required to get your converted files ready for production.

If there are scripts, layouts, relationships, passwords, value lists, or fields that you know are no longer used or needed, try to eliminate these before conversion. If there has been case inconsistency in the entry of passwords in your current system, take the time to standardize them. These efforts will be rewarded by shorter conversion time and having less to test after conversion. Any other housekeeping in the original files can only be beneficial, including organizing scripts, editing object names, and archiving old data.