logo: Troi Activator Plug-in for FileMaker

Troi Activator Plug-in 4.5
for FileMaker Pro 16
USER GUIDE

September 2017







logo: Troi Plug-ins for FileMaker

Troi
Boliviastraat 11
2408 MX Alphen aan den Rijn
The Netherlands

You can visit the Troi web site at: www.troi.com

Troi Activator Plug-in is copyright 1998-2017 of Troi Automatisering. All rights reserved.








Table of Contents


Installing plug-ins

Starting with FileMaker Pro 12 a plug-in can be installed directly from a container field. Installation is therefore very easy: just open the "All Activator Examples.fmp12" example file and the startup script will install the plug-in for you. See also the EasyInstallTroiPlugins.fmp12 example file which contains the actual plug-in and install script.

TIP You can check which plug-ins you have loaded by going to the plug-in preferences: choose Preferences from the Edit menu, and then choose Plug-ins.

You can now open the file "All Activator Examples.fmp12" to see how to use the plug-in's functions. There is also a function and script step reference available.


If you have problems

This user guide tries to give you all the information necessary to use this plug-in. So if you have a problem please read this user guide first. You can also visit our support web page:

            www.troi.com/support

This page contains FAQ's (Frequently Asked Questions), help on registration and much more. If that doesn't help you can get free support by email. Send your questions to support@troi.com with a full explanation of the problem. Also give as much relevant information (version of the plug-in, which platform, version of the operating system, version of FileMaker Pro) as possible. Note that due to spam we have to filter incoming email. It might happen that non-spam email is filtered out too. If you have sent an email and you don't get an answer, try to send another email, slightly differently formulated and include the word "FileMaker" in the body text.

If you find any mistakes in this manual or have a suggestion please let us know. We appreciate your feedback!

TIP You can get more information on returned error codes from the OSErrrs database on our web site. This free FileMaker database lists all error codes for Windows and Mac OS!


What can this plug-in do?

Troi Activator Plug-in is a very powerful tool for triggering scripts in your FileMaker Pro databases. All from within FileMaker you can:

  • trigger a script on a specified date and time
  • schedule events which trigger any script you want
  • validate fields with a script
  • notify a different user on a different computer of changes with the click of a button
  • be an image upload server (Mac OS only)
and more...

Software requirements

System requirements for Mac OS

Mac OS X 10.7 (Lion), OS X 10.8 (Mountain Lion), OS X 10.9 (Mavericks), OS X 10.10 (Yosemite), OS X 10.11 (El Capitan), macOS Sierra (OS X 10.12).

NOTE Troi Activator Plug-in 4.5 will probably run on Mac OS X 10.6.8 (Snow Leopard), but we have not tested this and no longer provide support for this.

System requirements for Windows

Windows 7 on Intel-compatible computer 1 GHz or faster
Windows 8, Windows 8.1
Windows 10

FileMaker Pro requirements

FileMaker Pro 12 or FileMaker Pro Advanced 12 or higher.
FileMaker Pro 13 or FileMaker Pro Advanced 13 or higher.
FileMaker Pro 14 or FileMaker Pro Advanced 14 or higher.
FileMaker Pro 15 or FileMaker Pro Advanced 15 or higher.
FileMaker Pro 16 or FileMaker Pro Advanced 16 or higher.

FileMaker Server requirements

FileMaker Server 12 or FileMaker Server Advanced 12.
FileMaker Server 13 or FileMaker Server Advanced 13.
FileMaker Server 14 or FileMaker Server Advanced 14
FileMaker Server 15 or FileMaker Server Advanced 15.
FileMaker Server 16 or FileMaker Server Advanced 16.

You can use FileMaker Server to serve databases that use functions of Troi Activator Plug-in (client-side): you need to have the plug-in installed at the clients that use these functions.

Troi Activator Plug-in can also be used by FileMaker Server as a server-side plug-in or as a plug-in used by the web publishing engine. To use Troi plug-ins as a server-side or web-side plug-in you need to purchase a special Server/Web license. More information can be found in the download or on our web site.


Getting started

Using external functions

Troi Activator Plug-in adds new functions to the standard functions that are available in FileMaker Pro. The functions added by a plug-in are called external functions. You can see those extra functions for all plug-ins at the top right of the Specify Calculation box:

External functions in Specify Calculation box

You use special syntax with external functions: FunctionName ( parameter1 ; parameter 2 ) where FunctionName is the name of an external function. A function can have zero or more parameters. Each parameter is separated by a semi-colon. Plug-ins don't work directly after installation. To access a plug-in's function, you need to add the calls to the function in a calculation, for example in a text calculation in Define Fields or in a script in Script Workspace (formaly called ScriptMaker).

Where to add the external functions?

Most of the external functions for this plug-in are intended to be used in a Set Field or Set Variable script step using a calculation. For most functions of this plug-in it makes no sense to add them to a define field calculation, as the functions will have side effects. The function "Actr_ScheduleEvent" of this plug-in can be used in a validation calculation when you are defining fields (choose Define from the File menu). See the Validation example file.

Using script steps

Starting with FileMaker 16 plug-ins can also add script steps. You can select these script steps in the script steps pane in Script Workspace, or you can begin typing the script step name, then choose the script step from the list that appears. The script steps expand the possible actions you can perform with FileMaker Pro.

Script steps in the script steps in Script Workspace screenshot of Troi File Plug-in script step

NOTE Only steps that perform an action have been added as a script step. Functions that have no side effect (like for example Actr_GetIPAddress) are only available as an external function.

Simple example

We start with a simple example to get you started. Say you have a database Remote.fmp12, with a global text field called gMyIPAddress, in which you are going to store the IP address of the computer. Create a new script called "Get my IP address". Then add the following script step to the script:

  Set Field [ gMyIPAddress ; Actr_GetIPAddress ( "" ) ]

This will put the IP address of your computer into field gMyIPAddres; for example:

  192.123.234.12

NOTE Function names, like Actr_GetIPAddress, are not case sensitive.

Please take a close look at the included example files, as they provide a great starting point. From there you can move on, using the functions of the plug-in as building blocks. Together they give you all the tools you need to trigger scripts from anywhere!

You can use globals or variables

With the release of FileMaker Pro 8 and later it is possible to use variables in calculations. Our example files in the download now both use global fields and variables to pass parameters and store the results of a plug-in function.

As this release of Troi Activator is intended for FileMaker Pro 12 and higher, we continue to move the scripts to use variables wherever possible. Note that not all examples are using variables yet.

All plug-in functions work with variables just fine. For example if you have this script step

  Set Field [ gMyIPAddress ; Actr_GetIPAddress ( "" ) ]

With variables you can alternatively use:

  Set Variable [ $MyIPAddress ; Actr_GetIPAddress ( "" ) ]

The main advantage of variables is that you don't need to define global fields that clutter your database definitions. The variables can stay local to the script.


Triggering scripts on other computers

First a few definitions: the receiver is the computer where a script must be triggered. The sender is the computer which sends a script trigger message to the receiver. Any computer can be a receiver and sender at the same time.

Think about security first!

Before implementing we advise you to think about the security issues, as triggering scripts is a very powerful feature. You do not want to have a "Delete All Records" script be triggered by an anonymous hacker. See below how you can limit security risks of remote triggering.

Start listening

To be able to trigger scripts on the receiver computer it must first start listening for trigger messages. If you don't want the Activator Plug-in to trigger scripts initiated by other computers you should not start listening. The plug-in will then ignore all remote trigger messages. In a script add the following script step:

  Set Field [ gErrorCode ; Actr_StartListener (
                                "-DefaultPortNumber" ; Get ( CurrentFileName ) ; "12345" ) ]

This will start the listening for messages on the default port (UDP port 54242). Only messages which have securityID 12345 are handled, other messages will be ignored. This makes listening for messages safer. No one can trigger a script on your computer, unless they know the securityID!

TIP For the securityID you can use anything you like. For example a large random number, a password or a combination of this. If you specify an empty securityID all trigger messages will be executed, even if the sender has included a non-empty securityID. See the example file "Remote" for a simple random number algorithm.

The receiver needs to tell other computers that it is listening for messages. A sender needs to know the IP address, the port number and the securityID (if used). A convenient way to distribute this information is via a shared FileMaker database, in which a receiver puts the needed information. See the example file "Remote" where this is implemented.

NOTE This is just a suggested implementation for getting this information to the sender. It is not necessary to have a shared database for remote triggering to work. You can implement this in a different way, for example by publishing it on the web or sending email. The information might even be always the same, so you don't need to communicate it.

TIP2 If the receiver is behind a firewall, the port on which the receiver is listening must be opened. If the receiver started listening on the default port this is UDP port 54242. See your system administrator for this.

Sending trigger messages

To send trigger scripts you only have to send the message to the receiver computer. We assume that in your FileMaker file "Remote.fmp12" the following fields are defined:

Field name Type Possible contents
Name Text Peter Falk
IP Address Text 192.1.123.24
SecurityID Text secretpassword
FileName Text Remote.fmp12
ScriptName Text TriggerScript1
gYourID Global, text 123
gYourText Global, text Please look at this record.
gErrorCode Global, text 0

In a script add the following script step:

  Set Field [ gErrorCode ; Actr_SendRemoteEvent ( "-PortNumber=51000" ; 
                     IP Address ; SecurityID ; FileName ;
                     ScriptName ; gYourID ; gYourText) ]

This will send the message to the receiver at the specified IP address and port 51000. The receiver must be listening on this port and also the securityID must be the same. You can use the global field gYourID and gYourText to send information to the receiver, for example a record ID and a message.


Function and script step reference

For a description of all External Functions and External Script Steps added by Troi Activator Plug-in please see the separate Reference.fmp12 file. For each function and script step you will find:

  • the correct syntax
  • the parameters/options to be used
  • the returned result
  • special considerations
  • an example usage

The same information is also available as online help on Troi's web site.

You can easily consult the online help directly from FileMaker, by clicking the Help button (the small question mark button) next to the function description in the functions pane or the script step description in the script steps pane.