Installing and using Troi Plug-ins on FileMaker Server
This page last updated on June 5th, 2015.
NOTE The information below assumes the use of FileMaker Server 9 or FileMaker Server Advanced 9 (for instant web publishing). Note that you can use FileMaker Server 10 to 14 too.
Two types of plug-in uses
It is important to understand that plug-ins can be used by FileMaker Server in two type of situations: as a server-side plug-in and as a plug-in used by the web publishing engine.
You can enable FileMaker Server to use plug-ins with hosted databases and server-side scripts. When plug-ins are used by hosted databases, field calculations can be performed on the computer running FileMaker Server. When you run server-side (ScriptMaker) scripts the functions of Troi plug-ins can also be used in these scripts.
Web publishing engine plug-in
You can also install plug-ins to be used by the FileMaker Web Publishing Engine. This means that you can use Troi Plug-ins in a field calculation or FileMaker script with Instant Web Publishing (IWP) or Custom Web Publishing or WebDirect (in FileMaker Server 13 or 14). If you use Custom Web Publishing XSLT, PHP, or any other web technology can use the functions of the plug-in in FileMaker scripts or field calculations.
DEFINITION In the following we will call FileMaker plug-ins to be used by the FileMaker Web Publishing Engine a web-side plug-in.
NOTE If you want to enable FileMaker Server to make use of both Server-side and web-side plug-ins, you must install two copies of the same plug-in in different locations.
NOTE 2 We don't have a separate Troi Plug-in for server-side or web-side. There is only one kind of Troi plug-in. After installation the plug-in will know if it is running on a FileMaker Pro client or if it is running as a server-side or web-side plug-in.
No graphic user interface in FileMaker Server
One limitation compared to plug-ins running in a FileMaker Pro client, is that server-side and web-side plug-ins can't make use of a graphic user interface (GUI). This makes sense as FileMaker Server is running without a user anyway. Practically this means that plug-ins can't show dialog boxes, progress bars, flash dialogs etc. For example Troi File Plug-in contains a function TrFile_SelectFileDialog, which shows a dialog to let a user select a file. As this is not allowed, this function won't work on Server, and will return the error code kErrNotAvailableOnServer.
When you run a plug-in server-side, it will run in the context of the FileMaker Server application. FileMaker Server runs in a non-logged-in state and does not have permissions. You should be aware of this when you use a plug-in such as Troi File Plug-in: as long as you are targeting files or folders inside the Server Documents folder you should be OK, but outside of that you are likely to get permission errors.
64-bit plug-ins are needed for FileMaker Server 13 and 14
FileMaker Server 13 and 14 and WebDirect are 64-bit processes, for which plug-ins need to be compiled for 64-bit. On Windows 64-bit plug-ins have a different extension: fmx64. In the download of a 64-bit compatible plug-in you will find this extra copy of the plug-in.
How to install server-side plug-ins with FileMaker Server 13 and 14
FileMaker Server 13 and 14 can now also install plug-ins by running a server-side script, with the "Install Plug-in File" script step. You need to enable this in the Admin Console of FileMaker Server 13 and 14: go to Database Server and then to the Server Plug-ins tab. Enable this checkbox:
How to manually install server-side plug-ins
Installing server-side plug-ins is actually quite easy. First you need to copy the Troi Plug-in to the appropriate FileMaker Server Extensions folder. The path of the folder where you need to place a copy of your plug-in is on Mac OS X:
On Windows the path is:
location of server-side plug-ins
After you placed a copy, you need to enable server-side plug-ins with the FileMaker Server Admin console: go to "Database Server" and then the Server Plug-Ins tab. Make sure you enable the checkbox "Enable FileMaker Server to use plug-ins". See below:
Server plug-ins in FileMaker Server Admin Console
The new plug-in should be visible in the list of plug-ins which FileMaker Server can use, like the Troi File plug-in you see here at the bottom right of the image.
NOTE You may need to stop and restart FileMaker Server in order for new plug-ins to appear in this list. Also stop FileMaker Server if you are replacing a plug-in with a new version.
Once the plug-in appears don't forget to enable the plug-in via the checkbox next to each plug-in. FileMaker Server is now set-up to use the plug-in as a server-side plug-in.
How to install web-side plug-ins
Installing web-side plug-ins is also quite easy. First you need to copy the Troi Plug-in to the appropriate "Plugins" folder. The default path of the folder where you need to place a copy of your plug-in is on Mac OS X:
On Windows the path is:
location of web-side plug-ins
NOTE The FileMaker Server installer does not create the "Plugins" folder, so the first time you will need to manually create this folder. Also note that on Windows, confusingly a folder Extensions exist in the wpc folder, but this is not where you should put the web-side plug-ins!
NOTE 2 If you have a custom installation, you will need to put the plug-in on the host where the web publishing engine is installed. These folder locations are relative to the installation folder where the web publishing engine is installed.
You need to stop and restart the web publishing engine once you've installed the plug-in. It may not be obvious if the web publishing engine really restarted, so to be sure, you may also want to stop FileMaker Server altogether (or even restart the machine).
There is no user interface in the FileMaker Server Admin console where you can see if the plug-in is properly loaded as a web-side plug-in. The Troi log files (see below) can help you determine what is happening.
Log files for Troi Plug-ins
Troi Plug-ins, installed on FileMaker Server as server-side or web-side plug-in, write a log file to help you determine what is going on, like for example to see if the plug-in is properly installed. Troi Plug-ins create two separate log files, one for server-side and one for web-side.
On Windows you can find the logs here:
NOTE Troi Plug-ins only write a log file when running as a server-side or as a web-side plug-in.
The plug-in will write the registration status to to the log file. But also events, like error situations are written. Two error situations specific for plug-ins on FileMaker Server are:
Troi Server/Web licenses
To use Troi Plug-ins as a server-side or web-side plug-in you need to purchase a special Server/Web license of that plug-in. You can purchase Server/Web licenses in the online Troi Store.
Registering Troi Plug-ins with a text file
Troi Plug-ins can be registered with a text file or with a built-in registration function (requiring no external text file). First we show you how to register a Troi plug-in with a payment certificate file. See also the screenshots of the folder structure below.
Troi Server/Web licenses (Mac OS X)
Create the text file: "Troi Payment Certificate" and fill it with the received registration data and place it in these folder(s):
The total path for the file will be:
folder structure on Mac OS X
Please note: on some systems you need to place the Troi Payment Certificate.txt file one directory higher to register the plug-in for server-side use: put it in the /Library/FileMaker Server/Database Server/ folder instead of in the /bin subfolder.
Troi Server/Web licenses (Windows)
Create the text file: "TroiPay.txt" and fill it with the received registration data and place it in these folder(s):
The total path for the file will be:
You may need to restart FileMaker Server for the Troi plug-in to register.
|Set Variable [ $AppVersion; Value: Get(ApplicationVersion) ]
If [ LeftWords( $AppVersion ; 1) ="Server" or LeftWords( $AppVersion ; 1) ="Web" ]
#We are running on FileMaker Server as server-side script or in the Web engine.
#ServerWeb registration is x-platform so only one registration is needed.
Set Variable [ $errorCode; Value:TrFile_Version( "<your ServerWeb registration here>" ) ]
#your FileMaker client registration steps here
The plug-in should be registered now.
TIP You don't need to restart FileMaker Server for the Troi plug-in to register.
If you use the built-in registration, the plug-in only remains registered while running in the FileMaker Server application. If you stop FileMaker Server, the registration information is removed. So you need to run the registration script every time you start FileMaker Server.
Now that the plug-ins are installed you should inspect your scripts and make sure they work as expected. If you have scripts where you use user-input, rewrite them so they also work on FileMaker Server. For this you can use the Get(ApplicationVersion) function in an If statement to branch to different script steps.
We hope this document helps to get you started using Troi Plug-ins on FileMaker Server. If you have any suggestions or remarks please let us know.
This page and Troi File Plug-in: ©2015 Troi Automatisering. All rights reserved.