360Works WebAssistant User Guide

WebAssistant allows you to submit forms from FileMaker, and to get the contents of any URL as text or a container.

Getting URL Contents

In its simplest form, you can use the WAGetURL function to get the contents of a URL. If the mime-type of the URL is text, the raw text of the webpage or file is returned. Otherwise, a container is returned containing the image or other data located at the URL.

Submitting Forms

The WebAssistant can simulate a browser submitting a web form. For each "field" you wish to send to a form, call the WASetInputValue function. Note that the paramName corresponds to the name of an input in the HTML form, which may differ from the label for the field as it appears on-screen. The paramName should match the name attribute on the <input type="text" name="my_input"> input element in the HTML source code.

In addition to field inputs, you can specify files to upload to a form using the WAUploadFileAtURL function. Again, the inputName should match the name attribute on the <input type="file" name="my_upload"> in the HTML source code.

You can specify multiple parameters or file uploads. They will all be sent the next time the WAGetURL function is called.

For more advanced users, there is the option of setting the content of the request manually, using the WASetRawPostData function. This will be sent as-is in the request, which is useful if (for example) the POST data should contain an XML document instead of key/value pairs. You are responsible for encoding this information correctly, as it will be sent as-is to the URL.

Example Usage

To add a user to a web-based signup form, you might use something like the following: 
Let ( setup = WAReset &
    WASetInputValue( "first_name" ; "Sam" ) &
    WASetInputValue( "last_name" ; "Barnum" ) &
    WASetInputValue( "email" ; "sam@example.com" )
;
    WAGetURL( "http://example.com/test/signup.php" )
)

To get an image from a password-protected website, just use the following calculation: 

Let ( setup = WAReset ;
    WAGetURL( "http://example.com/images/logo.jpg" ; "username=bob123", "password=secretpass" ; "type=container" )
)

To upload files to a web form, pass container data to the WASetInputValue function, or a URL to the WAUploadFileAtURL function: 

Let ( setup = WAReset ;
    WASetInputValue( "upload1" ; Products::picture_container ) &
    WAUploadFileAtURL( "upload2" ; "file:///Users/sam/Pictures/header.jpg" )
;
    WAGetURL( "http://example.com/upload.php" )
)

Proxy Support

If you are behind a proxy server, you will need to tell the WebAssistant plugin information about the proxy host, as follows: 
WAConfigure("proxyHost", settings::proxyHost) and
WAConfigure("proxyPort", settings::proxyPort)
Do this in your startup script, and any further connections will go through your proxy host.

Error Handling/Reporting

When something unexpected happens, a plugin function returns a result of "ERROR". This makes it easy to check for errors. If a plugin function returns "ERROR", call the WALastError function to get a detailed description of what went wrong.

Here is an example of basic error reporting:

Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ]
If [ $result = "ERROR" ]
    Show Custom Dialog [ "An error occurred: " & WALastError ]
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: " & WALastError ]
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 7 or higher.

Java Virtual Machine (JVM) version 1.5 or later. If you are running a JVM earlier than 1.5, 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.

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 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 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 or later

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.

  1. Drag the plugin from the MAC or WIN 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 stoppping 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. 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

WAConfigure ( optionName ; value )

Set a WebAssistant-related configuration optionName. Valid options are:
easySSL
A 1 or 0 indicating whether or not to use lax SSL certificate checking. This is useful for testing using self-signed certificates, or if you are getting certificate-related errors while connecting to https urls.
connectionTimeout
The timeout in milliseconds until a connection is etablished. A value of zero means the timeout is not used. The default value is zero.
socketTimeout
The default socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data. A timeout value of zero (the default value) is interpreted as an infinite timeout.
userAgent
Defines the content of the User-Agent header used by HTTP methods.
proxyHost
The proxy server host address or hostname.
proxyPort
The proxy server port number, defaults to 8080.
proxyUsername
The proxy server username.
proxyPassword
The proxy server password.

Parameters:
optionName - the optionName to set.
value - the value of the optionName.
Returns: 1 if an optionName is successfully set, or ERROR if an error occurs.

WAGetResponseHeader ( headerName )

After executing a request with the WAGetURL method, you can use this function to examine the HTTP headers in the response. This can be useful for seeing cookie data which the server is setting. You can use the WAGetResponseHeaders function to get a list of all headers.

Parameters:
headerName - the name of the HTTP header to fetch
Returns: the value of the first HTTP header named name, or null if no such header was found.

WAGetResponseHeaders

This gets a return-separated list of all HTTP header names from the last response.

Returns: all headers from the last request

WAGetURL ( url { ; key1=value1 ; key2=value2 ; ... )

Get the contents of a URL, as either TEXT or a CONTAINER object. If there are any input values or file uploads set, they are sent as part of a POST request. Otherwise, a GET request is used to get the contents of the URL.

You can also use this to get the contents of files on your local machine, using the following syntax: file:///path/to/file.txt.

If the content type of the returned data is text, this function returns the text. Otherwise, a container is returned. Alternatley, you can specify a type to return the URL content as, using the type parameter (see Optional Parameters below).

Authentication

You can optionally supply a username and password, for accessing password-protected content. This must be passed in with each request, as the values are cleared out after doing the request.

Optional Parameters

The following optional parameters are supported:
username
The username to be used for authentication
password
The password to be used for authentication
type
"text" to fetch the result as a text object, "container" to fetch the result as a container. If no type is specified, the content-type of the URL contents are examined to automatically determine the best type (images, etc. will be returned as containers, text & html will be returned as text)
encoding
The default is application/x-www-form-urlencoded. You can also specify multipart/form-data to force that encoding instead.

Example Usage

To fetch data from a password-protected XML web service as text, you could use the following calcuation: 
Set Variable [ $xml = WAGetURL(
    "http://myservice.com" ;
    "username=bob" ;
    "password=secret" ;
    "type=text" ) ]

Parameters:
url - the location of the file to get.
optionalParameters - optional parameters
Returns: The contents of the URL, as text or a container.

WALastError

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.

WALicenseInfo

Retrieve information about the WebAssistant plugin licensing and version.

WALoadForm ( html { ; whichForm } )

Use an HTML form as a starting point for form values. This can be useful if you're simulating a form submission from a page which has many hidden or pre-populated fields. This can often happen on multi-step form submissions.

Calling this function will scan the HTML parameter text for the form identified by the whichForm parameter. For every input element in the specified form, WASetInputValue will be called with the corresponding inputName and value.

Parameters:
html - block of HTML code containing one or more <form>s
whichForm - the optional id, name, or index of the form to use. If omitted, the first <form> will be used.
Returns: 1 on success, ERROR on failure.

WARegister ( licenseKey ; registeredTo )

Registers the Plugin.

Parameters:
licenseKey - a valid license key string, or the literal string "DEMO" to run in demo mode.
registeredTo - the company name for the license key used.
Returns: 1 on success, or "ERROR" on failure.

WAReset

Clears all request parameters, file uploads, and post data. This should be called before constructing a new request or getting a URL, in case there are some parameters lingering from a previous call that did not complete.

Returns: 1

WASetCharacterSet ( charset )

Set the character encoding used for sending form values and for decoding fetched URL contents into text.

Parameters:
charset - a character set name, for example US-ASCII, ISO-8859-1, UTF-8, UTF-16.
Returns: 1 on success, or "ERROR" on failure (if an unsupported character set is passed)

WASetInputValue ( inputName ; value )

Sets a parameter to pass in the POST argument during the next call to WAGetURL. If you want to simulate submitting an email signup form, you might call this with the values: 
WASetInputValue( "email" ; Contacts::emailAddress )

To send a container field as an attachment, pass the container field as the value. 

WASetInputValue( "photo" ; Contacts::portrait )

If you want to upload the contents of a local file or URL instead of a container, use the WAUploadFileAtURL function instead.

You can call this function multiple times before sending a form. If called twice with the same inputName, this will _not_ overwrite the previous value, but will send both values.

Parameters:
inputName - the unencoded name of the form input
value - the unencoded value text, or a container to send as an upload.
Returns: 1 on success, or "ERROR" on failure.

WASetRawPostData ( POST )

Set raw POST data to send during the next call to WAGetURL. If used in conjunction with WASetInputValue, any parameters set in that method will be passed as GET arguments instead of POST arguments.

You cannot combine this with calls to WAUploadFileAtURL in the same request.

You can call this function multiple times before sending a form.

Parameters:
POST - raw encoded POST data to send in the next request.
Returns: 1 on success, or "ERROR" on failure.

WASetRequestHeader ( headerName ; value )

Set manual HTTP headers to be sent with the request. The most common case you would use this would be to set cookies in the request.

Setting Cookies

To send cookies along with your request, call with with "cookie" as the headerName, and the cookie data as the value. 
WASetRequestHeader("Cookie", "sessionID=123456789;style=basic")

Other Uses

You can also use this to set the Content-Type of your request, or to pass in any other arbitrary headers you wish.

Parameters:
headerName - the name of the HTTP header to set
value - the value of the HTTP header
Returns: 1 on success

WAStripTags ( html )

Strip any HTML tags from a block of text.

Parameters:
html - some HTML.
Returns: the input HTML with all tags removed.

WAUploadFileAtURL ( inputName ; url )

Upload a file during the next call to WAGetURL. If one or more files are specified to upload, the data is sent as multipart/form-data.

If you want to upload the contents of a container field instead of a URL, use the WASetInputValue function instead, passing the container as the value parameter.

Parameters:
inputName - the input name to associate with this file.
url - URL pointing to a file to upload. This can be a local file (file:///path/to/file) as well as a remote URL (http://example.com/logo.jpg).
Returns: 1 on success, or "ERROR" on failure.

WAVersion

Returns the version number of the WebAssistant plugin.

Returns: a text version number