FileCatalyst TransferAgent Usage and Deployment

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.

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.

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.

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

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.

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.

Overriding The FileCatalyst Logo

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.

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"

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.

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.

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.

REST Services

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
  };
                

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.

Support