Automatically Updating Plug-ins

Using plug-ins has become commonplace in FileMaker Pro solutions, both big and small. One of the perceived issues with plug-in use has traditionally been the difficulty of distributing them to client machines. Even with the advent of server-side plug-ins in FileMaker Pro 7, every client machine that needs to make use of plug-in functionality must have the plug-in installed and enabled.

For a full discussion of using plug-ins with FileMaker Pro, see "Plug-ins," p. 771.

FileMaker Server has a feature called Auto Update that simplifies the distribution of plug-ins to client machines. The concept is very simple. Place your plug-ins in a designated folder on the server. When a user makes a client connection to a file hosted by FileMaker Server, you can have a script execute that checks the users machine to see whether she has version such-and-such of such-and-such plug-in. If she doesn , the script can automatically download the plug-in from the server. The plug-in is placed in the appropriate directory (the Extensions folder within the FileMaker Pro folder) and enabled. The server thus provides automatic updates to client machines that request them, obviating the need to manually distribute plug-ins.

Theres a bit of setup and scripting you have to do to make use of this feature, but its certainly not more than an hours work per solution. The time youll save not having to run around to all the machines on your network updating plug-ins is certainly worth the investment of an hour.

There are essentially three tasks that you need to perform to use the Auto Update feature. These are

• Prepare FileMaker Server
• Prepare FileMaker Pro
• Add scripts to your solution files to perform the auto update

These tasks are covered in detail in the following sections.

Preparing FileMaker Server

To prepare FileMaker Server to provide automatic downloads of plug-ins, you must enable the option and put the plug-ins in the appropriate folder on the server.

You can turn on Auto Update within the Client Connections Assistant of the Server Administration Tool. Its simply a matter of checking a check box. Theres only one check box on the screen, so you shouldn have any trouble locating it. That same check box can be accessed on the Clients tab of the FileMaker Server Properties window, shown previously in Figure 25.2 . You do not need to restart FileMaker Server after enabling the Auto Update feature.

The other task you need to do on the server is to place the plug-ins in an appropriate directory. Inside the Database directory, you should have a folder called AutoUpdate. Thats where your plug-ins go. You create a folder within the AutoUpdate directory for each plug-in that you want to be downloaded to client machines. Name the folder the same as the plug-in itself, sans extension.

Caution

Note that plug-in files often have different names on Mac and Windows. If this is the case, each plug-in file needs to be treated as its own plug-in, with its own directory tree within the AutoUpdate folder. See the example using the UPLOADit plug-in later in this chapter for further details.

Within that folder, create a folder for each version of the plug-in that you want to make available. You can name the folders anything you like, but its recommended that you simply use the version number of the plug-in. For example, within the MyPlugin folder, you might have a folder called 1.0 and another named 1.1.

Finally, place the actual plug-ins within the appropriate version folder. If you have both Mac and Windows users, you need to place both the Mac OS X and Windows versions of the plug-in in this same version-specific directory. If you are using a Windows version of FileMaker Server and need to allow Mac OS X clients to download plug-ins, be aware that you must compress the Mac version of the plug-in as a .tar archive. (See the "Mac Plug-ins on a Windows Server" sidebar that follows to learn how to do this.)

Mac Plug ins on a Windows Server

If you need to make Macintosh versions of your plug-ins available from a Windows version of FileMaker Server, you need to bundle the Mac plug-in as a .tar archive and place the archive on the server. This ensures that Macintosh-specific file information is not lost during the transition of the file from one platform to another.

Tar, which stands for tape archiver, was originally developed to create tape backups on UNIX systems. Its now commonly used for bundling files for all sorts of purposes. You can use the Terminal application on Mac OS X to create a .tar archive that contains your plug-in.

From the command-line prompt in the Terminal application, navigate to the directory where the plug-in is located on your machine by using the cd command. (You can learn more about changing directories by typing in man cd at the command prompt.)

Say that the plug-in you are working with is called foo.fmplugin. You want to turn this into an archive called foo.fmplugin.tar. To do this, you would type the following at the command line:

tar -cf foo.fmplugin.tar foo.fmplugin

Take the .tar file and place that in the appropriate directory on your Windows server. The archive is automatically unbundled when Mac clients download the archive.

Caution

If you are using a Mac OS X version of FileMaker Server, you need to make sure that any plug-ins you place on the server are owned by the fmsadmin group and have group read permissions.

A sample plug-in is installed with FileMaker Server so that you can see the directory and naming structures that you need to follow. Theres also a sample FileMaker Pro database that contains scripts to download the sample plug-in. These are both valuable resources the first time you go about setting up an auto-upload routine.

To give you an additional, more real-world example, we walk through the steps youd take to build an auto update routine for a different plug-in. The plug-in that weve chosen as our guinea pig is UPLOADit, from Comm-Unity Networking Systems (www.cnsplug-ins.com). Theres nothing special about this choice; we merely wanted to use something other than the sample plug-ins that ship with FileMaker. You follow the same steps for any plug-in that you use.

When you download UPLOADit, youll get a folder full of demo files, instructions, and of course, the plug-ins themselves. The Mac version is called UPLOADit_OSX.fmplugin, and the Windows version is called UPLOADit_Win.fmx. The tasks you would need to undertake to prepare FileMaker Server to download these to client machines are as follows:

1. Create directories in the AutoUpdate folder on the server (FileMaker ServerDataDatabasesAutoUpdate) called UPLOADit_OSX and UPLOADit_Win. You need to have both because the plug-ins have different names on the two platforms.

2. Create a directory within each of these folders called simply 1.0.

3. If FileMaker Server is running on Windows, bundle the Mac version of the plug-in into a .tar archive called UPLOADit_OSX.fmplugin.tar (see the previous sidebar titled "Mac Plug-ins on a Windows Server").

4. Copy the .tar archive and the Windows version of the plug-in to the appropriate 1.0 folder.

After those steps have been taken, and assuming the Auto Update feature of FileMaker Server has been enabled, client connections to the server can now begin requesting the UPLOADit plug-in. The actual download process is covered in the following sections.

Preparing FileMaker Pro

For a FileMaker Pro client to download plug-ins from FileMaker Server, the client needs to have the AutoUpdate plug-in installed and enabled. This plug-in is part of the typical installation of FileMaker Pro, so unless youve disabled the plug-in for some reason, chances are that the client application will be all prepared to download plug-ins.

As with all plug-ins, the AutoUpdate plug-in should be placed in the Extensions folder within the FileMaker Pro application directory. To confirm that the plug-in is enabled, go to the Plug-ins tab of the Preferences dialog, which is shown in Figure 25.15.

Figure 25.15. The AutoUpdate plug-in must be enabled on a workstation for it to be able to retrieve downloads of other plug-ins from FileMaker Server.

As part of the routine for performing the actual downloadwhich is described in detail in the next sectionyoull write a script that checks that the AutoUpdate plug-in is installed and active. If its not, you can show users a dialog telling them to call the database administrator or giving them instructions on how to obtain and enable the AutoUpdate plug-in.

Performing the Auto Update

The actual downloading of a plug-in from the server to the client machine is triggered by a script executed on the client machine. The AutoUpdate plug-in, which was discussed in the preceding section, has three functions, which all play a role in an auto-update routine. These three functions are

• FMSAUC_Version (0)Returns a string containing the name and version number of the AutoUpdate plug-in itself. Currently, this value is "FileMaker Auto Update Plugin Version 8.0".
• FMSAUC_FindPlugin (plug-in_name)Returns a space-delimited list of the folder names on the server within the directory specified by the plug-in name parameter. The list, however, returns only folders that contain the specified plug-in. If theres no folder in the AutoUpdate directory on the server thats named the same as the specified parameter, this function returns a -1.
• FMSAUC_UpdatePlugin (plug-in_name_and_version)This is the function that actually obtains the plug-in from the server. A string containing both the plug-in name and version should be used as the parameter. If the plug-in downloads with no error, the function returns a 0. Table 25.3 shows the other values that may be returned.

Table 25.3. Error Codes Returned by FMSAUC UpdatePlugin

Error Code	Description
-1	The file to be downloaded is missing from the temporary folder.
-2	The ExtensionsSaved folder to contain the backup of the outdated plug-in or support file couldn be created.
-3	The file to be replaced on the client computer couldn be deleted from the Extensions folder.
-4	The file to be replaced couldn be moved to the ExtensionsSaved folder.
-5	The downloaded file can be copied to the Extensions folder.
-6	The download file must be a plug-in file.
3	The AutoUpdate plug-in is disabled in the FileMaker Server Administration Client Connections Assistant, FileMaker Server Properties (Windows), or Configure, Clients (Mac OS).
5	The download file can be found in the AutoUpdate folder on the FileMaker Server computer.
6	An error occurred on the computer running FileMaker Server as the file was being downloaded.
100	The external function definition for FMSAUC_UpdatePlugIn contains an invalid or empty parameter.
101	The function call from the client computer to the computer running FileMaker Server failed. The server computer might be running a previous version of FileMaker Server.

To download a plug-in from the server, a user must first open a client session to a file that resides on the server. Plug-in downloads will not work from a peer-to-peer hosted file.

A typical auto-update routine consists of three tasks:

• Checking to see what version of the plug-in, if any, already resides on the clients workstation
• Checking whether the server has a more recent version
• If necessary, downloading the plug-in to the client workstation

If a certain plug-in is required for a file to operate as designed, you will want to have the auto update routine be part of the files startup script. That way, if for some reason the user isn able to retrieve the plug-in, you can prevent her from entering the system. Whether you write the routine using just a single script or split it into three (or more) subscripts that are called from a master script is a matter of personal preference. In the example that follows, we use a single script because its a bit easier to follow the logic. First, however, we briefly discuss each of the parts of the routine independently.

Check Whats Already on the Workstation

Every plug-in should contain a function that returns the name and version number of the plug-in itself. By calling that identity function, youll know not only whether the users workstation already has the plug-in, but also what version of the plug-in it has (thereby possibly obviating the need to download the plug-in again). You need to manually install and enable the plug-in on a workstation so that you can find out what this function is supposed to return when everything is up to date.

In the case of the UPLOADit plug-in that is serving as our example, this function is called Upld-Version, and the version we e working with returns the string UPLOADit v.1.0.0. A quick call to this function at the beginning of your auto-update routine informs you whether the workstation already has everything it needs. If it returns nothing, or if it returns a different version number, the script needs to proceed with the update routine.

Of course, if the users workstation doesn have the AutoUpdate plug-in installed and enabled, theres no chance that a download can occur. You therefore need to check the version number of that plug-in as well; you do this with the function FMSAUC_Version (0). As long as this function returns somethingindeed, anythingthen the plug-in is active and you can proceed. If not, youll want to provide users with some feedback on what they need to do (such as calling the database administrator).

Check Whats on the Server

You can check what version(s) of a plug-in are available for download from the server by using the function FMSAUC_FindPlugin. The parameter you pass should be the name of a folder youve set up on the server to contain plug-ins. If a folder with the specified name can be found, the function returns a -1. If it is found, the function returns a string containing a space-delimited list of the version numbers of the plug-ins of that name that are available.

The version number string returned by this function contains the names of the folders youve created within the plug-ins directory; these may or may not correspond to the actual version numbers of the plug-in. That is, you can name the folder anything you want. As long as its in the plug-ins directory and contains the specified plug-in, the folder name is included in the response generated by the FMSAUC_FindPlugin function. For the example plug-in, the functions FMSAUC_FindPlugin ("UPLOADit_OSX") and FMSAUC_FindPlugin ("UPLOADit_Win") would both be expected to return 1.0.

Theres one other thing to know about the list of version numbers returned by the FMSAUC_FindPlugin function. It returns only the names of folders that actually contain a version of the plug-in thats appropriate for the clients operating system. That is, if you have a Mac version of the plug-in in a folder called 1.0.1, and a Windows version in a folder called 1.0.2, Mac clients see only the 1.0.1 directory and Windows clients the 1.0.2 directory. If both directories contain versions for both platforms, the function returns the string 1.0.1 1.0.2.

Caution

Because the FMSAUC_FindPlugin function returns a space-delimited string, you must avoid using spaces in the names of the folders you create on the server. It is impossible to parse one folder name from another if they contain spaces.

After youve determined the version numbers that are available on the server, you need to compare them to what the client already has to determine whether a new version should be downloaded. There are many ways you can go about comparing the local and remote version numbers, and theres no single right way that will work in all cases. Youll probably need to extract the numeric portion of the local version, using the GetAsNumber function or one of the text-parsing functions. Set up the name of the version folders on the server to facilitate easy comparison with whats actually returned.

Tip

Its rare that youll ever need or want to have multiple versions of a plug-in available on the server. If you have only one version, then you can simply check whether the local version equals the server version.

Download the Plug-in

If the workstation either doesn have the plug-in, or if your comparison of the local and server versions reveals that the local version needs to be updated, youll use the FMSAUC_UpdatePlugin function to download the plug-in to the workstation. The parameter you pass to this function should contain both the plug-in name and the version number, separated by a space. For instance, to download the Mac version of the UPLOADit plug-in, you would use the following function:

FMSAUC_UpdatePlugin ("UPLOADit_OSX 1.0")

If desired, you can use FileMakers string manipulation functions to dynamically build a string to pass as this parameter, using the results from the FMSAUC_FindPlugin function. If you know the name and version number you want, though, you can also hard-code it as has been done here.

If the users machine already has a version of the plug-in, it is automatically moved to a directory named Saved (within the Extensions folder). The new plug-in is placed in the Extensions folder and is enabled for immediate use. There should be no user intervention necessary before, during, or after the download.

Its good practice to include a final check at the end of your update routine to ensure that the plug-in is indeed active. This would consist of another call to the version function of the particular plug-in. Assuming that alls well, your startup script can proceed with any other desired tasks.

Putting It All Together

The preceding sections have discussed the tasks and principles involved in a typical auto-update routine. It should nonetheless be helpful to see a complete sample script from start to finish. The example again uses the UPLOADit plug-in and assumes a directory structure on the server as described in the "Preparing the Server" section. Because the names of the Mac and Windows versions of the plug-ins are different, its necessary to have some conditional logic that takes the client platform into consideration. Finally, in this script we e simply interested in getting the version 1.0.0 plug-in on the users machine. You could add more complex logic to automatically test for updates; this script would need to be edited slightly if an updated plug-in became available.

[View full width]
Set Variable [ $localVersion; Value: Upld-Version ]
If [ RightWords ($localVersion; 1) # "1.0.0" ]
 If [IsEmpty (FMSAUC_Version (0))]
 Show Custom Dialog [ Title: "Warning"; Message: "You do not have the Auto Update 
plug-in installed on your workstation. Please call Jasper, the database administrator,
 immediately"; Buttons: "OK" ]
 Halt Script
 End If
Set Variable [ $remoteVersion;
 Let ([paramName = Case ( Get (SystemPlatform) = -2;
 "UPLOADit_Win" ; UPLOADit_OSX");
 versionString = FMSAUC_FindPlugin (paramName) ];
 RightWords (versionString; 1)) ]
 If [ IsEmpty ($remoteVersion) ]
 Show Custom Dialog [ Title: "Warning"; Message: "The UPLOADit plug-in could not be
 found on the server. Please call Jasper, the database administrator, immediately"; Buttons
: "OK" ]
 Halt Script
 End If
Set Variable [ $error;
 Let ( [pluginName = Case (Get (SystemPlatform) = -2;
 "UPLOADit_Win"; UPLOADit_OSX");
 version = $remoteVersion;
 paramName = pluginName & " & version] ;
 FMSAUC_UpdatePlugin (paramName)) ]
 If [$error images/U2260.jpg border=0> 0 ]
 Show Custom Dialog [ Title: "Error Downloading Required Plug-in"; Message: "There 
was an error encountered during an attempt to download a plug-in required by this database.
 ERR = " & AutoUpdatePlugin::gError; Buttons: "OK" ]
 Halt Script
 End If
End If

As you can see, this script has three error traps in it. Youd want to change the error handling to be appropriate for your solution. Weve just put Halt Script steps in here, but you may want to exit the application or take the user back to a main menu layout.