What is it?

The Documentum ftpIntegrator (version 4.2.4) allows client programs to transfer files into and out of docbases by means of the standard File Transfer Protocol (FTP). This provides a simple, standard mechanism for allowing networked access to and updating of the contents of a docbase without having to set up any complex infrastructure. Since FTP has been around for a long time just about every species of system and browser comes complete with FTP client software. This means that, by configuring ftpIntegrator, exporting, importing and browsing of the folder structure of a docbase can be done at any host. [Unfortunately, Internet Explorer 5.0’s implementation of FTP does not interoperate with ftpIntegrator.]

The ftpIntegrator also has a lot of built-in support for specialized client programs such as MacroMedia’s DreamWeaver and Allaire’s HomeSite, which can use FTP to push a directory tree of web-pages onto a WebPublisher docbase.

What can it do?

When used with a WebPublisher docbase, ftpIntegrator provides facilities to create new documents in the docbase according to a preconfigured XML ruleset. These rules allow the object type, lifecycle and directory path to be specified, along with any pre-initialized unique attributes which may be wanted.

When used with a 4i docbase, a user may get and put documents in the docbase. If putting a document into a docbase where there is already an object with the same name and folder-path, a new minor version of the object will be created. There is no support for checking-out a document.

How does it work?

The ftpIntegrator does not need to be running on the same machine as the target docbase or docbases. It operates as a stand-alone process which listens for incoming FTP requests arriving across the network and uses the information supplied by the calling FTP client to establish a Documentum session with a docbase. Once established, the ftpIntegrator will translate requests received from the client into standard calls to the docbase by using Documentum Foundation Classes (DFC).

This architecture allows ftpIntegrator to provide concurrent FTP access for several different FTP clients to many different docbases running on multiple host machines. Since ftpIntegrator is acting as a translator there is no requirement to set up complicated authentication mechanisms at the host on which it runs – it will try to establish a connection with a docbase using the information supplied by the client. If the docbase does not exist, or the username does not exist or the password is invalid or if for any other reason a connection cannot be established then the ftpIntegrator just hands that information back to the client program. Once the session is established the determination of just what the user can see and do is controlled by the access controls within the docbase – ftpIntegrator simply makes the request and returns the results. This helps to keep things simple.

How is it Installed?

Documentum supplies several implementations of ftpIntegrator. These are available for:

• Windows NT
• Windows 2000
• Solaris
• HP-UX

Architecture-specific documentation is supplied along with the actual product binaries.

For this article the Windows 2000 implementation was used. Installation was straitforward – just following along with the documentation which in this case equated to ‘unzip the archive in a temporary directory and then run setup’. Since ftpIntegrator needs the Documentum Foundation Classes (DFC) in order to operate, the installation process checks to see whether this is available and prompts for installation if it is not. For ftpIntegrator 4.2.4 DFC version 4.2 is required, so the installation upgrades any previously installed DFC as required.

Configuration

Upfront decisions

Before starting to configure ftpIntegrator, some decisions need to be taken.

First of all, it is necessary to decide whether ftpIntegrator is going to interface with Documentum 4i docbases or with WebPublisher docbases. These require different configurations and there is apparently only a single, global setting for this value. More bluntly, ftpIntegrator may serve files from multiple 4i docbases OR multiple WebPublisher docbases, but not at the same time.

Secondly it is sensible to decide whether ftpIntegrator is going to serve files from just a single docbase or from several docbases. There is slightly less flexibility available for configurations which serve multiple docbases (of whatever kind), but this may not be an issue for many establishments.

Configuring

Once installed there are four main configuration files which need tweaking for a specific installation. Prototypes of these files are found in the installation directory. They are:

• ftpConfig.xml
• WebPublisherDocType.conf
• FTPServer.conf
• FileFormatType.conf

Since ftpIntegrator can be configured to serve files from several docbases, the class=”path”>ftpConfig file may include several xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>docbase tags to establish different behaviours for these different docbases. For an individual docbase an arbitrary number of xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>rules tags may be supplied, which are used to select amongst the objects with the docbase. Once selected the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>object_config tags are used to determine what attributes should be set (if this is a ‘put’ to the docbase) and where the new object should reside in the docbase cabinet structure.

ftpIntegrator 4.2.4 may be configured in either WebPublisher or 4i Docbase mode. Many of the available configuration settings are only meaningful when configured in WebPublisher mode; these settings are ignored when it is configured in its alternative mode.

WebPublisherDocType.conf is apparently only used in WebPublisher mode. It controls the object, folder and cabinet type that objects being created or imported into the docbase should be given. These defaults apply when no explicitly configured rule applies, or when a new folder or cabinet is created.

FTPServer.conf controls the type of docbase being addressed (4i or WebPublisher), the port on which ftpIntegrator will listen, idle timeout, root directories and other values.

FileFormatType.conf is an extensible database used to map between external and internal file types. Documentum advises against removing any of the preconfigured entries, but installations which use custom filename extension mappings will need a place to tell ftpIntegrator about them. This is the place.

In general, whenever a configuration file is modified, ftpIntegrator needs to be stopped and restarted before these changes will take effect.

ftpIntegrator has a built-in trace facility which may be used to troubleshoot configuration and other issues. Since ftpIntegrator runs as a service under Windows 2000 this trace information is not available unless explicitly requested by navigating to the services menu and checking the check-box to indicate that the service should be allowed to interact with the desktop. Once this has been done (and the service restarted) then a console window will appear with the trace information.

Using ftpIntegrator

With ftp clients it is always necessary to authenticate yourself. With ftpIntegrator this is also the time when you get to specify the actual docbase that you wish to work with. Working with the traditional FTP client on Windows 2000 this goes as follows:

C:>ftp bugs
Connected to BUGS.
220 FTP Server Ready
User (BUGS:(none)): test@test_dev
331 Password Required
Password:
230 User logged in
ftp>

An alternative syntax is also supported for specifying user and docbase – <docbase><user>. Where your class=”path”>FTPServer.conf file is configured with a single, named docbase then it is not necessary to specify the docbase name since this will be filled in for you if you dont supply it.

Interestingly, even if your class=”path”>FTPServer.conf file is set up for a single docbase only, ftpIntegrator will sucessfully authenticate you to any docbase which is registered with the docbroker known to the host on which ftpIntegrator is running, if you use the above syntax. This may or may not be a good thing.

Once logged-in you will be placed in the ‘root’ directory configured in class=”path”>FTPServer.conf. However, this does not make the rest of the docbase unavailable to you – it’s just the place you start. Changing directory to (say) ‘/’ or ‘/Temp’ works just fine. Also, it was not possible to ‘put’ any documents until after changing directory, if this ‘root’ directory is configured to be anything other than ‘/’.

ftp> put junk.doc
200 Command successfull
150 File okay, ready to transfer
######
221 Service closing connection
ftp: 19456 bytes sent in 0.00Seconds 19456000.00Kbytes/sec.
ftp>

Using the configuration below this created a new document of type ‘web_content’ in the current directory.

Using the ‘dir’ command to get an extended directory listing:

ftp> dir
200 Command successfull
150 File okay, ready to transfer
-rwxrwxrwx 1 test_user ArgonDigital_test_users 19456 Jun 28 01:13 junk.doc
226 Closing data connection
ftp>

The access control information is clearly bogus, but then mapping docbase ACLs into Unix-like permissions isn’t easy.

Putting the same document a second time resulted in a new version, 1.1. Attempting to put the same document a third time (while the document was locked) resulted in an error being reported.

Changing directory is slightly strange in that the name of the new directory (folder) needs to be preceeded by ‘/’, even if this is a sub-folder of the current directory. This can lead to unexpected results if there is both a sub-folder and a cabinet with matching names, since you end up in the cabinet and not the sub-folder.

ftp> pwd
257 /Import
ftp> ls
200 Command successfull
150 File okay, ready to transfer
Test
ftp
Test
ftp
226 Closing data connection
ftp>

In order to change directory to ‘ftp’, do the following:

ftp> cd /ftp
250 Requested file action successful, command completed
ftp>

Non-standard features

If the user wishes to make use of any of the more advanced, client-specific features of (say) HomeSite, then this must also be indicated through the username string. This is done by appending the ‘|’ character and then a single letter, indicating the FTP client in use. Those supported are:

• H – HomeSite
• G – goLive
• W – WS_FTP pro
• D – DOS Client
• U – UNIX Client

For either username syntax, this convention always appears at the end of the line. So either

ftp> user test@test_dev|U

or

ftp> user test_devtest|U

will indicate to ftpIntegrator that a UNIX client is being used. Details of these client-specific features are covered in the Administration manual for ftpIntegrator.

ftpIntegrator is available under UNIX (Solaris and HP-UX). However, by default it is configured to listen on the non-standard port of 2100. Although is changeable by configuration but does mean that the product cannot be used ‘as is’ with many FTP Clients, since these do not allow the main FTP port number to be specified.

The maximum size of an object which may be moved with ftpIntegrator is limited by the machine on which it is running. In practice this means that files with 10Mb or more of content may not be put or fetched. This is probably due to an implementation detail where the object content is fetched as a byte stream to the program, not directly to the file system. Since java processes are limited in their maximum size, this results in the size of transfers also being limited.

Sample Configuration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ftpIntegrator SYSTEM "ftpConfig.dtd">
<!--
This file controls the creations of documents with specific subtypes,
lifecycle, path, alt_folder, or any non-repeating attributes. If
needed, more than one node can be created, with different docbase
names.
-->

<ftpIntegrator>
<docbase name="test_dev">
<!--
this rule will apply to all the documents with names start with "FTP",
file extension is txt, it is not case-sensitive.
-->
<rule directory="/Import" extension="txt" file_name="FTP">
<!--
First rule for 'test_dev'. This will match operations that
'put' .txt files into the folder root '/Import' with names
begin with 'FTP'.
-->
<!--
All the parameters can be seen on the property page in
viewable area, except alt_folder, to which folder a
link of the current object will be created.
-->
<!--
type should be the actual type name, not the display
name. path is any folder name under
configurationContent Templates.
-->
<!--
Nb: Not setting the 'extension' attribute results in the
rule never being matched. Always fill this in.
-->
<object_config type="inet_document" alt_folder="/Import/ftp" />
<init_attribute name="log_entry" value="set by ftp" />
<init_attribute name="a_effective_date" value="11/10/2000" />
</rule>
<rule directory="/Import" extension="doc" file_name="p">
<!--
Second rule for 'test_dev'. This will match operations
that 'put' .doc files into the folder root '/Import' with
names beginning with 'p'.
-->
<object_config type="web_content" />
</rule>
<!--
For all other 'put' operations, the default 'dm_document' will
be used to create new objects.
-->
</docbase>

<docbase name="webcache">
<!--
A different docbase
-->
<rule directory="/Temp" extension="txt" file_name="FTP">
<object_config type="acme_document" lifecycle="3 Stage Lifecycle" path="Sales" alt_folder="/Sarah" />
<init_attribute name="log_entry" value="set by ftp" />
</rule>
</docbase>
</ftpIntegrator>