Documentation for fileXHub 1.2 Enterprise Edition

fileXhub™ 1.2 Enterprise Edition

(previously Protocol Proxy)

1. Overview

For more information contact us via EMAIL or Phone: 314-635-6351, for more complicated solutions, including but not limited to:

  • Business to Business integration (B2B)
  • Message transformation and mapping services
  • ERP connectivity (SAP, Oracle, etc.)
  • Enterprise Application Integration (EAI)
  • Managing trading partner communities
  • Support contracts
  • Custom application development



1.1. Introduction

This guide provides documentation for running fileXhub™ from Amazon EC2 Marketplace. It is assumed that you have already started an instance of fileXhub™. An EC2 security group should have automatically been created when you started your new instance. This security group opened specific TCP ports to your EC2 instance that are needed to run fileXhub successfully. Please note that in addition to these rules that iptables has been installed on the instance and is being used to lock down the ephimeral port range that is listed below.

These TCP ports are:

Port Use
22 SSH
80 HTTP(Admin Web Interface, User Portal Web Interface)
21 FTP
1024 - 65535 FTP



1.2. fileXhub™

fileXhub™ (BIT file transfer hub) is a lightweight replacement to standard protocol services (FTP, HTTP, HTTPS) that is deployable in the DMZ. This allows you to eliminate the need to open "holes" in the firewall of the secure internal network while still able to service a wide variety of standard messaging protocols. It also secures your data by encrypting the data before storing it in an encrypted database.



1.3. Managed File Transfer (MFT)

BIT offers a secure Managed File Transfer solution for moving financial transactions, critical business files, large documents, XML, and EDI transactions over the Internet and private IP networks.



1.4. Business to Business (B2B) Integration

Business Integration Technology creates custom business-to-business (B2B) integration solutions. We have extensive experience and proven success in applying our knowledge in a variety of industries. Our Capabilities demonstrate expertise across business areas, data standards, and communication protocols.

Most common business documents can be exchanged electronically, including purchase orders and acknowledgments, manifests, bills of lading, shipping confirmations, shipment status or tracking data, invoices, and financial transactions. Electronic processing and transmission of business documents saves time and labor by reducing the use of phone and fax, and by reducing human error.



1.5. Enterprise Application Integration (EAI)

Business Integration Technology also creates custom enterprise application integration (EAI) solutions. We have extensive experience and proven success in applying our knowledge in a variety of industries. Our Capabilities demonstrate expertise across business areas, data standards, and communication protocols. BIT applies the same knowledge, skills and best practices to EAI projects as are delivered in a B2B project.

Application integration solutions route messages between enterprise applications such as legacy systems, packaged applications, or homegrown custom applications. Each of these applications is usually built around a proprietary data model, and each application expects to receive messages that conform to its internal data format. Applications using different data formats communicate with each other using a special filter, a message transformer, to translate one data format into another.


2. Release Notes


1.2.0 Version

  • Moves Enterprise edition to AWS Infrastructure



Prior Versions of Protocol Proxy

1.1.3 Version

  • Rebranded as fileXhub™ (formerly Protocol Proxy)
  • Divided into 3 editions:
    • Personal - Web portal only
    • Professional - Web portal + FTP
    • Enterprise - Web portal and FTP + HTTP POST + admin Web services


1.1.2 Version

  • Enhanced Documentation


1.1.0 Version

  • Configurable processing of large files - 1+ Gb


1.0.2 Version

  • User Administration
    • Timestamp for last login
    • Audit log per user, in addition to full consolidated audit log


0.9.1 Version

  • Enhanced Documentation


0.9.0 Version

  • Initial Release


3. Quick Start

After completing this entire Quick Start section, you will have a fully functioning installation of fileXhub™. You will then be ready to proceed to the Trading Partner tutorial.



3.3. fileXhub™

fileXhub™ has been preinstalled and is automatically started when your EC2 instance is booted. The installation directory of fileXhub™ on your EC2 instance is located in /usr/share/tomcat6/webapps. For help logging into your EC2 instance using SSH please refer to the Amazon EC2 documentation located here : EC2 Connection. It is recommended to associate an Elastic IP Address for your instance, this is mandatory if passive mode FTP will be used by your trading partners. Refer to Appendix 1 : Passive Mode FTP


NOTE: The web interface for fileXhub™ runs on Port 80 and FTP on port 21. Starting/Stopping/Restarting fileXhub™ will require root access.


3.3.1 fileXhub™ Login

We will begin by logging into the fileXhub™ Admin web interface. The admin interface is your tool for managing the user profiles of those with whom you want to exchange files. For example, you may want to receive electronic purchase orders from your customers, and then send them electronic invoices. You would use the fileXhub™ Admin interface to manage each trading partner's access to fileXhub™ to send orders to you and receive invoices from you.


To Login: http://Your EC2 Domain Name or Elastic IP Address/admin

username password
admin (AWS EC2 Instance ID)



Your initial password is the instance ID assigned to your new instance by Amazon AWS. You will see this id on your EC2 Management Console by clicking 'Instances'.

After a successful login you will see a screen similar to below.

If this fails you probably did NOT start fileXhub™ with the required privileges.



3.3.1.1 Change ADMIN password

Click on the change link next to the ADMIN user under the Password column. Please enter a new password to secure fileXhub further.



3.4. Test Install

We will create a new user to confirm that the installation and start-up completed successfully. We will use this new user ID in the Trading Partner tutorial.

Verify that fileXhub™ is running and that you are still logged in from step 3.3.1.

Fill out the User form and click submit:

  • Set username to test.
  • Set password to password.
  • Set Contact Name to Trading Partner.
  • Set Company Name to Tutorial.
  • Set Email to {any valid email address}.
  • Set Phone to 3146356351.

username and password are mandatory. The other fields are optional and are not required for this test. They are for information purposes only.


If your new user "test / Trading Partner" is successfully created, the screen will refresh and you will see a result similar to below. You will see "user created successfully!" at the top, and it will be listed in the Current Users table at the bottom of the screen.


This is proof your installation is working. You are now ready to progress to the next section, the Trading Partner tutorial.


4. Trading Partner Tutorial

File transfer with your trading partners is made very easy with fileXhub™. For both inbound messages (Trading Partner to you) and outbound messages (you to Trading Partner), simply create a username & password for the Trading Partner in the fileXhub™ Admin interface. This will enable you to manage the settings in fileXhub™ and EME for the sending and receiving of messages for that Trading Partner.

In fileXhub™, "inbound/in" and "outbound/out" always refer to the point of view of the Enterprise (you), never from the point of view of the Trading Partner. "Inbound" always refers to messages coming from the Trading Partner TO you; "outbound" always refers to messages going FROM you to the Trading Partner.



4.1. Trading Partner Example

In this section, we will use the Trading Partner that we added in section 3.4 to confirm that fileXhub™ was installed correctly.

Verify that fileXhub™ is running before proceeding with this tutorial.


4.1.1. Send Inbound Message

Now we can test sending an inbound message as the fileXhub™ trading partner we created, test. We are going to use the fileXhub™ Web Portal, which is the web interface that is available to your trading partners. A real trading partner can use any of the protocols supported by fileXhub™ Professional or Enterprise (HTTP POST, FTP, Web Services) without any changes - they do not have to use the portal.


Login to the fileXhub™ Web Portal with our newly created user: http://Your EC2 Domain Name or Elastic IP Address/portal

username password
test password


Click the Upload tab to select a file to send to fileXhub™.

You will see a screen similar to below.

You will specify what type of file it is, either binary or text. Let's send the text file that is posted on our Download page as a zip archive. It is an EDI standard 810 invoice. Using the Browse tool, select the file 810.edi from the directory where you extracted it from the zip archive. Change the Content Type selection to Text.

Microsoft Word documents, Microsoft Excel spreadsheets, and PDFs are actually binary file types.

When you have selected the file, click upload.

After the upload, the screen refreshes to view the Inbox tab. You will see the file listed, similar to the screen below.



Now let's check the admin interface that we used in section 3.4 where we can verify that the 810.txt file uploaded by the trading partner is available for you to pick up. Click the Messages tab and you will see the file where you can manually open or download it, or delete it. Click the Audit tab to see a log of the events that have taken place for that file. The audit log is useful for confirming transaction events with a trading partner.

You can integrate with fileXhub™ by using any of the current methods you have available in your enterprise environment that utilize a RESTful web service.

The following two screen shots show the Messages tab and the Audit tab.





4.1.2. Send Outbound Message

Next we will test sending a message outbound to our Trading Partner, test by using the admin interface to upload a file. Make sure you are still logged in to the admin interface, and click the Upload tab to send the same 810.txt file out to the trading partner. Make a copy of the text file and give it a new name, such as 810-outbound.txt, so you can distinguish between the 2 files.

Change Content Type to Text, Direction should be Out, and enter TEST in the Username field. Click Browse and select the 810.text file from your system directory and click upload.

Your screen will look similar to the one below.

After the upload, the screen refreshes to view the Messages tab. You will see the file listed, similar to the screen below.

Now let's check the portal interface that the trading partner uses, and we can verify that the 810-outbound.txt file you uploaded is available for the trading partner to pick up. Click the Outbox tab and you will see the file where you can manually open or download it, or delete it.

You will see a screen similar to the one below.


This is the end of the tutorial. You have learned how to:
  • add a Trading Partner
  • send files inbound - from a Trading Partner
  • send files outbound - to a Trading Partner


5. Technical Details

  • fileXhub™ has two web front ends, one for administrators (http://Your EC2 Domain Name or Elastic IP Address/admin) and one for trading partners (http://Your EC2 Domain Name or Elastic IP Address/portal)
  • fileXhub™ uses two ports (HTTP:80, FTP:21) that require either root access to start properly.
  • fileXhub™ internally is broken down into different parts; all of the log files are in the following location:
      /usr/share/tomcat6/logs
  • fileXhub™ is run as a background process, so to shutdown you need to run a script. Please reference the Stop fileXhub™ section for details.
  • fileXhub™ runs in the Apache Tomcat container. If you have another default install of Tomcat running on your system, you may have problems with start and stop scripts. It will require you to change some administration ports in one of your Tomcat installs.



5.1. Restart fileXhub™

Verify that you have root access or have proper sudo privileges


5.1.1. Linux / Unix

From the command prompt or terminal:

If you are root, type:

  /etc/init.d/tomcat6 restart

Otherwise type:

  sudo /etc/init.d/tomcat6 restart

fileXhub™ will restart up in the background



5.2. Start fileXhub™

Verify that you have root access or have proper sudo privileges


5.2.1. Linux / Unix Command

From the command prompt or terminal:

If you are root, type:

  /etc/init.d/tomcat6 start

Otherwise type:

  sudo /etc/init.d/tomcat6 start

fileXhub™ will start up in the background



5.3. Stop fileXhub™

Verify that you have root access or have proper sudo privileges


5.3.1. Linux / Unix

From the command prompt or terminal:

If you are root, type:

  /etc/init.d/tomcat6 stop

Otherwise type:

  sudo /etc/init.d/tomcat6 stop

fileXhub™ will restart up in the background



5.4. Advanced Setup

5.4.1. FTP Firewall Rules

Exposing FTP securely requires additional firewall rules. These rules have already been applied to your EC2 instance. The default communication port for FTP is port 21, however FTP also uses random ports in the Dynamic Port Range for short periods of time for transmitting data. Most modern firewalls have algorithms so you don't have to open all of the whole Dynamic Port Range, and it will only allow traffic on the specific port needed for the short duration that it is used, then close it again. This isn't specific to the fileXhub™ implementation of FTP; all FTP servers require these rules.



5.5. Setup fileXhub™ SSL

Click here for very thorough documentation on how to set up SSL for Tomcat.

You will need to edit server.xml once you have created a keystore:

/usr/share/tomcat6/conf/server.xml



5.6. Features

fileXhub™ is compartmentalized into different web applications deployed into a single Apache Tomcat Web Container. The default web port is 80, so it will require root privileges to start.


5.6.1. fileXhub™ Admin

fileXhub™ Admin is the Administration Web Portal: http://Your EC2 Domain Name or Elastic IP Address/admin

You can add/edit users, upload, download, and delete messages for any fileXhub™ user.

Default access:

username password
admin password


5.6.2. fileXhub™ Portal

fileXhub™ is the User Web Portal: http://Your EC2 Domain Name or Elastic IP Address/portal

It is accessed by the external Trading Partners so they can upload, download, and delete messages for only their fileXhub™ user.


5.6.3. FTP

FTP is a standards-based FTP Server external Trading Partners can use to upload, download and delete messages for only their fileXhub™ user. By default it is run on port 21, with data ports being from the dynamic range.

It has been tested with many clients across all operating systems, however that does NOT mean it will work with every client. FTP has been around for a long time and some legacy clients may have issues.

Note: fileXhub™ requires an FTP client that supports IPV4.

Click for more information about FTP.


5.6.4. HTTP/S

There are two HTTP/S REST Web services available, one for Trading Partners, and one for EME (Internal Applications). The external REST API only allows fileXhub™ users to upload, download, and delete their own messages. The Administration REST API is used so an internal system can act upon messages for all fileXhub™ users.

Click for more information about HTTP.
Click for more information about HTTPS.
Click for more information about REST Web services.



A. Appendix


A.1. Passive Mode FTP

Most users will want to take advantage of passive mode FTP in fileXhub™. It is important that you have created and associated an Amazon Elastic IP Address to your EC2 instance. Please refer to Amazon Elastic IP for help setting this up.

From the command prompt or terminal:

As root, edit the following file:

/usr/share/tomcat6/webapps/ftp/ftp.properties

Change the following values :

Property Value
override.ip true
external.ip.address Your Elastic IP Address

Restart fileXhub™ by following the instructions in Section 5.1


A.2. Admin REST

You can poll fileXhub™ for messages from your users. The Integrated flag on a user indicates to fileXhub™ whether
that user should be included in the list-all manifest.

The admin REST interfaces uses Basic Authentication.

Default access:

username password
admin password
Get All Files

HTTP GET http://Your EC2 Domain Name or Elastic IP Address/proxy-admin-rest/admin/list-all

Example XML manifest in the response:


<?xml version="1.0" encoding="UTF-8"?>
<list size="1">
  <record id="2" num="0" size="27367" username="TESTUSER">testfile.json</record>
</list>

By parsing the manifest you can now perform more functions based on the username and id of a particular record.

Get File by Record Id

HTTP GET http://Your EC2 Domain Name or Elastic IP Address/proxy-admin-rest/username/id

The response will contain the file either text/plain or in binary format based on how the user originally uploaded the file.

Remove File by Record Id

HTTP DELETE http://Your EC2 Domain Name or Elastic IP Address/proxy-admin-rest/username/id

Until the admin user successfully DELETEs a record id it will continue to be included in the list-all manifest.

Upload a File for a Specific User

HTTP POST http://Your EC2 Domain Name or Elastic IP Address/proxy-admin-rest/username


A.3. User REST

A user can poll fileXhub™ for messages from you.

The User REST interfaces uses Basic Authentication.

Default access:

username password
username password
Get All Files

HTTP GET http://Your EC2 Domain Name or Elastic IP Address/httproxy/list

Example XML manifest in the response:


<?xml version="1.0" encoding="UTF-8"?>
<list size="1">
  <record id="3" num="0" size="11614" username="TESTUSER">http_TESTUSER_9hZCp8Xqh0.dat</record>
</list>

By parsing the manifest you can now perform more functions.

Get File by Record Id

HTTP GET http://Your EC2 Domain Name or Elastic IP Address/httproxy/id

The response will contain the file either text/plain or in binary format based on how the user originally uploaded the file.

Remove File by Record Id

HTTP DELETE http://Your EC2 Domain Name or Elastic IP Address/httproxy/id

Until the user successfully DELETEs a record id it will continue to be included in the list manifest.

Upload a File

HTTP POST http://Your EC2 Domain Name or Elastic IP Address/httproxy