360Works FTPeek User Guide

The 360Works FTPeek plugin enables SFTP (encrypted with SSH) / FTP / FTPS (encrypted with SSL) functionality in FileMaker, including:

You can select what type of FTP protocol you want to use by using one of the FTPeek_Connect methods. For regular unencrypted FTP, use FTPeek_ConnectFTP. You can also do SFTP with FTPeek_ConnectSFTP or FTPS with FTPeek_ConnectFTPS.

Once you're connected, the plugin functions to upload, download, etc. are the same for all three protocols.

More information about the FTP protocol, as well as the secure variations (SFTP and FTPS) can be found at this Wikipedia article.

Example Usage

This shows an example of connecting to a secure SFTP server, getting a list of files, and downloading one of them.

Step #1: Get public key of the server. This returns text that can be stored in FileMaker.

Set Field[ example::publicKey; FTPeek_GetPublicKey( "host.address.com" ) ]
If[ example::publicKey = "ERROR" ] ...show error using FTPeek_LastError...

Step #2: Connect to the server. Requires public key and client authentication.

if[ FTPeek_ConnectSFTP( "host.address.com" ; example::publicKey ; "username" ; 
     "password" ) = "ERROR" ] ...Handle error...

Step #3: Get a list of files in a directory on the server

Set Field[ example::filesList; FTPeek_GetFileList( "/Users/ftpeek/" ) ]
if[ example::filesList = "ERROR" ] ...show error using FTPeek_LastError...

Step #4: Download the first file in the list to a temp directory and name it newFileName.

If[ FTPeek_DownloadFile( "/tmp/" ; GetValue( example::filesList; 1 ); 
     "newFileName" ) = "ERROR" ] ...Handle error...

Step #5: Disconnect

If[ FTPeek_Disconnect = "ERROR" ]
     ...Display error message to user, but we don't need to do anything else...

Relative vs. Absolute Paths

All functions support referencing remote files and directories as relative or absolute paths.

A relative path references files and directories starting from the current working directory. For example, if we are in the "/uploaded/FTPeek/" directory on the remote server, changing into "backup" would navigate into the "/uploaded/FTPeek/backup/" directory.

On the other hand, an absolute path references files and directories starting from the root directory of the server. If we're in the same "/uploaded/FTPeek/" directory and try to change into "/temp", we would actually end up in "/temp/" instead of "/uploaded/FTPeek/temp/", since we start at the root directory instead of the current working directory.

As seen in the examples, an absolute path starts with a slash ("/"), while a relative one does not. Either can be passed in to FTPeek_ChangeDir, FTPeek_Rename, FTPeek_UploadFile, and other functions to reference relative or absolute paths.

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.

  1. Drag the plugin from the MAC or WIN folder into the FileMaker Server/Database Server/Extensions folder (Server 8 and older versions of server use the path FileMaker Server/Extensions/Plugins).
  2. Restart FileMaker Server. In the Server Admin application, go to Configuration -> Database Server->Server Plug-ins.
  3. 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

Function Detail

FTPeek_ChangeDir ( remoteDir )

Changes the working directory to a specified directory. The remoteDir path can be relative or absolute. Please see the note on relative and absolute paths at the top of the page for more information.

Parameters:
remoteDir - the directory to navigate into
Returns: 1 on success, ERROR on failure

FTPeek_ChangeDirRoot

Changes the working directory to the root directory of the server.

Returns: 1 on success, ERROR on failure

FTPeek_ChangeDirUp

Changes the working directory to the parent of the current directory.

Returns: 1 on success, ERROR on failure

FTPeek_ConnectFTP ( host ; username ; password )

Connects to an FTP (File Transfer Protocol) server with the specified address, username, and password. You must call one of the connect methods (either FTP, SFTP, or FTPS) before you can call any other FTP functions.
If multiple connect functions are called, the last connection remains as the active working connection. While previous connections will time-out and eventually disconnect, a server may allow a limited number of concurrent connections per account, limiting new connections until the old ones are closed. It is therefore highly recommended to close any active connection before opening a new one. "ftp.mysite.com"; if need to connect to a non-standard port number, concatenate the port number to the host name like "ftp.mysite.com:21"

Parameters:
host - address of the server; can be numeric IP address like "127.0.0.1" or a named one like
username - the client username
password - the client authentication password
Returns: 1 on success, ERROR on failure

FTPeek_ConnectFTPS ( host ; username ; password )

Connects to an FTPS (FTP/SSL) server with the specified address, username, and password. You must call one of the connect methods (either FTP, SFTP, or FTPS) before you can call any other FTP functions.
If multiple connect functions are called, the last connection remains as the active working connection. While previous connections will time-out and eventually disconnect, a server may allow a limited number of concurrent connections per account, limiting new connections until the old ones are closed. It is therefore highly recommended to close any active connection before opening a new one. "ftp.mysite.com"; if need to connect to a non-standard port number, concatenate the port number to the host name like "ftp.mysite.com:21"

Parameters:
host - address of the server; can be numeric IP address like "127.0.0.1" or a named one like
username - the client username
password - the client authentication password
Returns: 1 on success, ERROR on failure

FTPeek_ConnectSFTP ( host ; publicKey ; username ; password )

Connects to an SFTP (SSH File Transfer Protocol) server with the specified address, public key, username, and password. You must call one of the connect methods (either FTP, SFTP, or FTPS) before you can call any other FTP functions.
If multiple connect functions are called, the last connection remains as the active working connection. While previous connections will time-out and eventually disconnect, a server may allow a limited number of concurrent connections per account, limiting new connections until the old ones are closed. It is therefore highly recommended to close any active connection before opening a new one. port number, concatenate the port number to the host name like "ftp.mysite.com:21"

Parameters:
host - address of the server; can be numeric IP address like "127.0.0.1" or a named one like "ftp.mysite.com"; if need to connect to a non-standard
publicKey - the unique key of the server, obtained by calling FTPeek_GetPublicKey. If a wrong key is entered, the connection will be refused and this error thrown: "The host signature is invalid or the host key was not accepted!"
username - the client username
password - the client authentication password
Returns: 1 on success, ERROR on failure

FTPeek_DeleteDir ( remoteDir )

Deletes the specified empty remote directory. Trying to delete a non-empty remote directory will produce an error. The remoteDir path can be relative or absolute. Please see the note on relative and absolute paths at the top of the page for more information. *

Parameters:
remoteDir - remote directory to delete
Returns: 1 on success, ERROR on failure

FTPeek_DeleteFile ( remoteFile )

Deletes the specified remote file. The remoteFile path can be relative or absolute. Please see the note on relative and absolute paths at the top of the page for more information. *

Parameters:
remoteFile - remote file path to delete
Returns: 1 on success, ERROR on failure

FTPeek_Disconnect

Disconnects from the server and quits the current SFTP/FTP/FTPS session.

Returns: 1 on success, ERROR on failure

FTPeek_DownloadFile ( remoteSourcePath ; localDestPath { ; newLocalFileName } )

Downloads a file to the specified directory and optionally renames the file. will be named whatever it was named on the FTP server.

Parameters:
localDestPath - the directory on the computer running FileMaker Pro where the downloaded file should be stored, for example "/Users/Shared/Downloads/" or "filemac:/Macintosh HD/Users/Shared/Downloads/"
remoteSourcePath - the file path on the remote FTP server to download
newLocalFileName - an optional parameter that can be used to locally rename the downloaded file. If left empty, the file
Returns: 1 on success, ERROR on failure

FTPeek_DownloadFileToContainer ( remoteSourcePath )

Downloads a file and returns file's data into a container field. For example, this will download a Word document from the FTP server and store it into a container field: 
Set Field[ example::ContainerField; 
     FTPeek_DownloadFileToField("My report.doc") ]

Parameters:
remoteSourcePath - the file path on the remote server to download
Returns: container data with the downloaded file

FTPeek_DownloadFileToField ( remoteSourcePath { ; encoding } )

Downloads a file and returns file's data as text. For example, this will download a text file from the FTP server and store it into a text field: 
Set Field[ example::TextField; 
     FTPeek_DownloadFileToField("My File.txt") ]

Parameters:
remoteSourcePath - the file path on the remote server to download
encoding - optional text encoding. Some of the supported encodings are "ASCII", "ISO8859_1", "UTF8", "UTF-16", for more suppoted encodings consult http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html use the second column of the table as the encoding name.
Returns: Text data

FTPeek_GetCurrentDir

Returns path of current working directory on the server.
For example, if the plugin has connected and navigated into a directory called "temp", calling the FTPeek_GetCurrentDir function will return "/temp/".

Returns: path of current workind directory

FTPeek_GetFileInfo ( remotePath; infoType )

Gets information about the selected file.

Parameters:
remotePath - remote file path to get info for.
infoType - Can be either 'size', which returns the file size in bytes, or 'moddate', which returns a Date field with the modification date of the file.

FTPeek_GetFileList ( { remoteDir } )

Returns a list of files in an optionally specified directory as a return-separated list. If the directory is not specified, the contents of the current working directory is returned. The passed-in directory can be relative or absolute. Please see the note on relative and absolute paths at the top of the page for more information.

Parameters:
remoteDir - the path of the directory to look in, or empty for the current working directory
Returns: return-separated list of files in the directory

FTPeek_GetPublicKey ( host )

Gets an SFTP server's public key, which must be provided as a parameter to FTPeek_ConnectSFTP. The public key is used to check to make sure that the server you are connecting to is the same one that you originally retrieved the key from. This prevents a malicious attacker from using DNS spoofing to pose as the real FTP server. For this reason, you should get the public key the first time you connect to an FTP server, and then store that in your FileMaker database and use the same key each time you connect to the server. You could retrieve the public key every time you connect to the server, but that would defeat the purpose of this security layer.

Parameters:
host - address of the server; can be numeric IP address like "127.0.0.1" or a named one like "ftp.mysite.com"
Returns: a text representation of the server's public key

FTPeek_IsConnected

Returns connection status.

Returns: 1 if connected to server, 0 if not connected

FTPeek_LastError

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. For example, 
If[ FTPeek_ConnectFTP( "ftp.domain.com"; "username"; "password" ) = "ERROR" ]
Show Custom Dialog[ "Could not connect to FTP Server: " & FTPeek_LastError ]
Exit Script
End If

Returns: Error text, or null if there was no error.

FTPeek_LicenseInfo

Returns license information about the plugin. This shows whether it is registered, and what type of license is being used.

Returns: plugin license information

FTPeek_MakeDir ( remoteDir )

Creates a remote directry or directory path. If there are multiple directories in the path hierarchy that do not exist, all of them are created as necessary. The remoteDir path can be relative or absolute. Please see the note on relative and absolute paths at the top of the page for more information. *

Parameters:
remoteDir - remote directory path to create
Returns: 1 on success, ERROR on failure

FTPeek_Register ( licenseKey ; registeredTo )

Registers the plugin. This will not be retained at the next launch of FileMaker, so if you're using this method to register the plugin, you'll want to call this in the startup script. For developer licenses, this is the only way to register the plugin.

Parameters:
licenseKey - registration key
registeredTo - register to entity
Returns: 1 on success, ERROR on failure

FTPeek_Rename ( from ; to )

Renames a file on the remote server. The from and to paths can be relative or absolute, however, the "to" file path must be in the same directory as the "from" file path. Please see the note on relative and absolute paths at the top of the page for more information.

Parameters:
from - old file name to rename from
to - new file name to rename to
Returns: 1 on success, ERROR on failure

FTPeek_ScanLocalDir ( localPath ; recursive )

Do not use this function - it is only included for backwards compatibility and will be removed from a future version of FTPeek. Use FTPeek_ScanLocalDirectory instead.

FTPeek_ScanLocalDirectory ( localPath ; isPathFromFilemaker )

Scans a local directory and returns a return-separated list of files in the directory. This is useful for examining the contents of a local directory to select files for upload. For example, the following call:
Set Field[ example::localFilesList; 
     FTPeek_ScanLocalDirectory( "/Library/User Pictures/Animals", 0 ) ]
on Mac OS X will set the field example::localFilesList to a return separated list of files, such as 
Butterfly.tif
Cat.tif
Dog.tif
Dragonfly.tif
Jaguar.tif
Parrot.tif
...etc
Calling this function on Windows:
Set Field[ example::localFilesList; 
     FTPeek_ScanLocalDir( "C:\WINDOWS\Media"; 0 ) ]
will set example::localFilesList to 
chimes.wav
chord.wav
ding.wav
flourish.mid
notify.wav
onestop.mid
recycle.wav
ringin.wav
ringout.wav
start.wav
tada.wav
town.mid
...etc

Directories will end in a '/' on Mac OS X or '\' on Windows.

Parameters:
localPath - path of the local folder to scan
isPathFromFilemaker - Set to 1 if localPath is a FileMaker-style path, returned from a FileMaker path function such as Get( DesktopPath ) or Get( TemporaryPath ). Set it to 0 if localPath is a native operating system path. For example, the file-style path to the user's desktop returned by Get( DesktopPath ) is '/Macintosh HD/Users/jesse/Desktop/', where the normal OS X path would be '/Users/jesse/Desktop'.
Returns: return-separated list of files in the specified directory

FTPeek_SetShowProgress ( showProgressFlag )

Configures whether to show progress bars on upload/download. Once this is set, it remains on that setting until changed, or until FileMaker is quit and restarted.

Parameters:
showProgressFlag - 0 to supress progress bars, 1 to show progress bars.
Returns: This always returns a 1.

FTPeek_UploadFile ( remoteDestPath ; localSourcePath )

Uploads a file to the remote server. If the upload directory structure does not exist on the remote server, it will be created as necessary. If the remote destination path is blank the file will be saved in the current working directory. If the remote file name is not specified ( remoteDestPath ends with a '/' slash character ), the remote file will be named the same as the local file. The remoteDestPath path can be relative or absolute.

Please see the note on relative and absolute paths at the top of the page for more information. localSourcePath can be a system specific file path or a URL. ( ex. http://serverAddress/sample.mov ).

Here is an examaple of how to upload a file into the current working directory on the FTP server, retaining the same name as the source file: 

If[ FTPeek_UploadFile( "", "/Library/Desktop Pictures/Lines Blue.jpg" ) = "ERROR" ]
Show Custom Dialog[ "Could not upload file"; FTPeek_LastError ]
End If

Parameters:
remoteDestPath - remote file or dir path to upload to; will be created if directory structure does not exist; if empty current working directory will be used
localSourcePath - local file path to upload
Returns: 1 on success, ERROR on failure

FTPeek_UploadFileFromContainer ( remoteDestPath ; containerToUpload )

Uploads container data as a file to the remote server. If the directory structure to upload to does not exist on the remote server, it will be created as necessary. If the remote file name is not specified ( remoteDestPath ends with a '/' slash character ), the remote file will be named the same as the local file. The remoteDestPath path can be relative or absolute. Please see the note on relative and absolute paths at the top of the page for more information.

Parameters:
remoteDestPath - remote file or dir path to upload to; will be created if directory structure does not exist
containerToUpload - container data to upload
Returns: 1 on success, ERROR on failure

FTPeek_UploadFileFromField ( remoteDestPath ; textFieldToUpload { ; encoding } )

Uploads text from a text field as a file to the remote server. If the directory structure to upload to does not exist on the remote server, it will be created as necessary. If the remote file name is not specified ( remoteDestPath ends with a '/' slash character ), the remote file will be named the same as the local file. The remoteDestPath path can be relative or absolute. Please see the note on relative and absolute paths at the top of the page for more information.

Parameters:
remoteDestPath - remote file or dir path to upload to; will be created if directory structure does not exist
textFieldToUpload - text data to upload
encoding - optional text encoding. Some of the supported encodings are "ASCII", "ISO8859_1", "UTF8", "UTF-16", for more suppoted encodings consult http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html use the second column of the table as the encoding name.
Returns: 1 on success, ERROR on failure

FTPeek_Version

Returns the version number of the plugin. This is always a numeric value, with no letter characters.

Returns: the version number of the plugin