ScriptMaster allows execution of Groovy code from within FileMaker.
Groovy is based on the Java programming language,
and for the most part you can pass straight Java code into the EvaluateGroovy function and it will work fine.
In addition, Groovy adds
new methods and syntactical improvements
(such as closures) to the standard java API, some of which can be big timesavers.
Consult the FileMaker demo file and the Groovy website to see some of the things you can accomplish with this language.
Variables
You can set variables prior to executing a script using the
SMSetVariable function. This is a handy way to get data from FileMaker into your custom scripts.
After a ScriptMaster script is evaluated using the EvaluateGroovy function, you can access any of the named variables which were set during execution using the SMGetVariable function.
Calculation and Scripting Engine access
In addition to setting variables prior to script execution, you can access the FileMaker calculation engine directly from within your Groovy script.
This is accomplished using the reserved fmpro object.
Every Groovy script which is executed will have an fmpro variable set to an instance of an FMPro object, which has two important methods:
- evaluate(fmcalculation)
- Evaluates the supplied FileMaker calculation text, returning the result as a String. The
fmcalculation parameter can be any valid FileMaker calculation string.
- performScript(fileName, scriptName [ , paramString ])
- Performs a FileMaker script in the current file, passing in the optional
paramString as a parameter. Note: fileName is required.
- merge(template)
- Processes some text with merge fields embedded, replacing the merge fields with their evaluated values. An example of a merge field is
<<table::field>>. If an error occurs during evaluation, the field is left as is.
Referencing External Jar Files
If there's some lib you need to use that isn't in the JDK, you can load it into the ScriptMaster classpath by using the
SMLoadJar function.
Pass in a container field containing a .jar file, or a URL pointing to a .jar file, and any scripts you execute will have access to the classes in that .jar. This means you can bundle in things like the
Jakarta Commons packages or JavaMail.
You could also easily write your own java code, package it as a .jar, and distribute it with your FileMaker solution! And since the .jar is stored in FileMaker, deploying new versions of the java code to the FileMaker clients is as easy as updating a single container field.
Example Usage
The following illustrates the various ways of working with the ScriptMaster plugin.
The Groovy Script
This instantiates a File object, queries it for the modification date, and returns its contents.
File f = new File(path);
modified = new Date(f.lastModified());
return f.newReader().getText();
Setting the "path" variable
The path argument is not set in the script, so we must provide that from FileMaker. We can set the path variable using the SMSetVariable function.
Likewise, the script returns the contents of the file, but we can also access the modification date using the SMGetVariable function.
Here is what the FileMaker script step might look like:
New Record/Request
Set Field [Demo::tmp; SMSetVariable( "path" ; "/path/to/my/file.txt" )]
Set Field [Demo::fileContents; EvaluateGroovy( Demo::script )]
Set Field [Demo::dateModified; SMGetVariable( "modified" )]
Installation
Requirements
FileMaker version 7 or higher.
Java Virtual Machine (JVM) version 1.4.2 or later. If you are running a JVM earlier than 1.4.2, you should upgrade.
Download a JVM from http://www.java.com/en/download/. If you are not sure what
version of Java you have installed, you can do 'java -version' on the command line in Windows or OS X.
Windows, or Mac OS X version 10.4 or higher.
Note to intel Mac users: running this plugin under Rosetta is not supported. Upgrade to FileMaker 8.5 to run our plugin in native Intel mode.
Install Steps for FileMaker Pro
Drag the plugin from the MAC or WIN folder into your FileMaker extensions, and restart FileMaker. You will need to enter your license key before you
can use it. After FileMaker starts up with the plugin installed, open FileMaker preferences, click on the Plug-ins tab,
select the plugin from the list, and click the Configure button. Enter your license key and company name in this dialog.
You will only need to do this once on a given machine. Alternately, you can use the registration function to register the plugin during a startup script.
This will also enable the plugin for use with Instant Web Publishing from the FileMaker Pro client software.
If the plugin does not load correctly, double-check that you meet the system requirements.
Install steps for FileMaker Web Publishing Engine / Instant Web Publishing
You do not need to do this step unless you plan on using the plugin with Instant Web Publishing or Custom Web Publishing with FileMaker Server Advanced.
You will need an Enterprise License to use this feature.
For installing into the Web Publishing Engine with FileMaker 9 Server or FileMaker Server Advanced, drag the plugin from the MAC or WIN folder
into the FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins folder. If there is no 'Plugins' folder inside the 'wpc' folder, then create it manually.
Restart FileMaker Web Publishing, and now the plugins should be ready to go.
Note that you must use the registration function to register the plugin, since there is no preferences dialog in the FileMaker Web Publishing Engine to enter
the license key and company name.
Note that due to a bug which we and other plugin vendors have reported to FileMaker, web plugins do not work in FileMaker Web Publishing Engine 8.0v4
on Mac OS X. You will need to use a later version, like 9, or an earlier version, like 8.0v3. The Windows FileMaker Server 8.0v4 does not have this bug, and will work correctly.
The easiest way to test whether the plugin is working is to have a calculation which calls the version function of the plugin, and display that on an
IWP layout. If it shows "?", then the plugin is not working. If it shows a number, then the plugin has been installed successfully.
Install steps for FileMaker Server 9
You do not need to do this step unless you plan on using the plugin with scheduled script triggering, a new feature in FileMaker Server 9.
You will need an Enterprise License to use this feature.
- Drag the plugin from the MAC or WIN folder into the
FileMaker Server/Database Server/Extensions folder (older versions of server use the path FileMaker Server/Extensions/Plugins).
- Verify that the permissions on the plugin give the fmserver / fmsadmin user all access
- Restart FileMaker Server. In the Server Admin application, go to
Configuration -> Database Server->Server Plug-ins.
- Check the box that says 'Enable FileMaker Server to use plug-ins', and then check the 'enabled' box for this plugin. You should now be able to write schedules that trigger scripts which use the plugin.
Note that you must use the registration function to register the plugin, since there is no preferences dialog in FileMaker Server to enter the license key and company name.
Feedback
We love to hear your suggestions for improving our products! If you are experiencing problems with this plugin, or have a feature request, or are happy with it, we'd appreciate hearing about it. Send us a message on our website, or email us!
Function Summary
- EvaluateGroovy ( groovyScript ) Evaluates a Groovy script in the foreground.
- SMGetVariable ( variableName ) Returns the value of a named variable which was set in the previously executed call to EvaluateGroovy.
- SMLastError Returns defailed information about the last error generated by this plugin.
- SMLastStackTrace Returns the stack trace of the last generated exception, if any.
- SMLoadJar ( externalJar ) Load a custom jar file for use in a custom script - This should be called before calling EvaluateGroovy.
- SMReset Resets any loaded jars and variables.
- SMSetVariable ( variableName ; value ) Evaluates a Groovy script without any user interface.
- SMVersion Returns the version number of the plugin.
Function Detail
EvaluateGroovy ( groovyScript )
Evaluates a Groovy script in the foreground. This is the primary method in ScriptMaster, which is responsible for executing the actual groovy script.
Call SMLastError to get a detailed description of the compilation error.
Call SMLastStackTrace to get a detailed description of any exception which occurs during script execution.
Parameters: groovyScript - a block of groovy/java code
Returns: the return value of the evaluated expression, or "ERROR" on failure.
SMGetVariable ( variableName )
Returns the value of a named variable which was set in the previously executed call to
EvaluateGroovy.
This can be very useful if your custom script needs to return multiple values, or for debugging purposes.
You can set any named variable within your script and retrieve the value of that value after evaluation has been completed.
Parameters: variableName - the name of the variable whose value is being gotten.
Returns: the value which was assigned to the named variable during the last script execution.
SMLastError
Returns defailed information about the last error generated by this plugin. If another plugin function returns the
text "ERROR", call this function to get a user-presentable description of what went wrong.
Returns: Error text, or null if there was no error.
SMLastStackTrace
Returns the stack trace of the last generated exception, if any.
This can be handy for troubleshooting cryptic error messages, when
SMLastError does not return enough info.
Returns: the stack trace of the last execution.
SMLoadJar ( externalJar )
Load a custom jar file for use in a custom script - This should be called before calling
EvaluateGroovy.
There are two methods of loading the driver .jar file: via URL, or via container field.
Loading a custom .jar file from a URL
You can load a jar file which is on the local file system or accessible on the network by passing a URL parameters as the
externalJar parameter.
The URL should be of the form
file:///path/to/my.jar or
http://example.org/path/to/my.jar.
Loading a custom .jar file from a container field
As an alternative to specifying a URL, you can embed any java .jar file into a container field in your FileMaker solution, and load the .jar from there.
Be sure that the driver is not stored as a reference, or the ScriptMaster plugin will not be able to read the information.
Caching Behavior
Jars are cached according to their name. If you register two files with the same name, the second will not be registered. The jar file will remain registered until you call
SMReset or quit FileMaker.
Parameters: externalJar - jar file location or data. This can be a URL pointing to a .jar file, or an actual container field containing a .jar file.
Returns: 1 if the jar was loaded successfully, or an error message if the jar could not be loaded.
SMReset
Resets any loaded jars and variables.
Returns: 1
SMSetVariable ( variableName ; value )
Evaluates a Groovy script without any user interface. This has no effect on Windows, but it will run faster in Mac OS X.
If your code does anything that triggers a user interface or runs on the Event Dispatch Thread (ie. a popup dialog), then it may freeze FileMaker.
/
private FMType EvaluateGroovyNoUI(String groovyScript) throws FeedbackException {
try {
errorVars = vars; //If call fails, we want to keep a reference to the last set of vars
lastScript = groovyScript; //Keep a reference to the failed script if there is an error
if (groovyScript == null) return null;
groovyScript = PluginUtils.convertLineBreaksFromFilemaker(groovyScript);
Object result = beanShellModel.evaluateGroovy(groovyScript, vars, fmpro, false );
if (result == null) return null;
// if result as String contains newline, return fmtext with converted line breaks
// otherwise, return the best value
errorVars = null; //Call worked, don't store reference to vars
lastScript = null;
if (result instanceof String) {
String resultWithLineBreaksConverted = PluginUtils.convertLineBreaksToFileMaker((String)result);
log.log(Level.FINE, "Returning TEXT {0}", resultWithLineBreaksConverted);
return new FMText(resultWithLineBreaksConverted);
} else {
return FMType.bestTypeForJavaObject(result);
}
} catch (CompilationFailedException e) {
throw new FeedbackException("Error during evaluation of " + groovyScript + ": " + e.toString()); // toString() has a better error message than getMessage() in this case
} finally {
vars = new LinkedHashMap();
}
}
public String SMSetVariablePrototype() { return "variableName ; value"; }
/**
Set a variable to be used in a ScriptMaster Evaluate function call. The next script evaluated will have access to this named variable.
Note that the value will always be converted to a String. If you need to use this as some other object type (date, etc) you are responsible for converting it within your script.
All variables are cleared after every call to an Evaluate function.
Setting a variable also clears the named variables from the previous script execution. If a script dealing with memory-intensive objects has been completed, it's a good idea to set a dummy variable to free up this memory.
Parameters: variableName - the name of the variable being setvalue - the value of the variable being set
Returns: null
SMVersion
Returns the version number of the plugin.
Returns: a string representation of the version number