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. 789 .

FileMaker Server 7 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 user 's machine to see whether she has version such-and-such of such-and-such plug-in. If she doesn't, 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.

There's a bit of setup and scripting you have to do to make use of this feature, but it's certainly not more than an hour's work per solution. The time you'll 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. It's simply a matter of checking a check box. There's only one check box on the screen, so you shouldn't 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 placing the plug-ins in an appropriate directory. Inside the Database directory, you should have a folder called AutoUpdate. That's 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.

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 it's 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 compress 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. It's now commonly used for compressing files for all sorts of purposes. You can use the Terminal application on 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 expanded when Mac clients download the archive.

CAUTION

If you are using a Mac OS X version of FileMaker Server, then 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 you can see the directory and naming structures that you need to follow. There's 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 you'd take to build an auto update routine for a different plug-in. The plug-in that we've chosen as our guinea pig is UPLOADit, from Comm-Unity Networking Systems (www.cnsplug-ins.com). There's 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, you'll 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 Server 7\Data\Databases\AutoUpdate\ ) 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. Compress the Mac version of the plug-in into a .tar archive called UPLOADit_OSX.fmplugin.tar (see 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 you've 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 download ”which is described in detail in the next section ”you'll write a script that checks that the AutoUpdate plug-in is installed and active. If it's 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 7.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 there's no folder in the AutoUpdate directory on the server that's named the same as the specified parameter, then 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 . 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 Extensions\Saved folder to contain the backup of the outdated plug-in or support file couldn't be created.
  -3	The file to be replaced on the client computer couldn't be deleted from the Extensions folder.
  -4	The file to be replaced couldn't be moved to the Extensions\Saved folder.
  -5	The downloaded file can't be copied to the Extensions folder.
  -6	The download file must be a plug-in file.
  3	The Auto Update 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't 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 of a file that resides on the server. It will not work from a locally 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 client's 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, then you will want to have the auto update routine be part of the file's startup script. That way, if for some reason the user isn't 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) sub-scripts that are called from a master script is a matter of personal preference. In the example that follows, we use a single script: it's a bit easier to follow the logic. First, however, we briefly discuss each of the parts of the routine independently.

Check What's 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, you'll know not only whether the user's workstation already has the plug-in, but also what version of the plug-in they have (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're 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, then the script needs to proceed with the update routine.

Of course, if the user's workstation doesn't have the AutoUpdate plug-in installed and enabled, there's 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 something ”indeed, anything ”then the plug-in is active and you can proceed. If not, then you'll want to provide users with some feedback on what they need to do (such as calling the database administrator).

Check What's 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 you've set up on the server to contain plug-ins. If a folder with the specified name can't be found, the function returns a -1. If it is found, then 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 you've created within the plug-in's 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 it's in the plug-in's 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 .

There's 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 that's appropriate for the client's 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, then the function returns the string 1.0.1 1.0.2 .

CAUTION

Because the FMSAUC_FindPlugin function returns a space-delimited string, you should 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 you've determined the version numbers that are available on the server, you need to compare that 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 there's no single "right" way that will work in all cases. You'll 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 what's actually returned.

TIP

It's rare that you'll 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't have the plug-in, or if your comparison of the local and server versions reveals that the local version needs to be updated, then you'll 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 FileMaker's 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 user's 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.

It's 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 all's 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 example 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, it's necessary to have some conditional logic that takes the client platform into consideration. Assume in the following script that gLocalVersion , gRemoteVersion , and gError are all globally stored text fields. Finally, in this script we're simply interested in getting the version 1.0.0 plug-in on the user's 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.

  Set Field  [ AutoUpdatePlugin::gLocalVersion; Upld_Version ]  If  [ RightWords (AutoUpdatePlugin::gLocalVersion; 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 Field  [ AutoUpdatePlugin::gRemoteVersion;     Let ([paramName = Case ( Get (SystemPlatform) = -2;              "UPLOADit_Win" ; "UPLOADit_OSX");           versionString = FMSAUC_FindPlugin (paramName) ];           RightWords (versionString; 1)) ]  If  [ IsEmpty (AutoUpdatePlugin::gRemoteVersion) ]  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 Field  [ AutoUpdatePlugin::gError;     Let ( [pluginName = Case (Get (SystemPlatform) = -2;                "UPLOADit_Win"; "UPLOADit_OSX");            version = AutoUpdatePlugin::gRemoteVersion;            paramName = pluginName & " " & version] ;            FMSAUC_UpdatePlugin (paramName)) ]  If  [AutoUpdatePlugin::gError  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. You'd want to change the error handling to be appropriate for your solution. We've 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.

If you're having problems getting the auto update feature to work, check the troubleshooting section at the end of this chapter, titled "Problems with Auto Update."