Search this site

Disclaimer

The "triDeveloper" site and content are neither affiliated with nor sponsored by TRIRIGA, Inc. "TRIRIGA" is a trademark of TRIRIGA, Inc. All trademarks used on this site are the property of their respective owners.

Download: triftp-1.1.zip
"triFTP" Using the Content-Based APIs

Managing Document Manager Through FTP with the New BusinessConnect Content APIs

Up until recently, TRIRIGA did not provide a means of interacting with binary content through the BusinessConnect API.  However, new versions have introduced a set of Content-based APIs that can be leveraged to open up several new opportunities:
  • Manipulate HTML Note fields on records
  • Upload and download content to binary fields
  • Modify Image fields on records
  • Manage Document records, by uploading or download content either directly or to/from staged locations on the application server
In this article, we briefly discuss the new Content APIs and present a "gateway" application which provides an FTP interface to Document Manager.  This allows you to use your favorite FTP client to manage documents stored within the TRIRIGA application.

The Content APIs

The new API function calls are detailed in the BusinessConnect Technical Specification documentation from TRIRIGA (available on Elite, login required); in summary, they are:
  • getContentFieldsDefinition - Retrieves metadata information about the available content-based fields on a record.  This includes any Binary, Image, or Note fields.  Documents are a bit different, as the record itself "contains" the content (there is no individual content field).
  • getContentLength - Retrieves the content size of the field or Document data in bytes.
  • getChecksum - Calculates the checksum of the content, which can be used to detect file corruption.
  • copy - Copies the content from one Document record to another.
  • delete - Deletes the content from a Document record.
  • upload - Uploads data to a content-based field or Document record.  The data is supplied in the method call itself.
  • download - Downloads data from a content-based field or Document record.  The data is returned with the method call result itself.
  • uploadFrom - Uploads data to one or more Document records from files staged on the application server.  This can be used to move large amounts of data that would not be practical through a direct method call.
  • downloadTo - Extracts content from one or more Document records into files on the application server filesystem.  As with uploadFrom, this API allows you to work with larger data sets than would be feasible with a direct download method call.
The application we're looking at here basically wraps a small FTP server around some of the core record operations:
  • copy - Used when a Document or Folder is moved to a different location in the hierarchy (a trivial rename operation is just done via a saveRecord call, but reparenting a record within the Folder hierarchy essentially requires copying the subtree and then deleting the source).
  • delete - Used to delete a Document or Folder (the content is deleted, followed by triggering the DELETE and FINAL_DELETE actions on the Document/Folder record itself).
  • getContentLength - Used when retrieving basic object information for an FTP directory listing.
  • uploadFrom - Files that are uploaded are staged to a temporary file on the application server, then moved into TRIRIGA using the uploadFrom call.  This allows the FTP server to effectively accept larger files than would be possible with a direct upload call.
  • downloadTo - Similarly, downloaded files are extracted from TRIRIGA into a temporary file which is then served to the user.  The downloadTo method is used to pull the content out of TRIRIGA into the temp file.
The system also uses runDynamicQuery/runDynamicQueryContinue to traverse the Document/Folder hierarchy.  Additionally, it leverages the old API1 doBoRecordAction call instead of the BusinessConnect triggerActions method when deleting the records; the new function only allows an operation if it is available ("Default Display") on the record's GUI, which "Delete" and "Final Delete" are not.  Using the old API allows the actions to be invoked without modifying the out-of-box Document/Folder GUIs.

Installing the FTP Server

Installing the middleware application is fairly straightforward (instructions below are for JBoss, other application servers should have similar procedures):
  1. Download and extract the zip file.
  2. Copy the "TRIFTP.properties" file into the TRIRIGA "config" directory (alongside TRIRIGAWEB.properties and the other configuration files).
  3. Edit TRIFTP.properties; the settings are as follows:
    • ftpPort - Specifies a different FTP port if needed (the default is port 21, which is the standard FTP control port)
    • tririgaServer - Indicates the server name and port for the TRIRIGA application server.  Note that the middleware server will need to be deployed on the same server specified here (in other words, "localhost" is probably what you want).  This is due to the fact that the middleware service uses the uploadFrom/downloadTo method calls which reference the application server's own filesystem.
    • ftpGroup - Specifies a group whose members are granted access to the FTP service.  Users which have membership in this group will be able to log in to the FTP server.  By default, this is set to "Admin Group".
  4. Copy the "ftp.war" application archive to the "server/all/deploy" subdirectory under your JBoss server installation (probably "jboss-4.2.1" under your TRIRIGA installation).  It should deploy automatically, and within a couple of seconds you should be able to point your web browser at "http://yourappserver:8001/ftp/ftp" and receive a message that the triFTP service is running.

Using the FTP Service

The middleware service can be accessed in the same fashion as any FTP server; using your favorite FTP client, just connect to your application server and login with your TRIRIGA credentials (remember, you'll need to use an account which is a member of the group specified in the "ftpGroup" setting).

Under Windows, you can create a new "Network Place" for this FTP service:
  1. Open Windows Explorer, and open "My Network Places".
  2. Double-click on "Add Network Place".
  3. When prompted for a service provider, select "Choose another network location" and click Next.
  4. In the address field, enter "ftp://yourappserver" (plus a port if you specified something other than 21 in the "ftpPort" setting).
  5. Click Next, and when prompted enter your TRIRIGA application username and password.
You can then drag and drop files and folders between the Network Place and your other local folders/files.

Some caveats/notes:
  • The filenames listed on the FTP site are the record names of the Documents, not the underlying file names.  For example, if you have an image file "mypic.jpg" stored in document manager as "\ROOT\TRIRIGA\My Picture", it will be listed as a file named "My Picture".  Files uploaded through the interface will be created with a record name matching the uploaded file name.
  • The FTP middleware doesn't check-out/check-in the underlying Document record on revision; the content is simply updated.

Additional Resources

The source code for the solution presented in this article is available at the triDeveloper code repository:


Files