360Works RemoteScripter 1.82 User Guide

RemoteScripter allows you to remotely trigger FileMaker scripts on another computer. It can be triggered either by RemoteScripter running on a different computer, or by an HTTP URL. This plugin can safely be triggered from within the Web Publishing Engine, which makes it an ideal way to trigger non-web-safe scripts on a separate script processing computer. For example, let's say that your WebDirect or IWP application needs to be able to generate downloadable PDF's. You would define a script called "Generate PDF" which is designed to be run on a computer running regular FileMaker Pro at IP address 10.0.0.25. It might looking something like this:

 Enter find mode
 Set field Customer::customer ID to Get(ScriptParameter)
 Perform find
 Save as PDF
 RemoteScripterSetResult("Success")
 

Now pick a random port number to run RemoteScripter on. We'll pick 4546, but it can be anything that does not conflict with another service running on the same port. You would have a startup script which calls:

RemoteScripterStart(4546, Get(FileName), "Generate PDF")

This tells RemoteScripter to trigger the Generate PDF script if it receives any requests on port 4546.

On the computer running WebDirect, you would have a button that the user clicks on to see the PDF. This button triggers a script which would look something like this:

 if( RemoteScripterTrigger("10.0.0.25", 4645, Customer::customer ID) = "Success" )
 	Go to Layout (Download PDF)
 else
 	Go to Layout (Show PDF generation error)
 end if
 

You could also trigger the PDF generation script directly from a user's browser, without going through the web server. Just have a URL that looks like this:

 <a href="10.0.0.25:4645?35">View customer record 35</a>
 

This will trigger RemoteScripter to run the script and return whatever is set with RemoteScripterSetResult().

You can use RemoteScripter to trigger scripts on your clients machines when they click links in a web viewer in your filemaker database. This allows you to design an interface in HTML, Java, Flash, or any language which can be displayed in your web viewer and then still trigger filemaker scripting. You can accomplish this by installing the Remote Scripter plugin on each of your client machines. You can then call the RemoteScripterStart function like in the example above (a startup script is a good place for this) and trigger the script using a link in your HTML to http://localhost:4645. The "localhost" url always points to the machine accessing it, so your users will trigger your script on their own machines when they click the link!

Error Handling/Reporting

When something unexpected happens, the plug-in will pop up a dialog showing what the error message is. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call RemoteScripterSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.

When you call this function, it is set for that plug-in for as long as FileMaker is running, so if you want to do all of your own error handling, you can just set it to true once in your startup script. However, we recommend only turning it on when your script is prepared to check for errors, and then turning it off after finishing that section.

Whether or not you suppress the error dialogs, a plugin function will return the word ERROR if something goes wrong. It's a good idea to put your plugin functions in an 'If' statement so that you don't execute a bunch of script steps after something has gone wrong. If you'd like for your script to get the error message, you can get that by calling the RemoteScripterLastError function.

Here is an example of basic error reporting:

Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ]
If [ $result = "ERROR" ]
    Exit Script[ "Error occurred: " & RemoteScripterLastError ]
Else
    ... do more stuff here ...
End If

Chaining Multiple Functions Together

Since the string "ERROR" evaluates to false when evaluated by FileMaker, and most plugin functions return a 1 when successful, you can chain multiple dependent plugin operations together using the "and" operator. However, in this case the result will be a 1 or a 0, not "ERROR". For example:

// chain multiple calls together
// if any of the functions fail, the calculation will
// short-circuit with a result of false,
// and none of the subsequent function calls will be evaluated.
Set Variable [ $success =
    FirstPluginFunction("x") and
    SecondPluginFunction("y") and
    ThirdPluginFunction("z")
]
If [not $success]
    Show Custom Dialog [ "An error occurred: " & RemoteScripterLastError ]
End If

Note: the above only works for plugin functions which return 1 on success! Check the documentation for each function used in this manner.

Additional Error Checking - Plugin not installed

If a plugin is not installed correctly, calls to a plugin function will return "?". As part of your startup script, you should check for this occurrence and display a warning accordingly that the plugin needs to be installed. Note: when treated as a boolean true/false value, FileMaker will treat ? as true.

Installation

Requirements

FileMaker version 11 or higher.

Java Virtual Machine (JVM) version 1.6 or later (32-bit). If you are running a JVM earlier than 1.6, you should upgrade. Download a JVM from http://www.java.com/en/download/. Apple has a 32-bit version of Java 1.6 here http://support.apple.com/kb/DL1572. 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.6 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.

If the plugin does not load correctly, double-check that you meet the system requirements.

Install steps for Instant Web Publishing

You do not need to do this step unless you plan on using the plugin with Instant 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 Server or FileMaker Server Advanced, drag the plugin from the MAC (.fmplugin file) or WIN (.fmx file) 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.

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 Custom Web Publishing

If you are using FileMaker Server 12.0v1 or earlier, you can follow the same procedure as detailed above for custom web publishing. However, in FileMaker Server 12.0v2 and later, the custom web publishing now runs as a 64-bit application, and requires a slightly different location. You will need an Enterprise license to use this feature.

For Mac, the single plug-in file in the MAC directory contains both 32-bit and 64-bit versions. For Windows, look for the plug-in that has the extension .fmx64 and use it in exclusively in custom web publishing.

To install 64-bit plug-ins, install either the .fmx64 or the .fmplugin to the following directory:

FileMaker Server / Web Publishing / publishing-engine / cwpc / Plugins

If it does not exist, create the Plugin folder manually. Restart FileMaker Web Publishing, and then you can then test a script that contains a plug-in and see if it returns the correct values.

Please note that plug-ins do not work with the web publishing engine of the Mac version of FileMaker Server 8.0v4.

Install steps for server scheduled scripts

You do not need to do this step unless you plan on using the plugin with scheduled script triggering. You will need an Enterprise license to use this feature.

  1. Drag the plugin from the MAC (.fmplugin file) or WIN (.fmx file) folder into the FileMaker Server extensions folder. On Mac OS X, this is located at /Library/FileMaker Server/Database Server/Extensions folder. On Windows, this is at C:\Program Files\FileMaker\FileMaker Server\Database Server\Extensions.
  2. In the Server Admin application, restart FileMaker Server by stopping and starting it.
  3. Go to Configuration -> Database Server->Server Plug-ins and check the box that says 'Enable FileMaker Server to use plug-ins', and then check the 'enabled' box for this plugin. Click the 'save' button and wait a few seconds to make sure that the 'enabled' check box stays checked. If it does not, then there was an error loading the plugin and you should contact us for help troubleshooting. You should now be able to write schedules that trigger scripts which use the plugin.

Auto Update

360Works has created an AutoUpdate helper database which makes setting up Auto Update much easier. This file includes pre-configured plugin files which you can place on your server, and an auto-update script for each of our plugins which you can paste into your own solution.

You can get the AutoUpdate360Works file at fmp7://autoupdate.360works.com/AutoUpdate360Works or fmp://autoupdate12.360works.com/AutoUpdate360Works. Follow the instructions included in the file to either host your own Auto Update server or pull the files from ours.

Uninstalling the plugin

Uninstall the plugin by quitting FileMaker Pro or stopping FileMaker Server and removing the plugin file from your Extensions directory.

Demo mode and Registering the plugin

Plugins will run in demo mode until they are registered. While running in Demo mode, the product will run for 2 hours every time you launch FileMaker / FileMaker Server / FileMaker Web Publishing Engine. The 2 hour time limit will reset every time you relaunch FileMaker. There is no expiration date when Demo mode stops working. There are no feature differences between the Demo version and the licensed version.

Once you have purchased the plugin, you can register it with the license key. Once a valid license key is entered, the product will run for as long as FileMaker is running. 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.

Note that if you are running the plugin with FileMaker Server / FileMaker Web Publishing Engine, you must use the registration function to register the plugin, since there is no preferences dialog on 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

Function Detail

RemoteScripterBringFilemakerToFront

You may optionally call this function to bring Filemaker to the front and give it focus.

Returns: the location of the Filemaker executable called

RemoteScripterGetVersion

Returns the version number of the RemoteScripter plugin.

Returns: a text version number

RemoteScripterLastError

Returns detailed 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.

RemoteScripterLicenseInfo


RemoteScripterRegister ( licenseKey; companyName )

Registers the plugin.

Parameters:

RemoteScripterSetErrorCapture ( errorCapture )

Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call RemoteScripterSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.

Parameters:
errorCapture - set to true to suppress the default popups.

RemoteScripterSetResponseHeaders ( header1 = value1 {; header2 = value2 ; ... )

Allows the user to set the response headers and value pairs for a script by defining them in a string array.

Parameters:
headers - String Array that specifies the headers and value pairs in a string array
Returns: returns success value when the response header is set

RemoteScripterSetResponseHTTPcode ( HTTPcode )

Allows the user to set the response HTTP code for a script by defining them in an integer.

Parameters:
HTTPcode - integer that specifies the HTTP code that is to be set
Returns: success value when the the response code is set

RemoteScripterSetResult ( resultText )

You may optionally call this function with text to return as the result of triggered script. If you do not call it, it will return nothing. This is usually called near the end of the triggered script.

Parameters:

RemoteScripterStart ( portNumber; filename; scriptname {; variablePrefix=prefixString } )

Starts FileMaker listening on the specified port. When it gets any request on that port, it will trigger the script. If there are any parameters included in the HTTP request, it will pass these along as script parameters to FileMaker.

The following starts RemoteScripter listening on port 9876. Incoming requests will trigger the Remote Scripter Callback Script script, passing in any URL parameters as key=value pairs, with the keys containing a $foo_ prefix.

 RemoteScripterStart( 9876; Get(FileName); "Remote Scripter Callback Script" ; "variablePrefix=$foo_")
 

Handling URL parameter data in FileMaker

If the RemoteScripter URL contains key=value data pairs, RemoteScripter will convert the values to the format $key1="value1";$key2="value2". This makes it easy to pass the resulting string to the evaluate and let functions in FileMaker, which will populate local variables with the parameters from the URL.

For example, an HTML form with inputs for firstName, lastName, and notes will result in the following script parameter being passed in from RemoteScripter:

$notes="testing¶one¶two¶three";$firstName="Sam";$lastName="Barnum"
To convert this to actual variables in FileMaker, use the following functions:
 Evaluate ( "Let ( [" & Get(ScriptParameter) & "] ; true )" )
 
After calling this, you'll have local variables for $firstName, $lastName, and $notes.

Optional parameters

variablePrefix
The symbol to use before a variable name, default is "$", to facilitate the use of Let and Evaluate. For backwards compatibility with older versions of RemoteScripter (1.6 and earlier), pass an empty string for the variablePrefix. To prevent URL parameters from conflicting with variables, use a unique prefix for the variable name.

Parameters:
portNumber - the port number you wish to use for listening for events
filename - The name of the filemaker database containing the script.
scriptname - The name of the script which generates PDFs
options - The optional variablePrefix. Adds the specified string to the beginning of all converted URL parameter keys.
Returns: A status message showing whether the call was successful.

RemoteScripterStop ( portNumber )

Stops listening on this port.

Parameters:

RemoteScripterTrigger ( remoteAddress; portNumber {; parameterText ; timeout } )

Triggers a script on the remote computer running the RemoteScripter plugin. This waits until the remote computer finishes the script, and returns the result.

Parameters:
remoteAddress - the hostname or IP address of the machine whose FileMaker instance is running the plugin.
portNumber - this should be the same port number which was passed to {@link #RemoteScripterStart} by the remote computer.
paramText - Any arbitrary text to be included as a script parameter. It can be in the form of a single parameter (ie. "John"), or as multiple URL encoded parameters (ie. "firstname=John&lastname=Smith").
timeout - Number value in milliseconds.
Returns: the response from the remote computer is returned, if it calls {@link #RemoteScripterSetResult}.