Polytrope: CM Assistant

This article is addressed to anyone receiving files from Polytrope LLC. The article deals with three basic scenarios.

The solution runs in FileMaker Pro 8 and you're receiving a front-end file update from us that does not contain your data.
The solution runs in FileMaker Pro 8 and you are receiving an update from us that contains new versions of both the data file (with your data in it) and the front-end application file.
You're updating a solution that runs in FileMaker Pro 6.

Scenario 1. Installing a new front-end file

Nearly all of the solutions that we have developed since the release of FileMaker Pro 7 in 2004--including CMAssistant and Goodbooks--are comprised of two principal files: a file that stores your data (called the "back end" or "data" file) and a file that contains all of our programming and provides the user interface (called the "front end" or "application" file). If we send you just a front end file, installation is quick and easy and does not touch your data at all. The following process takes five minutes or so from start to finish. NOTE that, if you are performing an update of CMAssistant or Goodbooks, you may be downloading the very same front-end file that other licensees are downloading. The front end contains no licensee-specific information.

1. Take the current files entirely offline.

If you're using FileMaker Server to share your files, you must close them on all workstations first, then use the FileMaker Server Admin utility to close the files on the Server. If you are not using FileMaker Server, then you must make sure that you close the solution files on every workstation that is using the files, including the host machine. NOTE that, if you are running more than one FileMaker Pro solution, you only need to take offline the files that you are going to update. If, for example, you are also running Pre1 Software's Smart Publisher, you wouldn't want to touch those files just because you're updating CMAssistant.

2. Download the archive that contains the new version of the front-end file and extract from the archive the FileMaker database file inside.

We usually send out an email with a URL for the download. The downloaded file is almost always delivered as a zip archive. You will need to use a decompression utility such as WinZip or StuffIt Expander to extract from the archive the .fp7 file inside. Note that this download should be very quick, because the front-end file contains no data and compresses to a very small archive (usually < 1 MB).

3. Go to the machine where the existing copies of your database files are stored and navigate your way to the folder that contains the databases.

If you're sharing the files using FileMaker Pro Server 8, this is usually inside the FileMaker Server Databases folder. If your server machine is running under Mac OS X, remember that you must always configure the files so that they are in the fmsadmin group and give them read & write privileges.

If you are sharing files using peer-to-peer, FileMaker Pro sharing, then the files are stored on the machine that acts as the host, but they could be anywhere. (Optional) At this point, you may wish to back up your old copy of the solution files.

4. Copy or drag the new .fp7 file (the one you extracted from the archive in step 2) into the folder that contains your existing files. Your operating system will warn you that a file with this name already exists and ask if you want to overwrite it. Say yes.

Remember, this is a front-end update only. Your data file is not being touched.

5. You can now put the files back online.

If you're using FileMaker Server to share the files, use the Admin Tool to open the files under FileMaker Server. If you're using FileMaker Pro's peer-to-peer sharing, you can now open the files on the host machine (and you must always remember to open them on that machine first). If you are not sharing the files, well, then you were basically done in step 4, and you can open the files now any time you like.

You are done with the update. You should now open your files and make sure everything looks okay. If it does, we ask that you send us a quick email letting us know that you successfully updated your files. If you run into trouble, please consult the troubleshooting section below, and if you don't find an answer there, send email to Polytrope Support (support-at-polytrope-dot-com).

Scenario 2. Installing a full update/upgrade including data

Nearly all of the solutions that we have developed since the release of FileMaker Pro 7 in 2004--including CMAssistant and Goodbooks--are comprised of two principal files: a file that stores your data (called the "back end" or "data" file) and a file that contains all of our programming and provides the user interface (called the "front end" or "application" file). When we make a significant change to the structure of the data file, we have to upgrade you, which means, we have to get your data from you, move it from the old data file into a clean copy of the new data file. We then send you a link that points to your files specifically. Since these files contain your data, the email containing this link will not be sent via broadcast email but will be sent exclusively and specifically to you.

How long it takes to follow these instructions from start to finish depends almost entirely on how long it takes you to download your files in step 2. Most of our licensees have very fast connections to the Internet and can download even very large files in a matter of a few minutes. So this process should take no more than ten or fifteen minutes.

1. Take the current solution files entirely offline.

2. Download the archive that contains the new version of the front-end file and extract from the archive the FileMaker database files inside.

3. Go to the machine where the existing copies of your database files are stored and navigate your way to the folder that contains the databases.

If you're sharing the files using FileMaker Pro Server 8, this is usually inside the FileMaker Server Databases folder. If you are sharing files using peer-to-peer, FileMaker Pro sharing, then the files are stored on the machine that acts as the host, but they could be anywhere. If your FileMaker Server machine is running Mac OS X, remember that you must always configure the files so that they are in the fmsadmin group and give them read & write privileges.

4. At this point, we strongly recommend that you backup your files to a removable medium such as CD or tape.

The next step is going to be destructive. Do not proceed unless you know you have a good copy of your old files that you can go back to, if there is a problem with the upgrade. If you share the files using FileMaker Server and you know that they were backed up last night (for example), you should confirm that you have that backup before proceeding. DO NOT simply duplicate the files to another folder on your hard disk. Remember that there should be only 1 copy of the solution files anywhere on the server or host machine's hard disk.

If you don't have time to backup, here's an alternative safe approach: Rename the old files. For example, change CMASSISTANT5.fp7 to CMASSISTANT5_OLD.fp7; do something similar for the data file. Drag the renamed old files out of their folder and into the Trash/Recycle Bin. But if you take this approach, be sure you remove the old files as soon as possible. You don't want to have multiple copies of the solution files lying around; if you do, you will eventually get confused and disaster will follow.

But not having time to backup your mission-critical data is like not having time to fasten your child's seatbelt or pay your life insurance. Even if you rename, it is still a good idea to back the old files up.

5. Copy or drag the new .fp7 files (the ones you extracted from the archive in step 2) into the folder where the files are supposed to be stored.

If you left the old files in the original folder without renaming them, then you will, at this point, be warned that you are about to overwrite your old files and asked if you really want to do this. As long as you know you've got a good backup, say yes.

6. You can now put the files back online.

You are done with the update. You should now open your files and make sure everything looks okay. If it does, we ask that you send us a quick email letting us know that you successfully updated your files, so that we can stop worrying about you and also so we can remove your files from our server as soon as possible. If you run into trouble, please consult the troubleshooting section below, and if you don't find an answer there, send email to Polytrope Support (support-at-polytrope-dot-com).

Scenario 3. Installing a FileMaker Pro 6 solution

If you have not upgraded to CM Assistant and are using EXTRA! version 1 or 2, the following instructions apply to you, too; simply interpret references to 'CM Assistant' as references to 'EXTRA!'.

1. Backup your old files.
If you are re-installing CM Assistant after an upgrade, before you install the new files, you should backup your old files to a removable medium (tape, CD, etc.), then delete them from the server or host machine, or, if you're not sharing CM Assistant on your network, delete the CM Assistant files from the hard disk of the computer where they reside.

WARNING: Backing up is critically important and is your responsibility.

2. Unpack the archive file that you downloaded.
You will now have a folder containing the dozen or more files that comprise the CM Assistant solution. (The exact number of files depends on the version of CM Assistant you're using.) The file may also contain some subfolders (or it may not).

3. If you share CM Assistant on a network, open the files and enable multiuser access.
To do this, place the CM Assistant folder on a computer that has FileMaker Pro running, open CM Assistant, go to the options area, find the page relating to sharing, and select the proper file sharing status. When you are done, close the files completely before proceeding to the next step.

4. Move the entire folder to its desired destination.
By "move", we mean to say that the folder should end up existing just in one place. If you have to copy the folder to move it, then, once the copy is complete, be sure to delete the original.

5. Set the files up on the server or host machine.
If you're sharing CM Assistant under FileMaker Pro Server, you'll need at this point to use the Server admin database to open the files for sharing. If you're sharing CM Assistant on a host machine simply running a standard copy of FileMaker, you'll need to confirm that your installation guarantees that the files always open first on the host, before anyone at another machine attempts to access them.

6. Store the archive (your master copy of CM Assistant ) away in a safe place.

That's it.

A final caveat: It is imperative that there be one and only one copy of the CM Assistant and Goodbooks solutions anywhere on your computer network or on the hard disks of any of the computers using CM Assistant or Goodbooks.

Troubleshooting installation problems

Problem: You can't open the file that you downloaded from Polytrope's FTP server.

Solution: We send your files to you compressed into a one-file archive that has been created by Aladdin System's StuffIt file compression utility. You can usually decompress this archive and extract its contents with your favorite decompression tool (WinZip or whatever); but if you have trouble, then go to Aladdin's web site and get the latest version of their freeware utility StuffIt Expander.

Problem: You've tried to decompress the archive you downloaded, but the decompression utility tells you that the file is damaged.

Solution: We test files before uploading them, so it's most likely that your download was not successfully completed. Try downloading the file again.

Problem: You think you've extracted the files successfully from the archive you downloaded, but you can't open the files. You double-click on the main file and nothing happens.

Solution: Do you have FileMaker Pro installed? CM Assistant does not run by itself; it runs under FileMaker Pro.

Problem: You're installed the files, but one or more users on your network can't open them.

Solution: Several possible causes of this problem. Here are a couple.
1. Reread the information above about enabling multiuser access after decompressing the archive but before placing the files online for sharing.
2. Every copy of FileMaker Pro needs to be configured for network access. Go to the FileMaker Pro application preferences to do this.

Problem: Users can open the files in FileMaker Pro, but when they try to edit records they see an alert telling them that the files are not modifiable.

Solution: If the machine running FileMaker Server Pro is running under Mac OS X, you must make sure that each hosted file’s permissions group is “fmsadmin” and the privileges are “read & write”. And this change must be made every single time you transfer the file back to the Databases folder. This step is not necessary if you are running Microsoft Windows.

Problem: When you try to open the files, CM Assistant tells you that you need FileMaker Pro 8.5 (or whatever) or higher and won't let you get any further.

Solution: CMAssistant 5.9 and 6 require FileMaker Pro 8.5 or higher. CM Assistant versions 3.0 to 3.2 require FileMaker Pro 5.5 at a minimum and will not run under earlier versions. As of this writing, the latest version of FileMaker Pro is 9.

If you have any questions about installation, send email to Polytrope Support, here: support@polytrope.com.

This page last modified: August 22, 2008 9:46 AM

polytrope cm assistant/support: installation

Scenario 1. Installing a new front-end file

Scenario 2. Installing a full update/upgrade including data

Scenario 3. Installing a FileMaker Pro 6 solution

Troubleshooting installation problems