FileMaker Server is the versatile database server of FileMaker Inc. FileMaker Server supports installing FileMaker plug-ins so they run as part of FileMaker Server. This will enable you to make use of the extra functionality plug-ins offer!
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 (Advanced) 10 and later 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.
Server-side plug-in
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 and later). 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.
About permissions
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 later
FileMaker Server 13 and later 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.
Plug-ins for macOS can be universal and the extension is always the same: fmplugin. A universal plug-in is a single plug-in that will run on a 32-bit process as well as on 64-bit process. You can not easily see if a macOS plug-in is 64-bit compatible. We have created a simple dropper app called “Troi Architecture Check” to determine for which architectures a plug-in is compiled. You can download the app here.
A plug-in running on FileMaker Server 13 or later and WebDirect does not run in the background. This means that a plug-in can not initiate something: for example our Troi Activator Plug-in can not receive messages from other computers.
How to install server-side plug-ins with FileMaker Server 13 and later
FileMaker Server 13 and later can 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: go to Database Server and then to the Server Plug-ins tab. Enable this checkbox:
Allow Install Plug-In File script step to update Server plug-ins
You can now install a plug-in with our EasyInstallTroiPlugins.fmp12 example file. On FileMaker Server create a new schedule to run a script (once). Run this script from EasyInstallTroiPlugins: “Install this Troi Plug-in on FileMaker Server 13 or later”.
You can also install plug-ins for WebDirect with the EasyInstallTroiPlugins.fmp12 example file. You need to open the file with WebDirect first and then click on the “Install This Plug-in” button.
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:
/Library/FileMaker Server/Database Server/Extensions
On Windows the path is:
C:\Program Files\FileMaker\FileMaker Server\Database Server\Extensions
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:
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:
/Library/FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins
On Windows the path is:
C:\Program Files\FileMaker\FileMaker Server\Web Publishing\publishing-engine\wpc\Plugins
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 Mac OS you can find the two logs here:
/Library/FileMaker Server/Logs/Troi Logs/Troi Plugin FMServer.log
/Library/FileMaker Server/Logs/Troi Logs/Troi Plugin Web Engine.log
On Windows you can find the logs here:
C:\Program Files\FileMaker\FileMaker Server\Logs\Troi Logs\Troi Plugin FMServer.log
C:\Program Files\FileMaker\FileMaker Server\Logs\Troi Logs\Troi Plugin Web Engine.log
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:
| error code | name | description |
| $$-4222 | kErrTryOutTimeOver | The plug-in stopped working as the two hour try-out time was reached. You can restart FileMaker Server to try-out this plug-in again. |
| $$-4251 | kErrNotAvailableOnServer | This function is not available on FileMaker server or not web compatible, as it involves graphic user interface. |
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.
TIP You can determine the registration status of a Troi Plug-in in the log file.
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)
Create the text file: “Troi Payment Certificate” and fill it with the received registration data and place it in these folder(s):
For server-side: /Library/FileMaker Server/Database Server/bin/
For web-side: /Library/FileMaker Server/Web Publishing/publishing-engine/wpc/
The total path for the file will be:
For server-side: /Library/FileMaker Server/Database Server/bin/Troi Payment Certificate
For web-side: /Library/FileMaker Server/Web Publishing/publishing-engine/wpc/Troi Payment Certificate
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):
For server-side: C:\Program Files\FileMaker\FileMaker Server\Database Server\
For web-side: C:\Program Files\FileMaker\FileMaker Server\Web Publishing\publishing-engine\wpc\
The total path for the file will be:
server-side: C:\Program Files\FileMaker\FileMaker Server\Database Server\TroiPay.txt
web-side: C:\Program Files\FileMaker\FileMaker Server\Web Publishing\publishing-engine\wpc\TroiPay.txt
You may need to restart FileMaker Server for the Troi plug-in to register.
Registering Troi Plug-ins with the built-in registration function
You can also register a Troi Plug-in with the built-in registration function. This has the advantage of not requiring an external text file.
How does built-in registration work?
You can register this plug-in from a FileMaker database file by calling the plug-in’s “Version” function with the registration string as a parameter. Your solution has to call this function before you use any of the plug-in functions. The best way to do this is to create a ScriptMaker script which is called before the first time the plug-in is used.
Registration script
Below is a example script that shows how to register a Troi Plug-in, in this case Troi File Plug-in. See also the RegiFunc file for an example on this process.
Create a script to be called before you use the functions of the Troi Plug-in, and add the following steps:
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>" ) ]
Else
#your FileMaker client registration steps here
End If
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.
Test your plug-in function calls
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 helps to get you started using Troi Plug-ins on FileMaker Server. If you have any suggestions or remarks please let us know.
