Plugins 101
Table of Contents:
Plugins 101
Who is this for?
This is a guide is for FileMaker users and developers who are new to using plug-ins with FileMaker Pro and FileMaker Server. It explains concepts that are applicable to all 360Works plug-ins, and to many FileMaker plug-ins in general
What is a plug-in?
A plug-in is a file that can be installed to add new functionality to FileMaker. Plug-ins do not stand alone, and are instead only used to extend FileMaker's capabilities. A plug-in's functionality can range from improving FileMaker's ability to send emails to allowing FileMaker to run custom Groovy code at will. By allowing developers to expand the functionality of FileMaker without changing its core structure, plug-ins ensure that FileMaker maintains its broad user group while meeting very specific needs.
Without plug-ins, users would need to purchase additional stand-alone software that may not interface with existing FileMaker databases. By utilizing FileMaker's standard functions to perform non-standard tasks, plug-ins help ensure that your information is accessible, organized, and integrated.
Requirements
360Works plug-ins are currently supported in FileMaker 16 or later. Generally, as long as your system meets the recommended minimum requirements set by FileMaker then you meet the requirements to use 360Works Plugins.
Installation
Manual vs Script installation
Plugin installation can be done via script using the Install Plug-In File script step or by manually placing the plugin file into the installation location. We highly recommend that you install plugins using the Install Plug-In File script step but sometimes a manual installation is necessary.
For automated installation, you can optionally use our Auto-Update file to install and/or update your plugins.
Where to Install the Plug-in
FileMaker Pro: If you are running FileMaker Pro, then you will need to install the plugin for FileMaker Pro. If your database is hosted on FileMaker Server AND uses the Perform Script on Server to run scripts on the server that call plugin functions, then you will also need to install the plugin on the server.
FileMaker Server: If your database utilizes the Perform Script on Server script step to run scripts that call plugin functions (from FileMaker Pro, Data API, or Web Direct), or if you intend to use the plugin in a scheduled script, you will need to install the plugin for FileMaker Server
Web Direct: If users will be accessing the database through Web Direct then the plugin needs to be installed into the FileMaker Server Web Publishing Engine.
Data API: If you are going to be calling scripts with plug-in functions via the Data API then you will need to install into the Data API location.
FileMaker Go: 360Works plugins cannot be installed on iOS, but you can install them on FileMaker Server and then use Perform Script on Server to run them.
FileMaker Pro installation
Installation via Script
Create a new file with a container on a layout. Insert the appropriate plug-in for your operating system into the container field, and write a script(installation script) that calls the script step Install Plug-In File. Running this script will install the plugin.
Manual installation
Step 1: Unzip the downloaded .zip file. Leave this Finder(Mac) or File Explorer(Windows) window open
Step 2: Open FileMaker Pro
Step 3: Open FileMaker Pro Preferences.
On Mac this is under the FileMaker Pro menu.
On Windows this is in the Edit Menu:
Step 4: In the Preferences window, click on the plugin tab and then click on the button that says "Reveal plug-in folder". This will open another Finder(Mac) or File Explorer(Windows) to the FileMaker Pro installation location:
Step 5: On the window from Step 1 navigate into the folder that corresponds with your operating system. If you are using a Mac go into the "MAC" folder, a Windows go into the "WIN" folder.
For Mac: Copy/paste or drag/drop the .fmplugin file that is inside the MAC folder into the folder that was opened in Step 4
For Windows: There will be two files inside the WIN folder. The file that has the extension of .fmx is 32-bit. The file that has the extension .fmx64 is 64-bit. If you do not see the file extensions, right-click on the file and select Properties. The extension will be shown next to "Type of File". Once you have determined the correct file copy/paste or drag/drop it into the folder that was opened in Step 4.
Step 6 Quit and restart FileMaker Pro
Step 7 Check to make sure that the plugin is installed and enabled. You can do so by opening FileMaker Preferences and going to the plugins tab and making sure the plugin is listed there and is checked to indicate it is enabled. See the screenshot in step 3 that shows 360Works plugins installed with a check mark to show they are enabled. If the plugin is not listed there, then it is not installed correctly. If it is listed there and not checked as enabled, try to check it to enable it. If you get an error when trying to enable it, please contact us by sending an email to support@360works.com.
FileMaker Server and WebDirect/Web Publishing Installation
Installation for FileMaker Server and WebDirect/Web Publishing can also be done via script or manually. Make sure you have enabled plugin use of plugins for the context you want to use them in the admin console.
Installation via Script
Make sure you have turned on the Install Plug-In File Script Step for Server plugins and/or Web Publishing plugins. Create a new file with a container on a layout. Insert the appropriate plug-in for your operating system into a container field, and write a script(installation script) that calls the script step Install Plug-In File and reference the container field.
If you want to install for FileMaker Server, create another script that calls the installation script via the Perform Script on Server (PSOS) script step. For Web Direct, put a button on the layout that calls the installation script. Host this file on FileMaker Server and then access it through FileMaker Pro or through Web Direct, whichever is appropriate for your installation. For FMS, call the PSOS script. For Web Direct, click the button that runs the installation script.
Manual installation
Place the appropriate plugin file for your operating system in the corresponding installation location. This process varies slightly depending on OS. Please see the Plug-in Installation Locations page for default installation locations.
If using Windows, make sure you are installing the 64-bit plugin (file extension is .fmx64). With a manual installation you will need to stop the FileMaker Scripting Engine/Web Publishing Engine using the fmsadmin utility in PowerShell/CMD before installing/updating:
To stop the FileMaker Scripting Engine:
fmsadmin stop fmse -y
To stop the Web Publishing Engine:
fmsadmin stop wpe -y
Once the FMSE/WPE has stopped, put the plugin file into the corresponding installation location and then start the FMSE/WPE.
To start the FileMaker Scripting Engine:
fmsadmin start fmse -y
To start the Web Publishing Engine:
fmsadmin start wpe -y
If you already have the plugin installed and are updating to a new version, make sure to replace the existing plugin file with the new one.
You can confirm that the plugin is installed and enabled in the FileMaker Server Admin console
Web Publishing Engine plugins do not show up in the admin console. You can confirm that they are installed by calling the Get( InstalledFMPlugins ) script step from a Web Direct context.
If you do not see the plugin listed there, try restarting the Admin server with the command
fmsadmin restart adminserver -y
Demo Mode and Registration
Demo Mode
All 360Works plugins will automatically enter demo mode at initialization. In Demo Mode, plugins will operate fully featured for 2 hours starting when the plugin first enables. This is when you start FileMaker Pro or once the plugin is enabled in the FileMaker Scripting Engine (FMSE) or Web Publishing Engine (WPE). Once 2 hours has elapsed all plugin functions will return a "Demo Mode Expired!" error. At this point you will need to restart FileMaker Pro (or the FMSE, WPE) in order to reset the timer. Once you have purchased a license, registering the plugin will take it out of Demo Mode.
Registration
Registering in FileMaker Pro
To register the plug-in in FileMaker Pro, open the Settings menu and click on the Plug-in tab
Select the plugin you want to register in the list and then click Configure. This will open registration window
Enter the license information into the respective fields and click Register to register the plugin
Since there is no mechanism to store registration information server side, registration needs to be done via the registration function built into the plugin. To register you must call this function at the beginning of
any script that is going to call plugin functions. This applies to scripts run via Perform Script on Server (PSOS), in Web Direct, and the Data API.
Creating Scripts, Calling Functions, and Setting Variables
Scripts are commands that cause FileMaker to perform specific tasks. They can be simple or complex, made of variable script steps. Script steps are generally composed of a Function, which defines the action that the script performs, and Variables, which define the parameters of the action. As plug-ins are used within FileMaker, you can use scripts to control the actions of plugins.
To create a script, open the script manager from the menu bar of your FileMaker database. This opens the script manager, where you can create new scripts or edit existing ones. To create a script, click the "+" in the upper left corner. To edit an existing script, click on it in the list of scripts on the left and then start editing it. To add a script step to the script, double click it, and it will add the step to your script. You can also just start typing the name of the script step or use its type-ahead designation.
Available script steps for plugins are listed on the right of the script workspace ( highlighted in red in the image below). You can also call plugin functions within a calculation such as the value of a Set Variable script step. Either option is completely viable, but it will be up to you to decide when either option is appropriate. To further define the parameters of the script step, click the options button next to the script step.
This will open a drop-down menu where you can specify the value of the parameters as well as a few other options ( see image below).
It is a common mistake to think that installing a plugin in FileMaker Server will give you access to the plugin's functions in the FileMaker Pro script workspace in a hosted solution. This is not the case. In order to write scripts that will be executed server side, you will need to install the plugin for FileMaker Pro. It can be removed once the scripts have been written. It is also a common mistake to think that when installing the plugin on FMS, that any script call made from a hosted solution will be executed with the plugin installed on FMS. This is not the case unless your script is being called using the Perform Script on Server script step.
Any other script call made from FileMaker Pro in any solution, hosted or not, will execute on the local machine and will require the plugin to be installed there.
Error Handling/Reporting
Handling errors when calling functions as script steps
When calling plugin functions as script steps, you will handle errors in the same manner you would any other FileMaker script step.
Please see the FileMaker documentation for how to handle errors appropriately. Generally, if there is an error, our plugins will return an error code of 1552 when Get( LastError ) is called.
However, some plugin functions will return different error codes. If a function can return an error code other than a 1552, it will be documented with the description of the function below.
In addition to the error code, you can also get the description of the error by calling Get( LastExternalErrorDetail )
Handling errors when calling functions in a calculation
When calling plugin functions in a calculation all functions will return ERROR if an error has occurred. In order to capture errors, use the lastError function built into the plugin like so:
Set Variable [ $result; Value: MyPluginFunction("x" ; "y" ; "z") ]
If [ $result = "ERROR" ]
Show Custom Dialog [ "Error occurred: " & lastErrorFunctionName ]
Exit Script
Else
do more stuff here ...
End If