FileCatalyst TransferAgent Usage and Deployment

Deploying to Web Server (Quick Start)

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.
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.
Choose one of the following pages based on your desired functionality: upload.html, download.html or download-button.html
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.
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.

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 a sample application. Since they are meant to run offline, repeated elements such as the main navigation are included with JavaScript includes. When using these files as a basis for a production application, efforts should be made to convert these includes to a server-side language. The HTML pages which comprise the application are index.html, upload_app.html, download_app.html, and download-button_app.html, as well as HTML provided by the scripts in the /includes directory.
- 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
  - bootstrap-theme.css - full non-minified version of the theme CSS
  - bootstrap-theme.min.css - minified version of bootstrap theme CSS, included on example pages
  - 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
- fonts - contains the actual font files (OTF, EOT, SVG, TTF, WOFF) used by web-font CSS.
  - 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.
- 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-1.10.2.js - full non-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)
    - jquery-1.10.2.min.js - minified version of jQuery
    - jquery-1.10.2.min.map - the map allow certain browser//debuggers to properly process the minified version of jQuery. Optional if using the non-mindified version, loading from CDN, or when debugging is not required
    - 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 MUST configure the application to enable connections. Configuration is done through this required script
  - 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.

Setting up HTML Document

Introduction

The basic shell for an HTML document is borrowed from initializr.com, which 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.

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">
    <title>TransferAgent</title>
    <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/bootstrap-theme.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-1.10.2.min.js"></script>
    <script src="js/vendor/bootstrap.min.js"></script>
    <script src="js/plugins.js"></script>
    <script src="js/configuration.js"></script>
    <script src="js/main.js"></script>
  </body>
</html>

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

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

bootstrap.min.css: If you choose to use Bootstrap, this stylesheet should be included before the others.
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.
bootstrap-theme.min.css: Theme files modify the default Bootstrap CSS. The included theme file provides subtle variations to colors and gradients. You may exclude this file, modify it, or include an alternative Bootstrap theme file from another source.
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. These are described in detail in the HTML API section. The bare minimum markup for a fully-functioning upload transfer area is:

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

JavaScript Includes

The FileCatalyst TransferAgent uses an extensive API, the usage of which is described in the JavaScript API section. 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.

/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.
/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.
/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).
plugins.js: JavaScript plugins used throughout the application for things such as Growl notifications and a unified localStorage API.
configuration.js: configuration of application behaviour and node connections.
main.js: the main application itself, containing all methods required to process and display TransferAgent interactions.

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.

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,
    remoteDirectory: "",
    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>

For more information on using the key/ID for HTML elements, read the HTML API section of this document.

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
remoteDirectory	accepts: string default: ""	Set a remote directory within the configured server account. If the directory does not already exist, it is created. Uploaded files will be written to this directory. For Download interfaces, user will start with a listing of this directory (even if it is empty and newly-created).
lockInitialDirectory	accepts: boolean default: false	If a "remoteDirectory" value is set, the user will start in that directory. For Download interfaces, this means that the "remoteDirectory" 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.

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"]

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"

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 <h2> 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 as a string OR function OR variable pointer to a predefined function OR any arbitrary JavaScript ex:javascript:alert('foo') 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.
doAfterError	accepts: URL as a string OR function OR variable pointer to a predefined function OR any arbitrary JavaScript ex:javascript:alert('foo') default: ""	If set, an action to take upon completion of a transfer that contained errors. Behaviour is per doAfterSuccess, described above.
doAfterCancel	accepts: URL as a string OR function OR variable pointer to a predefined function OR any arbitrary JavaScript ex:javascript:alert('foo') default: ""	If set, an action to take upon cancellation of a file transfer. Behaviour is per doAfterSuccess, described above.
doAfterOtherError	accepts: URL as a string OR function OR variable pointer to a predefined function OR any arbitrary JavaScript ex:javascript:alert('foo') 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 as a string OR function OR variable pointer to a predefined function OR any arbitrary JavaScript ex:javascript:alert('foo') 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:

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

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.

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.

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.

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:

Provide markup within each item found in pg.config.customIcons
Change the "key" of this set to whatever you wish. In pg.config.customIcons a sample empty set is pre-configured as "custom1"
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.

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, which are all required. 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.

HTML Markup API

The underlying JavaScript API may optionally take advantage of layout characteristics determined by the markup itself. Every configured node, including the local file system, has a related "ID" which is set in the JavaScript configuration. By referencing this ID in the markup, you can granularly determine where each widget appears. The loose connection between the HTML and JavaScript forms an HTML API layer.

How it works

The JavaScript will search the rendered document in order to decide where to place UI components. It follows this order:

Looks for an element with an ID attribute that matches the ID of a configured node. Local filesystem nodes have the ID "localFiles". This node is considered the default container for the UI components. If such an element is not found, no UI will be rendered.
For each component type, the script will use the pattern "{id}-{componentType}" to find an element with a matching ID attribute. If found, it will use that element to render the component. For example, the queue for "server1" would be "server1-queue".
If the component-specific element is not found, one will be created and appended to the default container.
If you wish to hide a component until it is needed, add "hide" to the class attribute. For example, <div id="server1-info" class="hide">

Available Components

There are a number of UI components available to be rendered. For example to render the local file list the div id must be: localFiles-list for the remote file list the div id must be: server1-list. They are processed (and if need be, added to the default container) in the order below:

name	markup substring	Function
File System Listing Heading	heading	This is a heading ("h2" if rendered by FileCatalyst) which describes the file listing. If rendered by the application automatically, it will be placed above the file listing and will follow be "Local Files" or "Remote Files: {name}" where {name} is either the configured name or the remote node's "ID".
File System Listing	list	This is a filesystem "browsing" widget which is ultimately a list of the files available at the configured node. At render, a table is created showing a list of the files and directories, along with controls for sorting, selecting, and navigating items in the file system
Controls	controls	A series of controls related to both the queue and the file listing. These are rendered as a series of buttons. Language may be updated in the localization file, but by default are: "Add selected files" (checkbox-selected items from the file system list, added to the transfer queue), "Remove selected from queue" (checkbox-selected items in the queue, removed from the queue), "Clear Queue", and "Upload/Download Queue" (initiate transfer).
Transfer Queue	queue	Before an item can be transferred, it must be added to the file queue. This component shows a list of items that are currently queued for transfer. The queue may be modified by using the provided controls.
Transfer Status	info	This component contains information about the status of ongoing transfers. The specific fields seen are configurable in configuration.js, but typically include such information as the current filename, the average rate, and a transfer progress bar. In the sample pages, this area uses the "hide" class and becomes visible only when transfer is initiated.
Email Notification Options	email	This component will only appear if the application is configured to send email notifications. It contains a simplified email form which will request the FileCatalyst Server to send out an additional notification email to the specified recipients, with the specified contents.

Examples

The following examples assume that there is a remote node configured with the ID "server1". Local fileysystem always uses the ID "localFiles".

Minimum download UI:

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

Minimum upload UI:

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

Most components in the default location, but transfer status in a specific div:

<div id="server1"></div><!-- contains most components -->
...intervening markup is possible here...
<div id="server1-info"></div><!-- contains the transfer status info -->

Using Bootstrap grid to separate the file list browser into one column and the rest of the components into another. This is the model used by the sample applications

<!-- Row containing the output of the FileCatalyst application -->
<div class="row">
    <div id="server1" class="col-lg-6">
      <div id="server1-list"></div><!--optional, since it will end up here by default anyhow-->
    </div>
    <div class="col-lg-6">
      <div id="server1-controls"></div>
      <div id="server1-queue"></div>
      <div id="server1-info" class="hide"></div>
    </div>
</div>

Internationalization

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:

On the web server that the web application is located on, find the i18n folder located at the {web.application.root}/i18n.
Navigate into the i18n folder, and create (if one doesn't already exist), a new folder with the ISO-8859-1 code that matches your current locale. For example if your current locale is 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 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").
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.
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:

the full region + language (ie. "i18n/en-gb/translation.json")
the language (ie. "i18n/en/translation.json")
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:

The dev folder within the i18n folder will be replaced during each upgrade of the TransferAgent. Custom language folders will not.
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.

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.

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.

Customizing Email Pane

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

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 programatically (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. Therfore it's recommended to 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.

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:

In the FileCatalyst Server Administration, go to HTTP Settings Tab and make sure that Enable HTTP Access is checked.
On the same HTTP Settings Tab, note the IP address
On the same HTTP Settings Tab, configure the web port. The default is 12480
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
Unzip the filecatalyst folder in FileCatalystTransferAgentDeployment.zip to {INSTALL_PATH}/www where {INSTALL_PATH} is the install path of the FileCatalsyst 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
Open your web browser and visit the following link: http://{IP_ADRESS}:{PORT}/filecatalyst/ ← the forward slash at the end is required.
Example for localhost: http://127.0.0.1:12480/filecatalyst/ You will see TransferAgent Welcome Screen.
If you are behind NAT, you must use the public IP to get to the web server.
Continue with the steps for either Quick Start or Detailed Instructions.

Running TransferAgent in headless insecure mode

By default TransferAgent will only respond to REST calls originating from 'localhost'. In some specific deployment scenarios, it's required to have TransferAgent running in insecure 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's installed on. The reason it's insecure is that REST calls will now be accepted from any outside computer to either request an upload or download of any arbitrary file on the machine TransferAgent is running on. Many types of automation workflows might require TransferAgent to run in this mode. To enable insecure headless mode follow these steps:

Enable port 12680 for incoming TCP on your firewall so the REST calls can be sent from other comupters on the network.
In /{FileCatalyst TransferAgent Folder}/fcta.conf add the following line: headless.and.insecure=true following the convention of other properties set in that file.
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 a the entire origins.json file, allowing 2 IP's: {"whitelist": [ {"origin": "1.1.1.1"}, {"origin": "1.2.3.4"} ]}

Note that the last entry in the list doesn't contain a comma

Start TransferAgent from command line using -headless-and-insecure flag ex:

			  cd /{FileCatalyst TransferAgent Folder} 
			  java -jar FileCatalsystTransferAgent.jar -headless-and-insecure

All REST calls must contain RESTAuthorization header set to "admin:system" base64 encoded
All REST calls must set Content-Type and Accept headers to application/json

FileCatalyst TransferAgentUsage and Deployment

Table of Contents