1 Deploying to Web Server (Quick Start)

  1. Upload or publish the entire "filecatalyst" folder contained in FileCatalystTransferAgentDeployment.zip to the web root of your web server. You will then be able to access a start page at http://mysite.com/filecatalyst which contains links to documentation and sample pages. If you don't have a web server, see Deploying to the built-in, web server section.
  2. Using your favourite text editor, edit /filecatalyst/js/configuration.js and define your host information under pg.config.remoteNodes. If you plan to use download buttons (per download-button.html), you must also configure pg.config.downloadButtons.
  3. You can make multiple copies of configuration.js ex: configuration2.js to connect to different FileCatalyst Servers or accounts. Just modify the HTML file that includes the JS file to load the desired configuration file.
  4. Choose one of the following pages based on your desired functionality: upload.html, download.html or download-button.html
  5. Using your favourite text editor, edit the desired page to customize the look. To change look and feel, the key files to edit are the selected HTML page as well as css/main.css.
  6. This step is not required for the local web server. The application serves a few files that might not have registered MIME types on your web server. These must be registered in order for the application to function. They include: .pkg, .exe, and .json. The MIME type for .pkg and .exe is application/octet-stream, and the MIME type for JSON is application/json.
    • In Apache, the mime types are defined in httpd.conf. For example, to register the .pkg file type, you will have to add the following line:
      AddType application/x-octet-stream .pkg
    • In Tomcat the mime types are defined in /conf/web.xml the lines to add are:
      <mime-mapping>
      <extension>pkg</extension><mime-type>application/octet-stream</mime-type>
      </mime-mapping>

    • For other web servers, please consult the manual on how to define custom mime types.

2 Deploying to Web Server (Detailed Instructions)

The deployment package contains the files needed to deploy a sample application to the web, as well as the separate JavaScript files which encapsulate the underlying functionality of the application. If you don't have a web server, see Deploying to the built-in, web server section.

The fastest way to get a single transfer page up an running is to follow the instructions in the previous section. Deploying the full web application starts the same way: move the contents of the included "filecatalyst" directory to an appropriate location on the web server. For example, for the application to be found at mysite.com/filecatalyst (case sensitive), move the "filecatalyst" directory from the package to within mysite.com web root. In addition to the single pages referenced in the previous section, an application will be available at http://mysite.com/filecatalyst (case sensitive), which can optionally be renamed.

It should be noted that in addition to the usual collection of HTML, CSS, and JS files, the application provides ".exe" files for Windows and ".pkg" files for Mac. The web server must be configured to recognize these MIME types or end-users will see a web server error and fail to download the required TransferAgent application.

The following files are included in the package in the following hierarchy. Optional files are indicated as well as the conditions for the option. In the sample application, minified versions of the files are included when appropriate and available. Only the full OR the minified version of a given file needs to be included.

  • filecatalyst - containing folder; application does not strictly need to be in a container
    • *icon*.png, favicon.ico - a series of favicon files; may be replaced with custom icons
    • *.html - files encapsulating implementations of the TransferAgent. Standalone implementations include "download.html", "download-button.html", and "upload.html". After deploying the folder to a web server, navigating to "index.html" will reveal links to these pages. In addition to being standalone implementations, these pages also serve as examples for implementing TransferAgent into your own application.
    • credits.txt - Text file acknowledging 3rd-party sources
    • css - sample pages will refer to files in a "css" directory matching this name and place in the hierarchy. This css folder does not apply to the Express (2-way) app.
      • bootstrap.css - full non-minified version of Bootstrap 3 CSS. May be periodically updated, so avoid modifying this file
      • bootstrap.min.css - minified version of Bootstrap 3 CSS.
      • font-awesome.css - full non-minified version of the CSS required to use "fontawesome" as an alternate icon set. Optional if not using Font Awesome
      • font-awesome.min.css - minified version of the CSS required to use "fontawesome" as an alternate icon set.
      • main.css - like all CSS, not strictly "required"; however, many UI conventions are established via the main application CSS which would need to be replicated or replaced if this is not included.
    • docs - this directory is intended for offline viewing by the administrator and is not required for web deployment
    • files - this directory contains files which the end-user may need to download. The application may be configured to retrieve files from a different location.
      • MacOSX/FileCatalystTransferAgent.pkg - the downloadable install package for Mac OSX
      • Windows/install_fc_transferagent.exe - the downloadable installer for Windows
      • Linux/fc_transferagent.tar.gz - the downloadable installer for Linux
    • fonts - contains the actual font files (OTF, EOT, SVG, TTF, WOFF) used by web-font CSS. This fonts folder does not apply to the Express (2-way) app.
      • fontawesome.* - all related files for rendering Font Awesome in the browser. Not required if not using Font Awesome icon set
      • glyphicons-halflings-regular.* - all related files for rendering Bootstrap default icons. Not required if not using Bootstrap
    • i18n - this directory contains internationalization files. By default, a subdirectory called "dev" containing a file called "translation.json" is replaced during each application upgrade. The administrator may provide alternative or supplemental language files, each in their own subdirectory. See the Internationalization section of this document for more details. This i18n folder does not apply to the Express (2-way) app.
    • images - sample pages will use inline HTML and CSS that refers to files in an "images" directory matching this name and place in the hierarchy
    • js - most JavaScript is considered required, and should be included in the order described in the Configuring JavaScript section of this document
      • vendor - a folder containing 3rd-party scripts issued vendors and integral to the application
        • bootstrap.js - full non-minified version of Bootstrap JavaScript, which enables interactive widgets provided in the Bootstrap framework. Optional if not using Bootstrap
        • bootstrap.min.js - minified version of Bootstrap JavaScript
        • jquery.js - full minified version of jQuery. jQuery itself is REQUIRED; however, an application may load jQuery 1.10.2+ from an alternative resource (eg. CDN or elsewhere on the web server)
        • modernizr-2.6.2-respond-1.1.0.min.js - a concatenation of modernizr and respond. The former provides useful classes after feature detection and the latter provides a shim for cross-browser responsive layouts. Optional if developing with different responsiveness and feature detection tools or if such tools are not required for the application. Required for the sample pages.
      • configuration.js - web administrator (You) MUST configure this file in order for the application to function correctly. Configuration is done through this required Java Script file. You can make multiple copies of this file ex: configuration2.js to connect to different FC Servers or accounts. Simply modify the HTML file that includes this JS file to load the desired configuration.
      • main.js - the main functionality of the TransferAgent web front end. Without this file there is no application
      • plugins.js - plugins used by functions found in main.js. Application will fail without this file.
    • express - a folder containing all the HTML/JavaScript/JSON files for Express (2-Way) Deployment. A deployment of Express requires additional files; see full instructions in the section on Deploying Express (2-way).
      • express-src - The main files required to launch Express (2-way) application. Changes to Express CSS are made to express-src/css/main.css
      • /express-src/express.html - This file redirects to /express-src/index.html, which in turn serves as the example file of how to include Express in your web application.
      • /i18n/ - The localization folder, which contains the default "dev" folder and its translation.json localization file with Express language entries.

3 Upgrading An Existing Deployment

Instead of deploying a brand new instance of the TransferAgent deployment, you may wish to upgrade an existing instance to the current version. To do this, please follow these steps:

  1. Create a separate "upgrade" folder anywhere within your current file system. Usually this folder is set up within the existing deployment location, but it can be placed anywhere you choose.
  2. Move the following configuration files and/or folders into the "upgrade" folder that you created in step 1.
    • filecatalyst/i18n/ - entire folder (only if you made changes to the language file)
    • filecatalyst/js/configuration.js
    • filecatalyst/js/configuration{Any-other-copy}.js if you use several configuration.js files

    If your current deployment version is 3.7 or greater, you will also need to move the following configuration files:

    • filecatalyst/express/i18n/ - entire folder (only if you made changes to the langauge file)
  3. Overwrite your existing deployment with the new version that you wish to deploy.
  4. Once the overwrite process has been completed, you will have to manually merge your "upgrade" configuration files into the new files. For each difference between your "upgrade" configuration file and the new configuration file, you will need to copy the difference over to the new deployment configuration file.

    Note: Any folder not titled "dev" within your "upgrade" i18n folders do not need to be merged separately. Instead of merging your changes one by one, you may just copy the files into the new i18n locations.

4 Setting up HTML Document does not apply to Express (2-way)

4.a Introduction

The basic shell for an HTML document is borrowed from initializr.com, which combines HTML5 Boilerplate, a responsive template, and Twitter Bootstrap into one distribution. Some components are optional, but unless your organization is invested in another framework or house styles, it is highly recommended to use the defaults.
Note: This section does not apply to Express, see Deploying Express (2-way) for more details.

4.b Sample of Complete HTML Document

Here are the basic components of a "default" HTML document for FileCatalyst TransferAgent being used as an upload tool:

<!DOCTYPE html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge, IE=11, IE=10, chrome=1">
    <meta name="viewport" content="width=device-width">
    <link rel="stylesheet" href="css/bootstrap.min.css">
    <link rel="stylesheet" href="css/font-awesome.min.css">
    <link rel="stylesheet" href="css/main.css">
    <script src="js/vendor/modernizr-2.6.2-respond-1.1.0.min.js"></script>
  </head>

  <body>
    <!-- arbitrary markup for your page. Example shows a bare bones localfiles widget
     embedded on the page -->
    <div id="localFiles" class="col-lg-6"></div>
    <div class="col-lg-6">Other markup in second column</div>

    <script src="js/vendor/jquery.js"></script>
    <script src="js/bootstrap.min.js"></script>
    <script src="js/plugins.js"></script>
    <script src="js/configuration.js"></script>
    <script src="js/ta_lib.js"></script>
    <script src="js/main.js"></script>
  </body>
</html>
              

4.c Breakdown of Sample Document

The meta tags, CSS includes, body markup, and JavaScript includes all play a role, though some components are optional.

Meta Tags

  1. X-UA-Compatible tag needs the content list provided in the example in order for certain JavaScript components to function (primarily the table header float function)
  2. viewport tag is required for the responsive layout.

CSS Includes

The HTML document has no strict requirements for CSS. However, it is recommended that you include at minimum main.css found in the zip archive. Here are the default CSS files included, all found within the "css" subdirectory of the web deployment:

  1. bootstrap.min.css: If you choose to use Bootstrap, this stylesheet should be included before the others.
  2. font-awesome.min.css: FileCatalyst TransferAgent provides a mechanism for using alternative icons, and Font Awesome is included as one such option out of the box. To use Font Awesome, include this CSS file as well as the related files from the /fonts subdirectory.

    Note: if you are not using Bootstrap, it is highly recommended to use Font Awesome as the configured icon set.
  3. main.css: custom non-bootstrap styles used for laying out the application widgets and overriding Bootstrap defaults when necessary. In most cases, you should be including main.css

Body Markup

The FileCatalyst TransferAgent API may be accessed indirectly by using markup conventions. The bare minimum markup for a fully-functioning upload transfer area is:

<div id="localFiles"></div>
              

JavaScript Includes

The purpose of this section is to itemize and describe the JavaScript files included within the HTML document.

Modernizr/Respond and Bootstrap are optional with caveats. The rest of the JavaScript files are required for the application to function. JavaScript files are found within the "js" subdirectory of the web deployment. A server-side script could be used to concatenate and then minify these scripts; however, such a mechanism is not provided in the TransferAgent distribution.

  1. /vendor/modernizr-{version}-respond-{version}.min.js: the only JavaScript file included in the document <head> by default (the rest appear before the body closing tag), the Modernizr.js portion provides feature detection echoed into the HTML tag, while the Respond.js portion provides a media queries shim for the responsive layout.
  2. /vendor/jquery-{version}.min.js: jQuery's utilities are used throughout the application. You do not necessarily need to include the one bundled in the deployment archive (for example, you may use a CDN). jQuery must be included before the remaining scripts.
  3. /vendor/bootstrap.min.js: The Optional Bootstrap JavaScript utilities may be used without the Bootstrap CSS; however, the functionality is generally not correct until appropriate CSS is paired with the resulting components (for example, a Bootstrap modal dialog will use Bootstrap classes for the overlay, position, animation, and buttons. Without Bootstrap CSS you will need to identify and provide analogies).
  4. plugins.js: JavaScript plugins used throughout the application for things such as Growl notifications and a unified localStorage API.
  5. configuration.js: configuration of application behaviour and node connections.
  6. main.js: the main application itself, containing all methods required to process and display TransferAgent interactions.

5 Deploying Express (2-way)

From within the deployment package, a folder called "filecatalyst" represents your web root. This folder itself does not need to be copied; only the contents matter. However, we will use this folder name to represent the root path to which you are deploying TransferAgent's UI. These are the minimum files required for an Express deployment:

  • /filecatalyst/js/configuration.js (a single file, but within the "js" directory)
  • /filecatalyst/files (entire directory and contents)
  • /filecatalyst/express (entire directory and contents)

The main application is found in the "express" folder; however, the shared configuration is found in configuration.js and shared downloadable resources (ie. the TransferAgent itself) are found in the "files" folder. Since "configuration.js" and "files" are often shared with the upload-only and download-only interfaces, we recommend that you simply copy all the files in the "filecatalyst" (root) folder. See Quick Deployment for details.

Here are some key deployment points:

  • Connection Details - Express also uses configuration.js for connection details. You MUST configure this file with connection details to your own FileCatalyst Server. You can use PGP message for encrypting connection details in JavaScript
  • HTML - Use /filecatalyst/express/express-src/index.html as an HTML example on how to make Express visible on your web page.
  • Custom Look and Feel - use /filecatalyst/express/express-src/css/main.css to make style changes to your deployment. You may also use any other method of adding and overriding the supplied CSS, such as writing it inline on the page or including an additional custom CSS file.
  • Language File - use /filecatalyst/express/i18n/dev/translation.json to make changes to the language entries visible to the end user. We recommend to make a copy of the translation.json file to roll back to. The application uses auto-detection, query string, or HTML tags to specify localization. We use i18next for localization; the i18next documentation will provide full information on how to localize for your users. A few common scenarios:

    • Providing an additional standard language: copy the "dev" folder and rename it to a code matching a standard region identifier. For example, for general French to be available, the copied "dev" folder would be renamed to "fr". To provide English translations that are specific to regions, you might have a set of directories: "en", "en-GB", and "en-US" for example, with "en" being the fallback for regions other than Great Britain and the U.S.A.
    • Forcing a particular language: bypass auto-detection by providing a query string on your URLs: "?setLng=fr", "?setLng=en-GB"
    • Forcing a custom language: using the query string technique, you can force language from an arbitrary folder which does not need to be named with region code standards: "?setLng=foobar"
  • Server Messages/Logs - by default server messages/logs are visible on the bottom of the HTML page that contains Express. To hide server messages/logs, edit /filecatalyst/js/configuration.js and set pg.config.express -> showLogs:false Alternatively, you could simply hide the area by adding this rule to your CSS:
    .log-element { display: none }
  • Hiding user functionality - the following functions can be hidden from the end user in Express:
    • Upload
    • Download
    • Delete
    • Rename
    • Refresh
    • Directory Info
    • Change Directory
    • Make Directory
    Use the pg.config.permissions in /filecatalyst/js/configuration.js to set the functions you wish to make available to the end user. These permissions are only cosmetic, they have to also be enforced on the FileCatalyst Server user permissions.

6 JavaScript Configuration

Behaviour, appearance, and connection-related parameters are all configurable within the configuration.js file in the /js subdirectory. Parameters are grouped in a sensible way and are documented via comments. Some parameter groups are completely commented out; these parameters have default values that TA will use and should only be un-commented when you wish to override the defaults.

Since the configuration uses JavaScript, language rules must be respected. Most importantly, you must maintain both sides of a key:value pair. To configure an empty string, for example, you must maintain empty quotation marks as a value. Empty arrays such as the pgpMessage must maintain empty square braces. A comma must appear in-between key:value pairs except the last one, which should drop the comma.

6.a Remote Node Configuration (pg.config.remoteNodes)

The TransferAgent may connect to a remote node which is stored in a JavaScript object literal containing a nested object.

The "key" for each nested object is CRITICAL. It serves as the glue between the JavaScript and the rendered HTML components. This key becomes the "ID" used in the HTML layout engine. Here is a sample of a remote node configuration object, using the key "server1":

pg.config.remoteNodes = {
  server1: {
    name: "Greg Server",
    remoteServer: "192.168.1.139",
    remotePort: 21,
    username: "",
    password: "",
    usesSSL: false,
    initialDirectory: "",
    lockInitialDirectory: false,
	servletURL: "",
    pgpMessage: []
  }
};
              

In the markup, this remote node will be rendered into an element with an ID that matches the key "server1":

<div id="server1"></div>
              

The ID is also used for more granular placement of subcomponents. For example, you can place the queue for this node anywhere on the page using this markup:

<div id="server1-queue" class="ta-queue"></div>
              

The configurable parameters for a remote node are as follows:

parameter options description
name accepts: string
default: “”

The "pretty" name visible to end users. This string is used for certain user-facing labels and headings. When not provided, the application will use the node id (in our example, "server1") in its place.

remoteServer accepts: string
default: “”

IP or hostname of an active FileCatalyst Server. Please note that third-party FTP servers are not supported.

Ignored when pgpMessage is provided; sent as clear text query string otherwise

remotePort accepts: integer
default: 21

The port used for the communication channel between TransferAgent and FileCatalyst Server. FileCatalyst Servers use 21 as the default non-secure port, and 990 for its secure port (when SSL is enabled).

Ignored when pgpMessage is provided; sent as clear text query string otherwise

username accepts: string
default: “”

The username to be used for the connection to the remote server. The user is configured on the FileCatalyst Direct Server. If left empty and pgpMessage is also left empty, the end user will be asked to provide it.

Ignored when pgpMessage is provided; sent as clear text query string otherwise

password accepts: string
default: “”

Password to be used for the connection to the remote server. The password for the user is configured on the FileCatalyst Direct Server. If left empty and pgpMessage is also left empty, the end user will be asked to provide it.

Ignored when pgpMessage is provided; sent as clear text query string otherwise

usesSSL accepts: boolean
default: false

Instructs the connection whether to use SSL on the configured remotePort.

Ignored when pgpMessage is provided; sent as clear text query string otherwise

initialDirectory accepts: string
default: ""

Set an initial directory within the configured server account. For Upload interfaces, if the directory does not already exist, it is created. In the absence of further changes to the current working directory, uploaded files will be written to this directory. For Download interfaces, user will start with a listing of this directory if it already exists.

lockInitialDirectory accepts: boolean
default: false

If an "initialDirectory" value is set, the user will start in that directory. For Download interfaces, this means that the "initialDirectory" value is considered to be their root and they are restricted from navigating higher. For Upload interfaces, there is nothing exposed to the end user and this value is essentially meaningless.

servletURL accepts: string
default: “”

if you wish to use HTTP transfers, this value must be set with the servlet location from the FileCatalyst server

pgpMessage accepts: array of strings
default: [] (empty array)

The pgpMessage is an encoded string broken down into an array of lines. This message contains the credentials for a connection. When a pgpMessage is included—valid or not—the clear-test credentials such as "remotePort", "password", and the like are ignored completely and may be set to empty or arbitrary values.

Please read Generating a PGP Message for more information on how to generate one and why it is essential to full security.

6.b Download Buttons (pg.config.downloadButtons)

Download buttons are configured similarly to remote nodes, except that their objects contain a "fileList", which is an array of files to be accessed when the button is clicked. Just as with remote nodes, the key for each button in the pg.config.downloadButtons object is tightly coupled to an div with a matching ID in the markup. More importantly, the downloadButtons use this key to obtain connection credentials from the pg.config.remoteNodes object.

Here are a pair of download buttons ("button1", "button2") configured in the containing object:

pg.config.downloadButtons = {
  button1: {
    label: "Download Package", //the button label. If left blank, it will default to "Download":
    sourceId: "server1", // must correspond to a connected remoteNode
    destinationId: "", // if blank or not present, will default to "local"
    fileList: ["/aa_testfile.mp4","/Colaboration/Email Setup.jpg"] // an array of strings representing
              paths (either individual files or entire directories) to be downloaded
  },
  button2: {
    label: "Download Media", //the button label. If left blank, it will default to "Download":
    sourceId: "server1", // must correspond to a connected remoteNode
    destinationId: "", // if blank or not present, will default to "local"
    fileList: ["/bb_testfile.mov"] // an array of strings representing paths (either individual files
              or entire directories) to be downloaded
  }
};
              

With this configuration object, a page may contain one or more anchors which have an ID set to reference the "key" in the object, and also has the class "downloadButton":

<a href="#" id="downbutton-button1" class="downloadButton"></a>
              

This minimum requirement is often augmented by CSS classes and custom text which overrides the label (see below). For example:

<a href="#" id="downbutton-button2" class="downloadButton btn btn-primary btn-lg">
Download Pre-Configured Package  <i class="fa fa-download"></i></a>
              

The configurable parameters are as follows:

parameter options description
label accepts: string
default: "download"
This string is rendered to the visible button if the markup does not already provide text
sourceId accepts: string
default: ""
The remote server from which files are to be downloaded. This string MUST correspond to the key of a pre-configured remote node (see previous section).
destinationId accepts: string
default: ""
This parameter will be used to initiate transfer between two arbitrary nodes; however, when not configured or when set to “local”, the download directory of the local TransferAgent install path is presumed to be the destination.
fileList accepts: array of paths
default: empty array

The fileList is an array of paths to files or directories which shall be downloaded by the button. The paths use the root of the configured remote server connection. Leaving the array empty will warn the user that there are no files available for download. For example, an array of paths will look similar to this:

["/file.txt","/subdir/subsubdir/file.doc","/subdir/dir_of_files"]

6.c Node Defaults (pg.config.nodeDefaults)

Certain parameter defaults may be shared between the local and remote nodes. For example, whether browsing a local file system or a remote list of files, you might expect the same default behaviour. The shared node defaults are grouped together in configuration.js:

pg.config.nodeDefaults = {
  sortOn: "name", // determines default sort column. Options are: name, type, size, lastmodified
  invertSort: false, // default sort is A-Z, smallest-to-largest, and oldest-to-newest. invertSort reverses this
  gridClass: "col-lg-6" // adds this class to each file listing "area" when the HTML is generated
};
              
parameter options description
sortOn accepts: string ("name", "size", "type", "lastmodified")
default: "name"
Determines default sort column. Note that after a user has chosen to sort by a different column, their new chose will be remembered and the default will be ignored.
invertSort accepts: boolean
default: false
The default sort is A-Z, smallest-to-largest, and oldest-to-newest. Set invertSort to true to reverse these.
gridClass accepts: string
default: "col-lg-6"
Adds this class to each file listing "area" when the HTML is generated. The default class is used for Bootstrap-based layouts, and will typically have no effect when Bootstrap is not used. Just as with direct editing of HTML, you may add multiple classes by separating with a space. For example, "grid-6 large reverse"

6.d Web application (pg.config.webapp)

The parameters in this section influence the user interface of the web application, as well as certain interactions between the web application and the installed FileCatalyst TransferAgent itself (the "native" tray icon application).

pg.config.webapp = {
  deploy-web.html
  showFileHeadings: true,
  ...
  doAfterTransfer: "",
  statusFields: {
    ...
  }
};
              
parameter options description
showFileHeadings accepts: boolean
default: true
When enabled, an &lt;h2&gt; tag will be rendered at the top of every file area, unless one has already been manually added to the HTML document.
animateRevealedComponents accepts: boolean
default: true
As components are needed, they are faded into the UI rather than abruptly appearing.
collapseEmailAccordion accepts: boolean
default: true
If configured to show an email widget, by default it is collapsed into a "bar". When this parameter is set to false, the widget is expanded instead of collapsed.
autoConnect accepts: boolean
default: true
Connects to and gets listing from any nodes found in the DOM (rendered HTML). When false, an API call must be made to pg.initialize();
appDownloadLinkWindows accepts: URL string
default: "files/Windows/
install_fc_transferagent.exe"
Set the download location for the TransferAgent Java application Windows installer. Depending on your site's structure, you may need to change this to a fully-qualified URL such as "https://mysite.com/filecatalyst/files/install_fc_transferagent.exe". In order for download links to work, your web server must be configured to recognize the .exe MIME type.
appDownloadLinkMac accepts: URL string
default: "files/MacOSX/
FileCatalystTransferAgent.pkg"
Set the download location for the TransferAgent Java application Mac OSX PKG file. Depending on your site's structure, you may need to change this to a fully-qualified URL such as "https://mysite.com/filecatalyst/files/FileCatalystTransferAgent.pkg". In order for download links to work, your web server must be configured to recognize the .pkg MIME type.
iconSet accepts: string
default: "fontawesome"
The “glyphicons” icon set is included with the deployment package. A “glyphicons” icon set is available to those who have included Bootstrap CSS. There is also the option to define a set of icons by following the same definition pattern. a sample is commented at the bottom of configuration.js. Uncomment and rename (if you wish) the sample to use it.
maxListHeight accepts: integer
default: 616
Maximum height, in pixels, for a given file list (local or remote file system browsing widget) before scroll bars appear.
launchDetectTimeout accepts: integer
default: 20
Time, in seconds, that the web application will attempt to launch and detect a running TransferAgent application on page load.
doAfterSuccess accepts:
  • URL string
  • anonymous function
  • function reference
default: ""
If set, an action to take upon successful completion of a transfer. A configured string is expected to be a functioning URL which the transfer page will redirect to. If a JavaScript function is set, that function must be defined and functioning. Any resulting success or error in custom functions are handled by whoever supplies them and not by the FileCatalyst TransferAgent. A data object containing the last known status update is automatically passed into the JavaScript call.

Examples:
  • doAfterSuccess: "http://filecatalyst.com",
  • doAfterSuccess: function() { alert('test function')},
  • doAfterSuccess: successAlert, // where successAlert was defined in a script loaded previous to this configuration file
doAfterError accepts:
  • URL string
  • anonymous function
  • function reference
default: ""
If set, an action to take upon completion of a transfer that contained errors. Behaviour is per doAfterSuccess, described above.
doAfterCancel accepts:
  • URL string
  • anonymous function
  • function reference
default: ""
If set, an action to take upon cancellation of a file transfer. Behaviour is per doAfterSuccess, described above.
doAfterOtherError accepts:
  • URL string
  • anonymous function
  • function reference
default: ""
If set, an action to take upon errors during which the native TransferAgent application stops responding. Behaviour is per doAfterSuccess, described above.
doAfterTransfer accepts:
  • URL string
  • anonymous function
  • function reference
default: ""
Used as a catch-all action to take if you do not wish to specify individual action types. Behaviour is per doAfterSuccess, described above.
statusFields accepts: special object
default: see section on statusFields
While a queue is being transferred, a number of status fields are available. The available fields are self-documented within configuration.js; describing each is beyond the scope of this document. See the below section on statusFields for more instructions.

statusFields

Per the above configuration table, the administrator may set which status fields are visible, as well as whether these appear as one table, or separate tables of current file and overall task statuses. statusFields accepts an object which contains two arrays. In configuration.js, most of the values are commented out but documented. Removing the commented lines reduces this object to the following default:

statusFields: {
    current: ["currentFilename"],
    overall: ["filesSoFar","overallTimeRemaining","rateAverageInKBperSecond","percentBar"]
}
              

By default, the status update draws almost all information from the overall task status, with the exception of the current filename. As you work with the two types of statuses, though, you may wish to visually divide them on the page. To do this, edit your translation.json file:

  1. Enter value for statusFields.current.heading to create a heading that will appear at the top of the status area
  2. Enter value for statusFileds.overall.heading to create a heading that will divide "current file" and "overall task" areas

6.e Transfer requests (pg.config.transfer)

The pg.config.transfer section contains values that are sent from the TransferAgent application to the FileCatalyst Server whenever a transfer task is requested. As such, it is considered to be for advanced configuration only. It is "commented out" so that the administrator has a record of what the default values are, and should only be uncommented when a value is to be set explicitly.

This configuration section is fairly expansive and describing each commented parameter is outside the scope of this document. However, additional comments within configuration.js describe the function of each parameter.

One sub-grouping is NOT commented out and is considered a candidate for the web administrator to update and adjust as needed. That section is the email settings, which looks like this:

/* settings related to email */
SendEmailNotification: false,
EmailAddress: "",
EmailBody: "",
SentFilelistInEmail: false
              

The behaviour expected by adjusting these parameters is as follows:

parameter options description
SendEmailNotification accepts: boolean
default: false
Enable the sending of a notification email upon completion of a transfer. This notification is independent and possibly in addition to any email notifications configured directly on the FileCatalyst Server.
EmailAddress accepts: string
default: ""
A semicolon-delimited list of email addresses receiving notifications upon completion of a transfer. If a user provides a list, it is added to this list.
EmailBody accepts: string
default: ""
Text to be sent in the email body along with some automatically-provided values. If a user also provides an email message, the value of EmailBody is separated with a heading and added after the user-provided message.
SentFilelistInEmail accepts: boolean
default: false
When true, adds a list of files that were sent successfully. Caution: a transfer of thousands of files may create an email which exceeds the mail server's limitations.

There is another sub-grouping which IS commented out but which is considered a candidate for the web administrator to update and adjust as needed. That section is the "Transfer Content Settings" section, which looks like this (full comments are omitted but appear in configuration.js):

/* Begin Transfer Content Settings section -- for UPLOAD only */

//    maxfiles                    : 0,
//    maxsize                     : 0,
//    minsize                     : 500000000000,
//    maxtotalsize                : 9223372036854775807,

...

//    regex                       : "^.*\.(jpg|JPG|gif|GIF|doc|DOC|pdf|PDF)$",
//    limitUploadToFiles          : false, 

/* end Transfer Content Settings section */
              

These parameters serve to filter whether files are allowed to be added to an upload file transfer queue or not. If filters are configured, the files and directories will need to meet to specified criteria in order for the selection to be added. In the event of a failed filter, the entire set of selected files is rejected and the user is given a reason for the failure.

To modify these filters, first un-comment (remove the leading double slashes) and then modify the value. The behaviour expected by adjusting these parameters is as follows:

parameter options description
maxfiles accepts: integer
default: 0
The maximum number of files (including files nested in directories) that may be added to the queue.
maxsize accepts: integer
default: 0
The maximum size (in bytes) for an individual file to be added to the queue.
minsize accepts: integer
default: 0
The minimum size (in bytes) for an individual file to be added to the queue.
maxtotalsize accepts: integer
default: 9223372036854775807
The maximum size (in bytes) for the sum of all file sizes to be added to the queue. The default number is "max long" and represents more than 9 x 10^6 terabytes.
regex accepts: string
default: ""
The filename is evaluated against a regular expression and will pass or fail. The administrator is responsible for creating a valid regex.
limitUploadToFiles accepts: boolean
default: false
When true, only files are allowed in the transfer queue. In other words, adding directories becomes disallowed.

6.f Local agent (pg.config.localAgent)

Within pg.config is the local configuration object, found at pg.config.localAgent. This object contains the defaults (for overriding), options, and requirements for communication between the web application and the local TransferAgent application. These values are visible so that they have the potential to be changed in the future, but as noted in the configuration.js, do not change these values. Doing so has potential to prevent the TransferAgent from successfully connecting to the server.

parameter options description
host accepts: URL string
default: “https://localhost.filecatalyst.net”
Currently, no value other than localhost over HTTPS will create a valid connection; however, the host is set by a parameter for possible changes in the future
port accepts: integer
default: 12680
For a fresh installation or if local configuration values are lost, this value is used to attempt a connection to the TransferAgent before further configuration is required. If a successful connection is made over the default port, the application can skip the configuration phase.

6.g Custom Icons (pg.config.customIcons)

Icons are interchangeable in a similar way to localization. The application substitutes the provided markup where appropriate. To use custom icons:

  1. Provide markup within each item found in pg.config.customIcons
  2. Change the "key" of this set to whatever you wish. In pg.config.customIcons a sample empty set is pre-configured as "custom1"
  3. Update the pg.config.webapp.iconSet parameter to reflect the name of your custom icon set. For example, "custom1"

The markup provided is completely arbitrary, but certain conventions should be followed where possible. For example, some of the application's markup expects the icon to be no wider than 20px and will cut off icons that are too large. If absolutely necessary, some of these size limitations may be overcome with modifications to the CSS (main.css).

Example:

pg.config.customIcons = {
  amazIcons: {
    ...
      directory: '<img src="url_to_image"/>',
      file: '<span class='fileIcon'></span>',
    ...
  }
}
              

To use the above example, pg.config.webapp.iconSet would need to be changed to "amazIcons". Whenever a directory icon is called, a particular image will be provided. Whenever a file icon is called, an empty span (which is likely styled with a background image) is called.

6.h Generating a PGP Message

In the Remote Server Configuration, a parameter called "pgpMessage" is available to the web administrator. This parameter should be considered a requirement for a fully secure environment. Electing to use the "remoteServer", "username", "port", and "password" parameters is less secure, because credentials are transmitted as clear text within a JavaScript file and also locally as a query string. Using pgpMessage ensures end-to-end encryption of credentials.

Within the "filecatalyst" directory of the web deployment files is an HTML document named encrypt.html. This may be run locally or from the web server once the package is deployed.

Fields for connection information and credentials are provided. If uncertain about SSL requirements, leave the box checked to allow SSL. Once the form is completed, press "Generate Parameter String" which will populate two text fields with encrypted text. The top field ("Pre-formatted") is the important one and should look similar to this sample:

["-----BEGIN PGP MESSAGE-----",
"Version: OpenPGP.js v0.6.0",
"Comment: http://openpgpjs.org",
"",
"wYwDdjw46XMAoVEBBADJe+iUDrO/kAQq8kXOnM5e32z14sK3a3KQ666TDnpQ",
"ztton76P7SBN7Pyu84/ZLcC1IhDlv40qA2HB9kkwkfn+0s17MALppeUbQh/l",
"VxK6J0FBvwExpEB7nWwihLXRC+O0jwhPEzG7MBHOqJNzlCDnZcOrkNOqjqZ0",
"KXJG9BQiUtKQAX3MXuY4nILoUKTyQxPG5CrKTmQMlofckrCE3c/pnHADyxkP",
"yXmXVitPsaZ5Ql61bkvOb7NcAQ+Z2WRCjWPe8yhQxRgnPH8cMQPlZPlnJMFI",
"HTLOifOLAgMayhBR0rotSXBH3YWDoKbhp9KFWQgDQOJmmLDq+RFTiE17YIry",
"k8JeE4Q8CRx9hFEYvPZ0dHcK",
"=Oa/p",
"-----END PGP MESSAGE-----"]
              

Copy the generated text from the top field and paste it to the pgpMessage value in the configuration file. The new array replaces the default empty one (the "[]" characters) or the previous PGP Message.

The bottom text field ("Raw output") is not used by the application but is provided for your convenience. It contains the PGP message without being converted to an array of strings.

PGP Message will work for all Upload, Download, Express (2-way) and Download Buttons modes.

6.i Modifying Notifications

TransferAgent has a series of notifications which will show up whenever something important occurs or to give guidance to the user. This includes notifications upon file transfer completion, download of an upgrade package, and application errors.

Along with each of these notifications, a named event is published using the AmplifyJS library. Subscribe to these to trigger custom functionality. The names of these events are also used to refer to specific notifications.

Default Notifications

The table below lists all current notifications and their associated events. The first column contains the name of the event, the second and third columns contain data that is passed to any registered callback or notification, and the last column provides information regarding the purpose of the event.

Event Name First Argument Second Argument Description
notify.upgrade --- --- Displayed when a filecatalyst upgrade is being downloaded.
notify.resource_not_accessible --- --- Displayed when the system can't list files and/or directories.
notify.resource_not_accessible_code Error code --- Displayed when the system can't list files and/or directories. This version of the notification includes an error code.
notify.file_transfer_complete --- --- Displayed when a file transfer has completed.
notify.file_transfer_cancelled --- --- Displayed when a file transfer is cancelled.
notify.file_transfer_error --- --- Displayed when a file tranfer has encountered an error.
notify.queue_directories_not_allowed The file path that is not allowed --- Displayed when a directory is being added to the queue, but the application is not set to allow them.
notify.queue_duplicate_multiple --- --- Displayed when files/directories are being added to the queue when more than one of them is already included in the queue.
notify.queue_duplicate The file/directory that is already in the queue --- Displayed when files/directories are being added to the queue when only one of them is already included in the queue.
notify.queue_no_files_waiting --- --- Displayed when the queue is empty, and processing is requested.
notify.queue_no_files_removed --- --- Displayed when the queue is empty, and emptying it is requested.
notify.queue_no_files_selected --- --- Displayed when the queue is empty, and removing of selected items is requested.
notify.filter_requirements_unmet The file/directory that could not be added --- Displayed when attempting to add a file to the queue that doesn't meet the filtering requirements.
notify.filter_max_files_exceeded The file/directory that could not be added The amount of files allowed in the queue Dislpayed when attempting to add a file to the queue, but the queue is already full.
notify.filter_max_filesize_exceeded The file/directory that could not be added The maximum size allowed for a single file Displayed when attempting to add a file to the queue, but the file is too big.
notify.filter_min_filesize_unmet The file/directory that could not be added The minimum size allowed for a single file Displayed when attempting to add a file to the queue, but the file is too small.
notify.filter_max_overall_filesize_exceeded The file/directory that could not be added The maximum data that can be contained in the queue Displayed when attempting to add a file to the queue, but the queue can't hold more data.
notify.filter_regex_unmet The file/directory that could not be added --- Displayed when attempting to add a file to the queue, but the regular expression filter rejects it.

Adding a Notification

Notifications can be added using the following function:

pg.utils.notifications.add( [EVENT_NAME], [MESSAGE], [OPTIONS] );
              

The function accepts three arguments. The last one is optional.

EVENT_NAME: The name of the event to which to subscribe the notification.

MESSAGE: The content of the notification. The message can use placeholders for some data that may be passed to the notification at runtime. They are {0} and {1}. The contents will change depending on the event. The argument may simply be the message string, but it can also be an object containing the "message" property as well as a few other properties. For more information, see the bootstrap-notify.js documentation. The message placeholders are not a part of the 3rd-party library - they are processed and removed before sending the message string to it.

OPTIONS: The options to use in the definition of the notification. For more information on these options, see the bootstrap-notify.js documentation.

This notification will show up at the same time as the default notification, if the default notifications are not being suppressed. Calling this function several times for the same event will add a new notification for each time it is called.

Replacing an Existing Notification

If you want to replace existing notifications with a new notification you can use this function:

pg.utils.notifications.replace( [EVENT_NAME], [MESSAGE], [OPTIONS] );
              

Like the add() function above, this function takes 3 arguments. The last one is once again optional. The three arguments are identical to those used in the add() function, described above.

The notification registered with replace will show up whenever the event is triggered. Any previous notifications that were registered before this function is called will no longer show up. In fact, only the last notification subscribed to this event will show up when the event occurs.

Subscribing to Amplify Events

Each of the events that are published with the notifications can be subscribed to through the AmplifyJS library. They can be used in conjunction with existing notifications, as well as custom notifications.

The simplest usage is as follows:

amplify.subscribe( [EVENT_NAME], [CALLBACK] );
              

At the very least, this function requires two parameters:

EVENT_NAME: This is the event to subscribe to. Also referred to as a "topic" by Amplify.

CALLBACK: This is the function to call when the event is published. This particular callback may be passed two arguments, depending on the event triggered. The callback's signature should take on this form:

function ( arg1, arg2 )
              

More information on how to subscribe to events can be found at the AmplifyJS website.

Related Configuration Settings

These settings directly affect the behavior of notifications system-wide:

Option Description
pg.config.webapp.suppressNotifications Stops the default notification messages from showing up. If set to "false", default notifications will be visible. If set to "true", default notification messages will not be used. If custom notifications have been added, they will still be visible. The default value is "false".

This setting is especially useful if you would like use a 3rd-party notification library, as opposed to the default library.

By default, a FileCatalyst logo appears on some dialogs, information bars, and navigation areas. You may wish to replace this with a logo of your own, or hide it altogether. Note: after certain updates to the product, you may need to reproduce these steps.

7.a Replacing the Logo

To replace the FileCatalyst logo image, your best approach is to modify 'css/main.css' After opening the file, search for the following rule:

.modal-footer, .filecatalystLogo, .modal-launchFailed .modal-header, .navbar-brand {
  background-image: url(../images/hs-filecatalyst-color-transparent.png);
  background-repeat: no-repeat;
}
            

Modify the background-image property to point to a different relative path or URL. Note: if the new image does not conform to the dimensions if the existing logo, it may also be necessary to modify other rules to accommodate this.

7.b Hiding the Logo

Open the file 'js/configuration.js' and locate the property showLogoOnDialogs. Set this to false in order to prevent the logo from showing. Alternatively, you can manually do the work of this property by adding the class 'no-background-image-fc-styles' to the body tag of any pages which should hide the logo:

<body class="no-background-image-fc-styles">
  <!-- the rest of the document -->
</body>
                

8 Internationalization for Upload and Download Only

The web application internationalization uses the well-known i18next JavaScript library. Full documentation can be found here: i18next.com/. The basic structure and process are as follows:

  1. On the web server that the web application is located on, find the i18n folder located at the {web.application.root}/i18n.
  2. Navigate to the i18n folder, and create (if one doesn't already exist), a new folder with the ISO-8859-1 code that matches a target locale. The locale is determined at the browser level rather than the system level. For example, if you wish to provide translation for browsers set to use Canadian English, you would create a folder called "en-ca". Brazilian Portuguese would use a folder called "pt-br". If you wish to provide a language but not a specific region, the folder will only need to have the two-character language code (for example, a generic French language file will require a directory called "fr").
  3. The default language file is found inside the i18n folder at /dev/translation.json. Copy this file into the new language folder, retaining the filename "translation.json". For example, you will now have a file at {web.application.root}/118n/en-us/translation.json.
  4. With the .json file copied into the new locale folder, change and edit the entries to match your language.

You can provide more than one language file; the application will be loaded in the following order:

  1. the full region + language (ie. "i18n/en-gb/translation.json")
  2. the language (ie. "i18n/en/translation.json")
  3. the application default (ie. "i18n/dev/translation.json")

Because they are checked in this order, a default will ultimately always be provided. Any custom translation.json files you provide will contain "overrides". For example, to provide a few English overrides for some of the UI's action buttons, you only need to provide the changed text, not the entire set of language keys.

A sample i18n/en/translation.json file with a few overrides might only contain something like the following:

{
  "webDeployment" : {
    "controlAreaUploadButton": "Upload",
    "controlAreaDownloadButton": "Download",
    "controlAreaTransferButton": "Send",
    "clearQueueButton": "Clear the List",
    "removeSelectedButton": "Remove selected items from list"
  }
}
            

Notes:

  1. The dev folder within the i18n folder will be replaced during each upgrade of the TransferAgent. Custom language folders will not.
  2. The JSON file must be edited and saved from an editor which will preserve UTF-8 encoding such as an IDE or a full-featured text-editor. Do not use applications such as "Notepad" and "Wordpad" (included in Windows) since they do not typically preserve the correct encoding.
  3. We recommend to make a copy of the translation.json file to roll back to. The application uses auto-detection, query string, or HTML tags to specify localization. We use i18next for localization; the i18next documentation will provide full information on how to localize for your users. A few common scenarios:

    • Providing an additional standard language: copy the "dev" folder and rename it to a code matching a standard region identifier. For example, for general French to be available, the copied "dev" folder would be renamed to "fr". To provide English translations that are specific to regions, you might have a set of directories: "en", "en-GB", and "en-US" for example, with "en" being the fallback for regions other than Great Britain and the U.S.A.
    • Forcing a particular language: bypass auto-detection by providing a query string on your URLs: "?setLng=fr", "?setLng=en-GB"
    • Forcing a custom language: using the query string technique, you can force language from an arbitrary folder which does not need to be named with region code standards: "?setLng=foobar"

9 Email Notifications

FileCatalyst TransferAgent can send email notifications automatically after a file transfer is complete for both uploads and downloads. The email can contain a custom message from the user as well as the list of files that were transferred. The email will NOT include a download link for the files, however a static html link can be added to the body. The static link can point to another deployment of TransferAgent which in turn could expose download with browse functionality so the uploaded files can be accessible.

9.a Prerequisites

The following settings must be completed to enable the email notification feature:

  • Outgoing email server (SMTP) settings must be set on the FileCatalyst Direct Server
  • In /js/configuration.js, email must be enabled with the "SendEmailNotification" parameter by setting it to true.
  • Additional email addresses and the body text for the email may be optionally set in the configuration.js file. These are added to the ones supplied by the user (if any).
  • Attach list of files to the email may also be enforced by setting "SentFilelistInEmail" to true. When not true, the user is given the option (disabled by default) to include such a list via a checkbox. Note that if the file transfer consists of thousands of files the size of the email may become too large.

9.b Customizing Email Pane (Upload and Download Only)

By default, email address and body set in /js/configuration.js will be automatically appended to the text entered by the end user on the email pane. It's possible to "lock" the address and body to only use the values set /js/configuration.js. In order to do this the email address, body and send file names check box can be hidden from the email pane. Below are a few HTML and CSS settings that can be applied to the email pane.

  • HTML: Add a "hide" class to the email component markup: <div id="{localFiles}OR{server1}-email" class="hide"> This will hide the entire email pane and will only use the defaults set in /js/configuration.js. This also assumes that the div markup is explicitly available in the HTML document. If it is not, it must be added in order to use the "hide" class.
  • CSS: #formGroup-emailAddress { display: none } will hide the email address from the end user
  • CSS: #formGroup-emailBody { display: none } will hide the email body from the end user
  • CSS: #formGroup-includeList { display: none } will hide the "Include list of files" check-box from the end user

10 List of Files Transferred by the User

The list of files either uploaded or downloaded by the end user can be included in the email.

To obtain the list of files programmatically (via server side script), PostURL parameter under pg.config.transfer must be set in /js/configuration.js.

Note: TransferAgent will continue to transfer files even after the browser/tab is closed. Therefore it's recommended to use the PostURL for any tasks after transfer. Using PostURL will ensure that the list of files is properly delivered to the web application even after the browser/tab is closed. Consult PostURLTutorial.html for more details.

11 Deploying to the built-in, web server

If you don't already have a web server to publish the contents of FileCatalystTransferAgentDeployment.zip, you can use FileCatalyst Direct server also as a web service. To publish TransferAgent on the built-in web server you must follow these steps:

  1. In the FileCatalyst Server Administration, go to HTTP Settings Tab and make sure that Enable HTTP Access is checked.
  2. On the same HTTP Settings Tab, note the IP address
  3. On the same HTTP Settings Tab, configure the web port. The default is 12480
  4. If your FileCatalyst Server is deployed behind NAT or Firewall, make sure that port 12480 is opened/forwarded to allow incoming TCP traffic to the FileCatalyst Server
  5. Unzip the filecatalyst folder in FileCatalystTransferAgentDeployment.zip to {INSTALL_PATH}/www where {INSTALL_PATH} is the install path of the FileCatalyst Server. For example, on Windows the default path is: C:\Program Files\FileCatalyst Server
    You must be an administrator to copy files into any folder under c:\Program Files on Windows 8 and higher
  6. Open your web browser and visit the following link: http://{IP_ADDRESS}:{PORT}/filecatalyst/ ← the forward slash at the end is required.
    • Note 1: The values for {IP_ADDRESS} and {PORT} have to be replaced with the values that match your FileCatalyst Server.
    • Note 2: If you are behind a NAT, you must use the public IP to get to the web server.
  7. Continue with the steps for either Quick Start or Detailed Instructions.

12 REST Services

12.a Enabling REST services

FileCatalyst TransferAgent is capable of accepting REST service calls in order to configure and control the application while it is running. These REST services are always enabled within the application and they can be used at any time. In addition, these REST services may also be used to build a remote control application external to the FileCatalyst TransferAgent.

12.b REST services documentation

Documentation on the REST services provided by the TransferAgent application can be viewed here

Alternatively, the documentation may be downloaded from here

12.c REST example using Swagger

In addition to the REST documentation, a web application built on the Swagger UI framework has been provided.

By using this application, you will be able to view all of the available REST services within the application, as well as examples of responses and requests that a particular call may produce or consume. In addition to these examples, the Swagger application supports the ability to configure REST call and make them directly against the application. Upon executing a REST call, the application will present you with the response for the call, as well as a small CURL example of the request that was made.


How to view the Swagger UI application

  1. Download the REST documentation package from here
  2. Navigate to the application's www directory (Example: C:\Program Files\FileCatalyst TransferAgent\www) and create a folder called "restDocs".
  3. Unzip the downloaded package into the location that you just created
  4. Access the harness by navigating to the follow URL: https://${transferagent.web.ip}:${transferagent.web.port}/restDocs/ui/index.html
    • Note: The values of ${transferagent.web.ip} and ${transferagent.web.port} will have to be replaced with values that match your TransferAgent IP and port combination. If you are using the default TransferAgent configurations, then your URL would look like the following: https://localhost.filecatalyst.net:12680/restDocs/ui/index.html

12.d REST example using Java

TransferAgent REST API Java examples built upon the Jackson and Jersey libraries are available download here

13 Running TransferAgent as a Remote Controlled Node

By default, TransferAgent will only respond to REST calls originating from 'localhost'. In some specific deployment scenarios, it is required to have TransferAgent running in remote control mode where REST calls can originate from other servers and applications. In this case, TransferAgent acts as always-on headless application and can provide file transfer services for the machine, it is installed on.

To enable the remote control mode, follow these steps:

  1. Enable port 12680 for incoming TCP on your firewall so the REST calls can be sent from other computers on the network.
  2. License TransferAgent with a license the supports the Remote Control feature.
    • Note: You can see which features the TransferAgent's current license supports by navigating to the TransferAgent configuration page, and clicking on the License tab.
  3. Configure the remote control username and password to your desired values
  4. Edit /{FileCatalyst TransferAgent Folder}/origins.json and add the IP address of the remote server that will be making the remote REST call to whitelist ex:
    {"origin": "123.123.123.123"}, make sure to follow JSON syntax correctly, pay attention for the last comma in the set. Example of the entire origins.json file, allowing 2 IP's:

                      
    {"whitelist": [
      {"origin": "1.1.1.1"},
      {"origin": "1.2.3.4"}
    ]}
                        
                    

Once these steps are completed, the TransferAgent will be able to be remotely controlled from any resource that successfully validates against the current Remote Control credentials.

Remote Control Security

All Remote Control REST services require authentication to run them. User credentials are passed in using HTTP headers. There are two ways to pass in credentials.

  • Using the RESTAuthorization header.

    This HTTP header can be used to pass in user credentials. The user credentials are Base 64 encoded and follow the following format: username:password

    JSON Example assuming username/password is admin/system:
    URL: https://localhost:12680/rs/agent/heartbeat
    Method: GET
    Accept: application/json
    RESTAuthorization: YWRtaW46c3lzdGVt

    Returned JSON:
    {"status" : "OK"}

  • Using the RESTSessionSecret header

    This is the more secured (and recommended) version for using the REST services. At least one call needs to be called using the above-mentioned HTTP Header (RESTAuthorization). A POST call to the rs/agent/remoteControlAuthorization REST service with the above header and credentials in the data content is required to get back a session secret. Once the session secret is known, it can then be used for all subsequent calls using the RESTSessionSecret header. The session secret will be valid for as long as the session stays alive on the server.

    JSON Example assuming username/password is admin/system:
    URL: https://localhost:12680/rs/agent/remoteControlAuthorization
    Method: POST
    Accept: application/json
    Content-Type: application/json
    RESTAuthorization: YWRtaW46c3lzdGVt

    Content:
    {"authorization":"YWRtaW46c3lzdGVt"}

    Returned JSON:
    {"adminUserType": "ADMINISTRATOR_USER","authorization": "YWRtaW46c3lzdGVt","sessionSecret": "1172656590452072764"}

    JSON Example using RESTSessionSecret:

    URL: https://localhost:12680/rs/agent/heartbeat
    Method: GET
    Accept: application/json
    RESTSessionSecret: 644783159662526094

    Returned JSON:
    {"status" : "OK"}

Using Transfer Agent Deployment Package

In order to use the deployment package with the remote Transfer Agent, you will have to modify the following in configuration.js:

  • Edit configuration.js, locate pg.config.localAgent config node, and change the host and port values to match those used by the remote TransferAgent
  • Example:
    pg.config.localAgent = {
       host: "https://IP_OR_DOMAIN_OF_REMOTE_TA", //do not change this value
       portDefault: 12680 //do not change this value
    };
                  

14 Running TransferAgent connected to Central

The FileCatalyst TransferAgent serves multiple purposes. As a basic usecase, the TransferAgent acts as an application that allows you to perform transfers from within your web browser. The TransferAgent is installed on your computer and the browser interacts with it to expose your file system as well as allow you to upload or download files to/from a defined FileCatalyst Server.

The TransferAgent also serves as a tool that allows you to perform transfers remotely. By connecting the TransferAgent to FileCatalyst Central, the admin within Central can access the computer which the TransferAgent is installed on and perform a transfer to/from a FileCatalyst Server defined in Central. This gives the ability to the admin to request a file from any node on the network.

Central offers a full REST API in addition, it also acts as a relay for API calls to any of the FileCatalyst nodes connected to it. This means that you can make a REST call to any FileCatalyst node through Central. This eliminates the need to open up the web (REST API) port on each node.

Since the TransferAgents can be controlled through Central, this provides the admin with the advanced functionality of being able to script remote transfers to and from TransferAgents. By offering such functionality through Central, admins can build complex workflows where files are fetched or delivered to remote locations without the interaction of users.

Here is a list of steps of how to connect TransferAgent with Central:

  1. Install and license an instance of FileCatalyst Central on your machine or an external computer. If an instance of Central already exists, you may skip this step.
  2. Login to Central as admin and go to Configuration, by clicking on your username drop down - Configuration
  3. Set the password for "Remote Connections Configuration" user. Note the default user is "monitor" and password is "12345"
  4. Open the TransferAgent configuration, and navigate to the Central Management section.
  5. Configure the values to match an instance of FileCatalyst Central that you would like to connect to. Including the "Remote Connections Configuration" user set in the previous step.
  6. Submit your changes, and wait until TransferAgent is connected to Central. If a connection doesn't occur, first verify that the values defined within the Central Management configuration are correct. If they are correct and a connection still hasn't occurred, verify that the firewall settings on your machine (and possibly Central's machine) allow for communication to occur. If either Central's port or TransferAgent's HTTP port are blocked, then you will need to adjust your firewall or port values accordingly.

Now that TransferAgent is connected to Central, you will be able to initiate transfers and configure remote Transfer Agent nodes directly from Central. You will also be able to use Central's REST proxy system to administer this TransferAgent instance programmatically via REST API. Here are the steps to make REST calls via Central to a remote Transfer Agent node using REST API:

  1. Determine the RESTAuthorization header that will be needed to authenticate your REST calls against Central. This token is a standard HTTP request header, and the value of the header is a base64 encoding of Central's current username and password, with the following format username:password. So for example, if your Central credentials are user:user, then the RESTAuthorization header value would be "dXNlcjp1c2Vy".
  2. With the RESTAuthorization now known, perform a GET request to Central's /rs/nodes REST resource. This will return the currently connected nodes within Central.
    • Example Request (Central IP = localhost, Central Port = 8080): http://127.0.0.1:8080/rs/nodes
  3. Once your TransferAgent node has been found in the current node list, you will be able to see the list of available REST services available to that node. All of these REST services use a different URL prefix then the normal TransferAgent REST services, but they function identically to the methods outlined in TransferAgent's system. If you need help with any of the REST services listed, open the TransferAgent's REST documentation and view the documentation for the service you wish to access.
  4. See REST example using JAVA on how to use the remote REST API for Transfer Agent.

Important Note: When making any REST calls against Central, you must supply the RESTAuthorization as a header in the HTTP request. If you don't supply the header (or you supply an incorrect one) Central will respond with a 401 unauthorized error message.

Central Security Model

By default TransferAgent connected to Central will allow access to any path on the local system. This means that Central Administrator or any user assigned in Central to the node will be allowed to upload/download files to/from any arbitrary location on the system running TransferAgent connected to Central.

To limit access, at least one Virtual Path has to be created in TransferAgent. Creation/Deletion of virtual Paths as well as changing of the default download path is not allowed from Central. All Virtual Path operations have to be done locally and not via Central.

15 Support

15.a Support System

Visit our support website at https://support.filecatalyst.com to view the knowledge base and to submit a ticket (Available 24/7).

If you have already submitted a Ticket and would like to send us your case files please go to https://support2u.filecatalyst.com to upload them. A valid Ticket ID will be required.

15.b Support Information

For support contact information, support hours and live chat: Visit our website at https://support.filecatalyst.com