Installing the Filesystem Connector

Cloud Customers

The Filesystem connector can be installed in any servlet container behind your firewall where it can connect to your back end system in order to read/write data.

1. If you use the Live Forms Cloud hosted server,  you must ensure that the connector is accessible from the frevvo servers. This is done by opening up one of the following ports in your firewall:

• • HTTP Ports: 80 or 19080
  • HTTPs Ports: 443 or 19443
    
    

1. If you choose to run the Filesystem connector in the same container where  is running:
   
   1. Stop .
   2. Download the file connector zipflile from here. 
   3. Be sure to change the port number in the appropriate file for the container you are using. For example, if you are using the frevvo tomcat bundle, the change should be made in the <frevvo-home>/tomcat/conf/server.xml file. 
   4. The port number change is also applicable to any outgoing HTTP requests to the Filesystem connector. 

   5. Extract the filesystem.war file to the appropriate location for the container you are using. For example, if you are using the frevvo tomcat bundle, the connector should be located in the <frevvo-home>\tomcat\webapps directory.

2. Configure the Filesystem Connector

In-house Customers using the frevvo Tomcat bundle

The Filesystem connector can be installed in any servlet container behind your firewall where it can connect to your back end system in order to read/write data. These instructions assume you have an in-house installation of  up and running and you are using the frevvo Tomcat bundle:

To install the Filesystem connector in the same tomcat as :

1. Stop .
2. Download the file connector zipflile from here. 
3. Extract the filesystem.war file to your <frevvo-home>\tomcat\webapps directory. 
4. Configure the Filesystem Connector

Configuring the Filesystem connector

Currently, the Filesystem Connector is configured using context parameters in a file named filesystem.xml. 

1. Create a file named filesystem.xml. Move it to <frevvo-home>\frevvo\tomcat\conf\Catalina\localhost directory when it is completed. Refer to the table below for the configurable parameters that can be included in the filesystem.xml content:

   Configuration Parameter	Description
   connector.file.root.dir	This is the location in your file system where the submission docs will be saved.  If not explicitly configured, it defaults to the user home directory. Change the value to reflect the location for your file system.
   connector.file.name.keep	This parameter determines whether the original files names will be retained. If this is set to true, then you either have to make sure that all your files have unique names or else save the documents of each submission under a separate uniquely named folder. If this parameter is not included, or is set to false, submission files will be named with a generated identifier as the prefix suffixed by '_' and a sequence number to make the file name unique. The original filename extension is retained. This is the default behavior. Ex: e454fa08-9a6e-4c54-9743-18f4ba0ad0b4_1.xml instead of form.xml.
   connector.file.dir.submission	This parameter allows you to create a unique new sub-folder for documents of every submission if true.
   connector.file.ignore.attachments	This parameter determines whether attachments will be saved or not. If the value is false, attachments will be saved. Change the value to true and attachments will not be saved. The submission XML does not store the names of uploaded attachments, instead it points to unique ID that is assigned to each attachment when that submission in created in . This is the as-designed.
   connector.file.metadata.prefix	The default is "md". Change the value to the desired prefix. Field names preceded by this prefix in the Doc Url will be included in the generated metadata file. You will have to change it if the control names in your forms/flows are prefixed with "md" as a company standard.
   connector.file.descriptor.suffix	When generating metadata, the descriptor filename is the identifier, followed by a configurable suffix. The default suffix is '.xml'. Use this parameter to change the suffix.The suffix can make identifying the metadata file easier, particularly if you save the files from all submissions into the same folder.

   
   Here is an example of the filesystem.xml. When executed, submissions will be:

   • Saved on the local drive in a directory called Submissions.
   • Individual file names will be retained.
   • Attachments in the submisison will be saved.
   • Documents of each submission will be saved under a separate folder
   • Add any form fields preceded by the prefix mmk. in the Doc Action Url to the generated metadata file.

   • Add the suffix "_desc.txt" to the metadata file for each submission.
     

     <Context unpackWAR="false" path="/filesystem" swallowOutput="true" unloadDelay="40000">
     <Parameter name="connector.file.root.dir" value="C:\Submissions" override="false"/>
     <Parameter name="connector.file.name.keep" value="true" override="false"/>
     <Parameter name="connector.file.ignore.attachments" value="false" override="false"/>
     <Parameter name="connector.file.dir.submission" value="true" override="false"/>
     <Parameter name="connector.file.metadata.prefix" value="mmk." override="false"/>
     <Parameter name="connector.file.descriptor.suffix" value="_desc.txt" override="false"/>
     </Context>

     
     

2. Start .

3. Make sure the directory where you plan to save the submissions is created and and has the appropriate access for the OS you are using. For example:

   1. If you are using Windows, you can map a drive to a server directory, or you could use the UNC path i.e. //host-name

   2. If you are using a Unix operating system you could mount a remote filesystem as a directory and use it as your destination directory

      To ensure interoperability across file systems, it is recommended that you follow a good naming standard such as POSIX when creating files and folders. For example, folder names can't contain slashes so a folder named '1/2/15' would not be valid.

4. Browse http://localhost:8082/filesystem/health (replace localhost:8082 with your frevvo server host:port) to check the status of the connector. If the connector is up and running, you will see { "status" : "UP" }.

5. Modify your form/flow to use the File Connector via the Doc Action wizard:

   1. Edit your form/flow in the appropriate designer.

   2. Click on the what happens to my data? icon.

   3. Click to open the POST data to your web application wizard

   4. Add  http://localhost:8082/filesystem/submission (replace localhost:8082 with your frevvo server host:port) in the URL property.

   5. Select PDF in the Send Snapshot dropdown. 

   6. The Send Data checkbox is checked by default. Uncheck it if you do not want to save the .xml file
   7. Save your form/flow.
      
      
      
6. Test and submit the form/flow.

7. The submission documents will be found in the directory specified by the connector.file.root.dir parameter or in uniquely named folders under that depending on your configuration.

How to Customize the Submission Folder Name

You can append the submission.dir Url parameter to the Doc Action Url to customize the submission folder name. This will work even if you have not configured the connector.file.dir.submission context parameter in your filesystem.xml file. The Url would look like this:

 http://localhost:8082/filesystem/submission?submission.dir={DirName} - Replace localhost:8082 with your frevvo server host:port and replace DirName with the name of a field in your form/flow. 

For example, if you want to save submissions in a directory reflecting the Name that is entered in a Name control in your form/flow, append ?submission.dir={Name} to the Url property in the wizard. Whatever value is entered in Name field, will be used as the name of the directory into which that submission’s documents are saved.

Generating Metadata

Importing the submissions into your ECM requires the generation of metadata. To do this you will need to:

1. Provide the submission metadata as name-value query parameters to the Doc Action URL.
2. Create a descriptor file named file-descriptor.ftl in your <frevvo-home>\tomcat\lib directory. The file MUST be named file-descriptor.ftl.

Submission Metadata as name-value query parameters to the Doc Action URL.

Metadata to be put in the file-descriptor.ftl file is specified by adding name-value query parameters to the Doc Action URL in your form/flow. The 'value' can be a templatized string referencing a form field. The name should be prefixed so that it can be distinguished from the form field. The default prefix is md. Parameters preceded by the configured prefix will be added to the generated metadata file.

The prefix can be changed using the connector.file.metadata.prefix configuration parameter. It will be removed from the actual metadata.

The following example of the Doc action Url  passes the name parameter with a value from a field in a form called Name to the descriptor file. The default prefix md is used to distinguish the metadata from the form field in the Url:

http://localhost:8082/filesystem/submission?md.name={Name} - Replace localhost:8082 with your frevvo server host:port and add &(your prefix).the parameter={your form field}

This example also shows how to specify multivalued metadata for a field named 'state' inside a repeat in your form:

http://localhost:8082/filesystem/submission?md.name={FirstName}&md.state={&md.state=|State!encode=false} - - Replace localhost:8082 with your frevvo server host:port and add &(your prefix).the parameter={your form field}

Create the Metadata Descriptor File Template

The metadata descriptor file template generates a descriptor file every submission using the template and the query parameters appended to the Doc URl. If a query parameter name is referenced in the descriptor, then it is replaced with its value in the metadata file. This file will vary depending on the ECM that you are using.

Since the metadata varies by form type, a typical template would just iterate over all the input name-value pairs and output them in the input sequence.

1. Create a file descriptor template file and name it file-descriptor.ftl.

2. The file-descriptor.ftl should be located in the classpath  - if you are using the tomcat bundle, it should be located in the <frevvo-home>\tomcat\lib directory.

3. The content of the file-descriptor.ftl file uses freemarker template language v2.3.23 syntax. The input to the template is identified by the variable 'params'. This contains a map of parameter name and parameter value(s). The value is a sequence/array since a parameter can be multi-valued. If there is metadata that remains constant it should be added to the file-descriptor.ftl template.
   
   Here is one example that can be used with Docushare Enterpise Content System:

   <#compress>
   <#escape x as x?xml>
   <?xml version="1.0" encoding="UTF-8"?>
   <Records>tomcat bundle
     <Record>
       <Field id="LF__User" length="-1" type="string">
         <Value>administrator</Value>
       </Field>
     <#list params?keys as key>
     <#assign values = (params[key]?size > 1)>
     <#assign doc = key?switch('submission.file.name',true,false)>
       <Field id="${doc?then('LF__Document',key)}" length="-1" type="${doc?then('document','string')}">
         <#if values><Values></#if>
         <#list params[key] as value><Value>${value}</Value></#list>
         <#if values></Values></#if>
       </Field>
     </#list>
     </Record>
   </Records>
   </#escape>
   </#compress>

   In the above sample:

   1. LF-User is an example of metadata that is constant for all submissions
   2. Full paths to all the submission files will be included in the metadata file if you put the submission.file.name parameter in the template.
   3. Value refers to a single parameter while Values designates a multi-valued parameter
      
      
4. The descriptor filename in the submission directory is the identifier, followed by a configurable suffix. The suffix plays an important part in isolating the file. The default suffix is '.xml'. The suffix can be changed using the connector.file.descriptor.suffix context parameter. Here is what the file looks like in the submission directory when the file suffix is configured to be _desc.txt:
   

   
   
   

5. The values from the specified query parameters will be included in the generated metadata file. For Example; if you have fields called Name and state in your form/flow that you want to include in your metadata file and have configured the connector.file.descriptor.suffix context parameter to have a value of mmk, your Doc Action Url should look like this:

   http://localhost:8082/filesystem/submission?submission.dir={Name}&mmk.name={Name}&mmk.state={State}

   The metadata file would look like this:
   

Troubleshooting

Doc Post Failure

If the destination for saving submissions that you have specified cannot be reached, your tenant admin will receive an Doc Post Failure notification email reporting an HTTP Status error - 404. Check the connector.file.root.dir parameter in the file.xml file and the Url in the POST data to your web application wizard.

Determine the version of the Filesystem Connector you are using:

There are two ways to determine the version of the Filesystem connector that you are using:

1. Type http://localhost:8082/filesystem/info into your browser. The version information is returned as shown in the image.
   
   
2. Navigate to the <frevvo-home>\tomcat\webapps\file\META-INF directory on your server. You can find the version in the MANIFEST.MF file.