SuperContainer Companion Plugin User Guide

This plugin does not have to be installed to use the 360Works SuperContainer Web Viewer add-on, but it allows you to automate certain features that would normally require user interaction.

The plugin supports uploading container fields into SuperContainer, or downloading into a local container field from SuperContainer. In addition, there are methods for deleting a file stored in SuperContainer, download files to the local drive, and for getting details about a file stored in SuperContainer.

This plugin is particularly useful for migrating data from container fields in an existing solution into SuperContainer.

Note: Instant Web Publishing clients should not use the plugin to upload files, because for IWP the plugin is on the server, so it can only access files on the server. This is probably not what you want! Instead, IWP clients should upload file via a web viewer which is placed on a layout. Your solution might have a separate layout for IWP uploads.

Important: you must call SCSetBaseURL before calling any plugin functions which interact with the SuperContainer server, passing the location of the server. We've disabled IWP plugin uploads in the SuperContainer Example.fp7 file which is included in the download.

For example, if you are running the standalone SuperContainer server on your development machine, call this:

SCSetBaseURL("http://server.mycompany.com:8020/SuperContainer/Files")

Note that you pass the complete URL, up to the "Files" component. All other plugin functions accept a relative folder path as a parameter (NOT a complete URL). This is the folder on the server where the file is stored, or where you want it to be stored. It should not include the SuperContainer host, port, or action name. For example:

SCGetContainer("staff/portraits/42")

Generally you will want to call SCSetBaseURL in your startup script. Once the plugin knows the complete URL to your server, the rest of the plugin functions only need to know the relative path on the server.

One thing to watch out for when using the plugin: Sometimes a plugin script will return before SuperContainer has finished processing the last action. So you might upload a file with the SCSetContainer plugin function, then immediately call SCGetInfo before the previous action has completed. One solution is to just put a pause script step in between the two actions.

Consult the SuperContainer documentation (Leveraging the Plugin) for several example usages of the Plugin Functions.

The companion plugin should work with container references as well as as stored container fields.

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 SCLastError 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: " & SCLastError ]
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: " & SCLastError ]
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 (32-bit). 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.

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 (.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.

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 (.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. 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

SCChooseFile ( { initialPath ; fileType ; title } )

Shows a file chooser dialog where a user can browse her local hard drive. When the user selects a file or directory and clicks "OK" on the file chooser, this function returns the path to the selected file or directory. If the user hits the cancel button, nothing is returned.

File Type

By supplying a fileType parameter, you can allow the user to just select files, just select directories, or select both files and directories. The default behavior is to only allow file selection.

When selecting files, you can combine this function with SCSetContainer to import a single file from a user's hard drive to SuperContainer. For example, the following code uploads a local file of the user's choice to the SuperContainer server:

SCSetContainer(Asset::ID ; SCChooseFile);

When selecting directories, you can combine this function with SCScanDirectory to batch-import the contents of a directory. The following example prompts the user to select a directory, then scans that directory recursively (returning a list of all files in the directory).

SCScanDirectory ( SCChooseFile("" ; "directories" ) ; true)

NOTE: specifying a fileType of "directories" or "files + directories" will cause a non-native file dialog to be used on some platforms, as the native dialogs may not support directory selection.

Parameters:
initialPath - optional path to set the initial dialog selection to. If empty, will default to the user's home directory.
fileType - whether to allow "files", "directories", or both "files + directories"
title - optional title string to display as the title of the FileChooser dialog
Returns: Path to the selected file, nothing if no file was selected, or "ERROR" if an error occurred.

SCClearLocalCache

Removes any locally cached temporary files which were downloaded by the SuperContainer companion plugin. This will only delete files in the temporary directory. The SuperContainer companion plugin saves temporary files when SCGetContainer is called without specifying a destination path. These are saved in the tmp directory.

Returns: 1 if all temporary files were successfully deleted, or "ERROR" if one or more files could not be removed.

SCCopy ( folderPath ; destinationPath {; filename } )

Copies a file on the SuperContainer server to an new location. This is useful if you want to move a file somewhere without losing the reference to the original.

If there is no file at folderPath, this function will return an error.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

Parameters:
folderPath - The folderPath of the file to copy
destinationPath - The folderPath of where you want to copy the original file to
keyValuePairs - optional key=value pairs. Options: filename, example filename=myNewName.txt.
Returns: 1 if the file was successfully copied, or "ERROR" on failure.

SCDelete ( folderPath )

Deletes the SuperContainer file with the given folder path.

If there is no file at this folderPath, nothing is changed on the server.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

To delete a file from the local filesystem, use the SCDeleteLocalFile function instead.

#Do the delete
Set Variable [$result; Value:SCDelete( Get( LayoutTableName ) & "/" & ID)]
#Check for error during delete
If [$result = "ERROR"
Show Custom Dialog ["Could not delete file"; SCLastError]
End If
# Refresh the web viewer to show the empty web viewer
Set Web Viewer [Object Name: "webviewer"; Action: Reload]

Parameters:
folderPath - the unique identifier for a supercontainer file.
Returns: 1 if the file was successfully deleted or did not exist, or "ERROR" on failure.

SCDeleteLocalFile ( localFile )

Deletes a file from the local filesystem. This may be used as part of a batch import process, to delete files after they are successfully uploaded to SuperContainer. NOTE: Be sure to check for successful upload before deleting the local files!

To delete a file from the SuperContainer server, use the SCDelete function instead.

Parameters:
localFile - path to the local file to delete
Returns: 1 if the file was successfully deleted, "" if the file did not exist, and "ERROR" if the file existed but could not be deleted.

SCDownload ( folderPath { ; destinationFolder ; width ; height; key1=value1; key2=value2; ... } )

Download a file from the SuperContainer server to another location, unless the file already exists and is up-to-date with the version on the server. If this is called multiple times for the same file, it is not downloaded again unless the file has changed on the server.

NOTE: If no destinationUrl is provided, the downloaded file will be stored in the user's temp directory, and will be deleted from the user's local drive when FileMaker exits.

Use caution when supplying a custom path, as this method will overwrite files with the same name!

Since this function returns a URL, it can be combined with the Open URL script step to open the downloaded file, for example:

Open URL [SCDownload("Photos/12345")]

Flags

The following flags are valid for this function: NOTE: if specifying a named parameter like filename, the destinationFolder, width, and height are then required, because these parameters are positional. Example:
SCDownload ( "Photos/Original/" & Photos::Photo ID ;  // Folder Path
Get( DesktopPath ) & "MyPhotos/" ; // Destination folder
0 ; 0 ; //width & height parameters
"filename=" & $fileName ; "returns=filepath" )

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

Parameters:
folderPath - The unique SuperContainer path
userDefinedDestPath - Optional URL or FileMaker path of the folder to download the file to (ie. /Macintosh HD/Users/Shared/Images)
width - Optional integer for pictures that represents the width of the image. If a width/height is specified, non-image resources will only download a filename, not the entire file.
height - Optional integer for pictures that represents the height of the image. If a width/height is specified, non-image resources will only download a filename, not the entire file.
flags - optional key=value pairs. Options: selfSignedSSL, returns, filename; example selfSignedSSL=1.
Returns: The URL the file was downloaded to. If the file does not exist or some other error occurred, then "ERROR" will be returned.

SCGetContainer ( folderPath {; width ; height ; resolution ; page} )

Fetches the contents of a SuperContainer file as container data. This function is intended for use with exporting the contents of a SuperContainer file to a container field in FileMaker. If you want to display an image or other file within your FileMaker database, you should use a Web View layout element and reference SuperContainer directly instead of using this function.

If there is no file at this folderPath, an empty result is returned.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

Parameters:
folderPath - the unique identifier for a SuperContainer file.
width - optional width parameter. If the SuperContainer file is an image, it will be resized to this width. Pass in 0 to leave width unconstrained.
height - optional height parameter. If the SuperContainer file is an image, it will be resized to this height. Pass in 0 to leave height unconstrained.
resolution - optional resolution parameter. If the SuperContainer file is an image, the jpeg preview for it will be rendered at the specified resolution. If omitted the default resolution of 72dpi wil be used.
Returns: Container data if successful, nothing if there is no file at that path, or "ERROR" on failure.

SCGetFolderURL ( macPath; winPath; folderPath )

Fetches the stored file's folder location as a URL pointing to a mounted/mapped file server. Note that this does not download anything from the SuperContainer server; it returns a URL pointing to the folder stored directly on the SuperContainer server. This is useful to combine with the "Open URL" script step in Filemaker to allow browsing of stored resources.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

NOTE: A mounted or mapped filesystem-accessible storage location is required to open referenced folder. Otherwise, you should download the file to the local hard drive using SCGetContainer and open it there.

Parameters:
macPath - Mac OS X path to root SuperContainer storage location
winPath - Windows to root SuperContainer storage location
folderPath - The unique identifier for a SuperContainer file folder

SCGetInfo ( folderPath { ; additionalFields } )

Returns meta-information about a supercontainer file, such as the filename, size, height, width, dimension, and date uploaded.

The result has at least three values separated by line breaks:

You can specify additional metadata to retrieve by passing additional arguments to this function. Currently only md5 hashcodes are supported.

MD5 Hash

Pass "md5" as an additional argument to return the MD5 hash of the file in the function result. This can serve as the fingerprint for a digital file, and can be used to help catch duplicate files, or ensure the integrity of a file. For example:
SCGetInfo("/photos/12345" ; "md5")
Might return:
Lucy.jpg
51231
4/8/08 3:02:56 PM
c7f47955c825ed83dfe2a6a2fac1a092
(the last line is the MD5 hash)

If there is no file at this folderPath, an empty result is returned.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

Parameters:
folderPath - the unique identifier for a supercontainer file.
additionalFields - either md5, height, width, dimension, or pagecount.
Returns: The requested data, or empty if the file does not exist, or "ERROR" on failure.

SCLastError

Whenever a plugin function fails, it will return the string "ERROR". You should call this function to get a user-readable description of whatever caused the last error. Here is an example of how to use it:
If [ SCSetContainer( Asset::ID ; theContainer ) = "ERROR" ]
Show Custom Dialog ["Could not store this file"; SCLastError]
End If

Returns: FMType

SCMove ( oldFolderPath ; newFolderPath {; filename } )

Moves a file on the SuperContainer server, without downloading it. This is useful if a folderPath changes for some reason in FileMaker, and you want to move the associated SuperContainer file.

If there is no file at oldFolderPath, this function will return an error.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

To move a file on the local filesystem, use the SCMoveLocalFile function
#Do the move
Set Variable [$result; Value:SCMove( Get( LayoutTableName ) & "/" & ID ; Get( LayoutTableName ) & "/" & DestID; "filename=New Word Document.docx")]
#Check for error during move
If [$result = "ERROR"
Show Custom Dialog ["Could not move file"; SCLastError]
End If
# Refresh the web viewer to show the new file
Set Web Viewer [Object Name: "webviewer"; Action: Reload]

Parameters:
oldFolderPath - The old folderPath of the file to move
newFolderPath - The folderPath to move the file to
keyValuePairs - optional key=value pairs. Options: filename, example filename=myNewName.txt.
Returns: 1 if the file was successfully moved, or "ERROR" on failure.

SCMoveLocalFile ( sourceFile; destinationFile )

Moves file locally from sourceFile to the destinationFile. This is a convenience function that doesn't communicate with the SuperContainer server at all. You might use this function to move files out of a watch directory after uploading them to SuperContainer with the SCSetContainer function.

To move a file on the local SuperContainer server, use the SCMove function.

Parameters:
sourceFile - file or directory to be moved
destinationFile - file or directory which sourceFile is to be moved to
Returns: FMType 1 if the file is successfully moved, or "ERROR" if the files could not be moved.

SCScanDirectory ( path {; recursive } )

Scan a local directory for files. You can use this to get a list of all files in a directory, then iterate over the list in FileMaker, adding files to a SuperContainer instance with the SCSetContainer function.

Parameters:
path - path to the directory to scan
recursive - whether to recurse into sub-directories, or only return files in the top level directory.
See also: SCMoveLocalFile
Returns: a list of all files beneath the indicated directory, excluding directories, or "ERROR" on failure.

SCSetBaseURL ( superContainerUrl {; username ; password } )

Set the location of the supercontainer server instance to be used by the plugin. You must call this function before calling any plugin functions which access the SuperContainer server! If you are running the standalone SuperContainerServer on your machine, you can use localhost as the hostname:
SCSetBaseURL("http://localhost:8020/SuperContainer/Files")
When using for live deployment, you should supply an actual hostname of IP address of the machine which will be running the shared SuperContainer instance. For example:
SCSetBaseURL("http://server.mycompany.com:8020/SuperContainer/Files")

If you supply a valid URL but there is not a running SuperContainer server at the host provided, the base URL will still be set, but an "ERROR" failure code will be returned (use SCLastError to get a detailed error message).

Remember that the default port number is 8020 for the standalone SuperContainer server, and 80 when deploying with FileMaker Server.

Typically, you should call this function in a startup script in your FileMaker database. It only needs to be called once per FileMaker launch, or anytime that the base URL changes.

Parameters:
superContainerUrl - The URL of the superContainer instance to be used by the plugin, e.g. http://fmpro.example.com:8020/SuperContainer/Files.
username - optional username. If your SuperContainer server is set up with password protection, enter the username here.
password - optional password. If your SuperContainer server is set up with password protection, enter the password here.
keyValuePairs - optional key=value pairs. Options: selfSignedSSL, example selfSignedSSL=1.
Returns: 1 on success, ERROR on failure (because of an empty or invalid URL).

SCSetContainer ( folderPath ; data {; param1 ; param2 ; ... } )

Pushes data from a FileMaker container field to a SuperContainer file, overwriting the SuperContainer file if it exists.

NOTE: If the data parameter is empty, this will not delete the superContainer file, use the SCDelete function instead.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

If you want to update the web viewer on a layout to show the newly uploaded file, add a "Set Web Viewer [Action: Reload]" script step to the upload script. This will cause an immediate update to be triggered.

Optional Parameters

The following can be passed as additional parameters to the SCSetContainer function:
filename
use filename=desired_name to provide desired filename for the file.
showProgress
use showProgress=false to hide the progress bar during upload.
Example:
Set Variable[$result =
    SCSetContainer(
        "Documents/D23" ;
        Documents::Legacy Container ;
        "filename=newName.txt" ;
        "selfSignedSSL=1" ;
    )
]
#Do the upload
Set Variable [$result; Value:SCSetContainer( Get( LayoutTableName ) & "/" & ID ; SCChooseFile)]
#Check for error during upload
If [$result = "ERROR"
Show Custom Dialog ["Could not upload file"; SCLastError]
End If
# Refresh the web viewer to show the new file
Set Web Viewer [Object Name: "webviewer"; Action: Reload]

Parameters:
folderPath - the unique identifier for a supercontainer file.
data - the data to be stored, typically a container field. Can also be a URL (ie. http://server/someFile or file:///Users/Shared/aFile) or a File path (ie. /Macintosh HD/Users/Shared/aFile or C:\Documents and Settings\aFile)
params - Additional optional parameters (filename)
Returns: 1 on success, or "ERROR" on failure.

SCVersion

Returns the version number of the SuperContainer companion plugin.

Returns: the version number, e.g. 1.32.