RATING: Advanced
VERSION: FileMaker Pro 5.5, FileMaker Server 5.5
PLATFORM: Macintosh, Windows
TECHNIQUE FILES: AutoUpdate.fp5
Plug-in Mania
Ever since FileMaker released version 4 of FileMaker Pro, which included the ability to augment FileMaker with new functions and features using a new plug-in architecture, third-party developers have rushed to the scene with a plethora of plug-ins that do everything from special calculations to graphing data using charts. Many developers have found these plug-ins to be a wonderful resource for allowing FileMaker to perform tasks that it was never able to do.
However, with the addition of plug-ins to the developer's arsenal came a new problem. How does the developer make sure the users of the system are using the latest version of a plug-in? Updating the system itself is easy, since any changes to the FileMaker files are automatic when users log onto the system. But plug-ins are stored individually on each user's computer, so distributing and keeping all these plug-ins up to date involved going to each computer and installing the plug-in manually.
FileMaker, Inc. identified this problem, and offered a fix for it with version 5.5 of FileMaker Pro and FileMaker Server. FileMaker Pro 5.5 includes a plug-in called Auto Update which is designed to help in these situations. It has the ability to check a special folder on the server and see if there's a newer version of a plug-in available, and if so, download it from the server and install it on the client machine. Keep in mind that a new version of the plug-in includes a plug-in that exists on the server-side but does not exist on the client-side. Meaning you can install new plug-ins as well.
The only caveat we have uncovered with the new Auto Update feature resides in multi-user operating systems. Whereas FileMaker Pro stores its plug-ins in a subfolder of the FileMaker Pro application folder, a plug-in will not be able to either be installed or updated if a user is logged into a non-administrative account and/or the user account does not have write permissions to the folder designated for FileMaker Pro plug-ins.
In this article, we'll cover how to set up FileMaker Server 5.5 to also serve these plug-ins and how to set up the scripts in your files to allow your FileMaker clients to check the version and install a new version if it's available.
Server Setup
The first step in using the Auto Update plug-in is to make sure everything is ready server-side. This is handled slightly differently, depending on whether you're running the server on Mac OS, Windows or Linux.
On a Macintosh running Mac OS 8 or 9, while in FileMaker Server 5.5, select "Preferences" from the "Edit" menu. Click on the "Files" tab and make sure that "Allow FileMaker Pro guests to download updates automatically" is checked. On a Macintosh running Mac OS X, launch the FileMaker Server Config application, select Preferences from the FMServer Config menu, click on the "Files" tab, and make sure there is a check next to "Allow FileMaker Pro guests to download updates automatically".
On Windows, open the FileMaker Server Console. Select "FileMaker Server" in the console tree and choose the "Properties" from the "Action" menu. Click on the "Files" tab and ensure that "Allow FileMaker guests to download updates automatically" is checked.
Lastly, if you're running FileMaker Server 5.5 on Linux, open up the "fmserver.conf" file in a text editor while logged in as the root users. Find the line that begins "UseAutoUpdate" and make sure that it reads "UseAutoUpdate ON". Save your changes, close the file, and reload the configuration file.
Now that we have the server set up to allow the updating of plug-ins, let's take a look at where the server needs to keep plug-ins so it can update them. Each platform that FileMaker Server runs on will have a folder called "AutoUpdate". On Macs, this folder is in the same folder that holds the FileMaker Server or FileMaker Server Config applications. On Windows machines, this folder is in the folder that has the FileMaker Server Console. On Linux, you'll find the "AutoUpdate" folder in "/var/fmserver/". Inside the "AutoUpdate" folder you'll see a number of sample files that are ready to be used for testing. We'll cover what these files are and what their names mean in a moment. This folder is actually the second place that FileMaker will search for plug-ins that can be updated.
The first place it will look, however, is the folder that contains the database that is being hosted and is calling the Auto Update plug-in's external functions. This can be useful for when you are hosting multiple systems with a single server, and only one or some of the systems need to have a plug-in updated. By storing the updated plug-ins in a folder for each system, you can control exactly which systems get the update and which don't. When searching for updates, FileMaker first searches the folder that the file is served within, on the server, and then, failing to find what it needs there, will search the "AutoUpdate" folder that exists by default.
For now, we're going to use this default "AutoUpdate" folder. If you open that folder, you should see a list of files with names like "FMPSADM.FMX", "FMPSADM.FMX.TXT", "Server Administration X.bin", and so on. FileMaker Pro can run on three different platforms that plug-ins need to be written for: Windows, Mac OS Classic, and Mac OS X. For each of these platforms a sample plug-in is provided: "FMPSADM.FMX" for Windows, "Server Administration X.bin" for Mac OS X, and "Server Administration.bin" for Mac OS Classic.
Also, each plug-in has associated with it a text file. This text file is named the same name as the plug-in followed by the extension ".txt". This text file is meant to hold a version string for the plug-in it is associated with. This makes it possible to check the version of the plug-in installed on a user's machine against the version installed on the server (as specified in this text file), and update the plug-in only if the version on the server is later than that on the client machine. If you open any of these files, you'll see that they all contain a single line of text: "FMPSADM 5.5".
Given that this text file is what the Auto Update plug-in checks to find out what the server's version of a plug-in is, if you place an updated plug-in on the server, you need to remember to change this text file. Even if the plug-in is actually a newer version, if this text file doesn't say so, then the update won't be downloaded to the client machines. It is up to the developer to program all logic with regards to the update process.
You'll also notice that the Macintosh plug-ins end with a ".bin" extension. If you're running FileMaker Server on either Windows or Linux, this is necessary because Macintosh files have two "forks" in them, which Windows and Linux operating systems don't understand. Storing Macintosh files on these systems without encoding them properly will lose what's called the resource fork, and render the plug-in useless. You can encode Macintosh plug-ins for storage on these systems by either using a program like StuffIt Deluxe, or by using an external function that FileMaker provides. StuffIt Deluxe can be purchased from < http://www.stuffit.com >.
Client Script
Before we begin writing the scripts that will actually check for plug-in updates and download them if needed, let's take a look at the logic behind them.
When your system starts up, part of its startup script routine will be to check the version of all the required plug-ins and compare these versions to those that are on the server. If the version on the server is later than the version that is installed, we want the Auto Update plug-in to download the newer version. Our script will select which version to download based on the results of the Status(CurrentPlatform) function. Since FileMaker loads plug-ins at startup, if a newer version of a plug-in was installed, then we need to alert the user to the fact and then quit FileMaker so that the user can relaunch the system with the new plug-in.
As we go through the scripts, you can either create them in a new file, or take a look at the included file, "AutoUpdate.fp5".
Our file has one script which is important to the auto update process. You would want to set this script to run automatically when your system starts up. The code for the script is below. One thing to note here: this script is using a demonstration plug-in that's included with FileMaker Server. Since that demo doesn't actually have any external functions, and isn't actually installed on your system when you first run this script, rather than referencing its version function, we reference a global field called "Version" to check the version of an installed plug-in. To see this script actually in action, you'll need to have FileMaker Server 5.5 set up and serve the sample file on it. Then open the file as a guest of the server, making sure that the sample plug-ins provided by FileMaker are in the AutoUpdate folder. See the sample file for more comments.
Set Field [External, ""]
If [Abs(Status(CurrentPlatform)) = 2]
If [TextToNum(External("FMSAUC-FindPlugin", "FMPSADM.FMX")) > TextToNum(Version)]
Set Field [External, "Updated " & External("FMSAUC-Updateplugin", "FMPSADM.FMX")]
End If
Else
If [Status(CurrentPlatform) = 1]
If [TextToNum(External("FMSAUC-Findplugin", "Server Administration")) > TextToNum(Version)]
Set Field [External, "Updated " & External("FMSAUC-Updateplugin", "Server Administration")]
End If
Else
If [Status(CurrentPlatform) = -1]
If [TextToNum(External("FMSAUC-Findplugin", "Server Administration X")) > TextToNum(Version)]
Set Field [External, "Updated " & External("FMSAUC-Updateplugin", "Server Administration X")]
End If
End If
End If
End If
If [not IsEmpty(External, 1)]
If [RightWords(External, 1) = "0"]
Set Field [Version,
Case(Abs(Status(CurrentPlatform)) = 2, External("FMSAUC-Findplugin", "FMPSADM.FMX"),
Status(CurrentPlatform) = 1, External("FMSAUC-Findplugin", "System Administrator"),
Status(CurrentPlatform) = -1, External("FMSAUC-Findplugin", "System Administrator X"))]
Else
Show Message [Buttons: "OK", "", ""; Data: "A new version of the System Administration
plug-in is available, but could not be installed. Please contact the system administrator."]
End If
End If
Yes, it's a long script for a sample file, but there's a lot to consider when updating a plug-in, including making sure the right plug-in is downloaded for the correct platform and double-checking the update was completed successfully.
Before we do anything else, we set External, a global text field, to an empty string. This is so we can tell later if an update was attempted.
The first thing we check for is the platform the system is running on. Status(CurrentPlatform) returns a 2 if the system is running Windows 9x and returns a -2 if the system is running any version of Windows NT/2000. Since plug-ins written for Windows work on any version, we compare the absolute value of the Status(CurrentPlatform) to the number 2, and if it's equal, we know we need to download the Windows version.
The second line is what we're using for this example so the sample file will work. We use Auto Update's external function FMSAUC-Findplugin to compare the version of the plug-in on the server to a string in a global field Version. In standard deployment situations you would use the Version function provided by the plug-in being checked. For the example technique file only, this field contains the text "FMPSADM 5.1". I used this string because the sample plug-in on the server has a text file with the string "FMPSADM 5.5" and converting these two strings to a number will result in the server's version being larger than the local version. Normally, if we were using a real plug-in, the second line (and the other lines which perform similar comparisons) would look like this:
If [ TextToNum( External( "FMSAUC-Findplugin", "FMPSADM.FMX" ) ) > TextToNum( External( "FMPSADM-Version", "" ) ) ]
This would compare the version on the server to the version installed on the client system. What it actually does, though, is check the version as it is entered in the file FMPSADM.FMS.TXT. This actually brings up some interesting possibilities with this plug-in that were probably never intended by FileMaker. The "FMSAUC-Findplugin" function returns the contents of the file that has the name passed as the parameter with the extension ".txt" added to it. Such a file doesn't necessarily have to have anything to do with actually updating a plug-in.
It's conceivable that you could have a file on the server that for some reason you wish to get it onto the user's system. On a Mac, perhaps it's a special AppleScript you would like to run occasionally, but want to easily edit separately from the FileMaker system itself. Whatever the reason, so long as the contents are less than about 64K (the limit of a FileMaker text field), you could use this plug-in to get text from the server to client machines. It's an interesting idea that I'm sure some enterprising developers will end up thinking of some original uses for.
Using the TextToNum function will often allow you to compare the number portions of the plug-ins, but not always. For instance, if a plug-in numbers one version as "Myplug-in 1.0b1" and another, newer version as "Myplug-in 1.0v1", the TextToNum function will show no difference in these plug-ins, and therefore won't update the plug-in. Check the version strings of your plug-ins to make sure you know how to compare them to determine which is the newer version.
If the version on the server is newer than the version installed on the local machine, then we call Auto Update's external function "FMSAUC-Updateplugin". This function will download the plug-in to a temporary folder on the user's hard drive, disable the existing plug-in, move it out of the enabled plug-ins folder, move the new plug-in into the enabled plug-ins folder, and enable the new plug-in. That's a lot of work for one function, and there are many things that could go wrong with it. This function therefore provides about a dozen possible error numbers. You can find a listing of the error numbers and their meaning in a document included on the FileMaker Server CD called "Auto Update Guide.pdf". Be sure to read through this document and check for the errors. If no error occurs, then the function returns a "0" as text.
Returning to the script, if the platform check for Windows fails, we then go on to check if the system running is Mac OS Classic. We check for Mac OS Classic and Mac OS X separately because many plug-ins have to be rewritten for Mac OS X. Notice that each platform's plug-in has a different name, which we use to pass as a parameter to both the "FMSAUC-Findplugin" and the "FMSAUC-Updateplugin" functions.
Once we have checked for any updates for the three possible platforms and updated any necessary plug-ins, we use another If block to see if anything was updated. It is here that you would specify any error checking and decide what you would want to do in the case of an error. We first check that an update actually happened by determining if the field External is still empty. If it is, no update occurred. If not, we want to make sure that the Auto Update function returned a "0" and that everything happened properly. In our case, since we're working with a sample plug-in, that doesn't actually have a version string associated with it, we update our Version field to have the same string as the version file on the server. This way, if we run the script again, it won't actually try to update the plug-in again. This tries to duplicate as closely as possible the behavior that a system would have in the real world.
If the value in External isn't "0", then some sort of error occurred. It would be here that you might have more extensive error checking. You might create a record in an error tracking file to store the error number. If it's critical that the user gets the new updated plug-in, you might also quit FileMaker, telling the user to contact the system administrator for assistance.
To test the update system, first make sure that the Auto Update plug-in is enabled in the application preferences ("Edit > Preferences > Application or FileMaker > Preferences > Application). Then click on the plug-ins tab and make sure there is a checkmark next to the Auto Update plug-in. If you don't see the Auto Update plug-in listed, you'll probably need to reinstall it from the original CD. Once the client has been set up to work with the plug-in, copy the sample file to a computer running FileMaker Server 5.5 and serve the file. See your FileMaker Server documentation for instructions.
Next, open the file on a client machine as a guest of your server and run the script. If everything works properly, you'll see the value in Version change to "FMPSADM 5.5" and the value in External change to "Updated 0". Heck, we could have done that much with a couple of set field steps. But what's really changed is that if you take a look in the folder that your FileMaker plug-ins are kept, you'll see that a new plug-in has been added. And if you take a look at the application preferences' plug-in tab, you'll see that the Server Administration plug-in is there and enabled.
One thing you may have noticed is that once the update has occurred, we don't really do anything else. When I first heard of the functionality of the Auto Update plug-in, my assumption was that once a plug-in had been updated, it would be necessary to quit FileMaker and launch it again to take advantage of the newer plug-in. My experiments and others' experience show that this isn't the case. Apparently FileMaker does what it can to disable the old plug-in and enable the new plug-in without having to quit FileMaker or open the Application preferences. But I would double-check that it works with your specific plug-in before trusting that this will always happen.
Conclusion
The Auto Update plug-in is a great addition to FileMaker's set of tools. With it, much of the hassle of working with plug-ins has been eliminated. Yes, issues surround non-administrative user accounts, but these can be circumvented by an administrator granting appropriate access privileges to the FileMaker Pro Extensions (Mac OS and Mac OS X) or System (Windows) folders.
Beyond the obvious advantage of Auto Update to plug-ins, the idea of being able to take a text file from the server and bring it into a field on the local machine is sure to have applications that no one's yet thought of. I look forward to seeing what will be done with it. If you've thought of a novel way to use this side benefit of the Auto Update plug-in, please drop me a line.
Charles Ross has worked with FileMaker for over seven years and is an independent contractor specializing in database and custom application development. You can contact him at chivalry@mac.com. This article was written with the help of the white paper "Using Plug-ins With FileMaker", written by Jesse Traynham (jesse@comm-unity.net) and Jake Traynham (jake@comm-unity.net) of Comm-Unity Networking Systems < http://www.cnsplug-ins.com >, used with permission.