SuperContainer Companion Plugin User Guide

Installation

Requirements

FileMaker version 12 or higher.

When 360Plugins are intialized for the first time, they will automatically download all required support files

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, please send an email to support@360works.com

WebDirect Install (FMS 13+)

Install plug-ins for use with WebDirect by dragging the appropriate plugin to FileMaker Server/Web Publishing/publishing-engine/cwpc/Plugins

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 or WIN(.fmx) 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 call 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, custom web publishing now runs as a 64-bit application and requires the 64-bit version of the plugin 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.

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 (.fmx64 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. Restart the FileMaker Script Engine by opening Terminal (Mac) or CMD (Windows) and type the command: fmsadmin restart fmse -y . Note: On Windows you may need to change directories to where the fmsadmin utility is located in order to run this command. By default this is located at "C:\Program Files\FileMaker\FileMaker Server\Database Server" This step is not necessary if using Powershell
  3. Go to Configuration -> Database Server->Server Plug-ins and check the box that says 'Enable FileMaker Server to use plug-ins'(if it is not already checked), 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 AutoUpdate much easier. This file includes pre-configured plugin files which you can place on your server, and an AutoUpdate script for each of our plugins which you can paste into your own solution.

You can get the AutoUpdate360Works file here 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: 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. You will need to call the register function at the beginning of any script that is going to call plugin functions. This will ensure that you do not get demo mode errors.

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!

Error Handling/Reporting

When calling plugin functions as script steps, you will handle errors in the same manner you would any other FileMaker script step. Please see the FileMaker documentation for how to handle errors appropriately. Generally, if there is an error, our plugins will return an error code of 1552 when Get(LastError) is called. However, some plugin functions will return different error codes. If a function can return an error code other than a 1552, it will be documented with the description of the function below. In addition to the error code, you can also get the description of the error by calling Get(LastExternalErrorDetail)

You can also call our functions in a calculation dialog. In this case, error handling is done differently. If you decide to call plugin functions in a calculation dialog and you want to capture errors, see this page page for instruction on how to do so

Examples

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.

Function Summary

Function Detail

SCChooseFile ( { initialPath ; fileType ; title ; [ key1=value1 ; key2=value2 ; ... ] } )

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
keyValuePairs - optional key=value pairs. Options: useNative, which you can set to false to use a Java file dialog instead of a native file 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 a new location within the SuperContainer directory. 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 an additional 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 ; key1=value1 ; key2=value2 ; ... } )

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
Returns:

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. See the 'additionalFields' documentation below for details.

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"; "width"; "height")
 
Might return:
 Lucy.jpg
 51231
 4/8/08 3:02:56 PM
 c7f47955c825ed83dfe2a6a2fac1a092
 640
 480
 
(the fourth 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: error message text

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.

SCReportProblem ( emailAddress ; problemDescription )

Send a problem report to 360Works.

Parameters:
emailAddress - The user's email address to allow for support contact
problemDescription - A description of the current issue
Returns: Always returns 1

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 - Pass in 1 to recurse into sub-directories, or pass 0 or empty to only return files in the top level directory. Does not recurse into sub-directories if this parameter is omitted.
See also: SCMoveLocalFile
Returns: a list of all files beneath the indicated directory, excluding directories, or "ERROR" on failure.

SCSetBaseURL ( superContainerUrl { ; username ; password ; key1=value1 ; ... } )

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.

NOTE: If specifying named parameters like selfSignedSSL, the username and password fields are required because these parameters are positional. If username/password are unused, insert empty quotes ("") instead. For example:

SCSetBaseURL("http://localhost:8020/SuperContainer/Files" ; "" ; "" ; "selfSignedSSL=1")

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

SCSetCertificate ( certificatePathOrContainer { ; certificatePathOrContainer2 ... } )

Adds a certificate(s) to the trust store

Parameters:
certificatePathOrContainer - A path or container field reference to an X509 server-side certificate. You may add more paths or certificate references if necessary (e.g., an entire certificate chain).
Returns: 1 on success or the word "ERROR" on error (see SCLastError for details on retrieving a more descriptive error message)

SCSetContainer ( folderPath ; data {; filename=xyz.jpg ; showProgress=false ; ... } )

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.

SCSetErrorCapture ( 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 SCSetErrorCapture with a parameter of True. That will suppress the error dialog from appearing to the user.

Example:

SCSetErrorCapture(True) // prevent dialogs
 

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

SCVersion

Returns the version number of the SuperContainer companion plugin.

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