The Filesystem Connector saves DocuPhase Forms submissions to local or remote file systems (Windows, Linux). You can:

• Save each submission to its own folder

• Save all submissions to the same folder

• Choose to keep file names or generate a file name

• Generate metadata for import into your Enterprise Content Management system.

Submission form/workflow XML document(s), attachments that are added by the user and the PDF snapshot of your form/workflow can be saved in the configured submissions directory.

Signatures are not saved as they are a different content type than attachments.

Using the Filesystem Connector to save submissions to a shared directory might be an alternative if your forms/workflows contain sensitive/secure information that you would rather not send via email or if you want to import the submissions into your Enterprise Content Management system.

Open

On this page

• 1 Installing the Filesystem Connector
  • 1.1 Cloud Customers
  • 1.2 On Premise Customers with an existing DocuPhase Forms tomcat bundle installation
  • 1.3 Upgrading from a previous version
• 2 Configuring the Filesystem Connector
• 3 Connect Forms/Workflows with the Send to File System wizard
• 4 Generating Metadata
  • 4.1 Create the Metadata Descriptor File Template
  • 4.2 File Descriptor File Examples
  • 4.3 Generating Metadata using the Send to File System wizard
  • 4.4 Filesystem Connector Example:
• 5 Troubleshooting
  • 5.1 Doc Post Failure
  • 5.2 Determine your Filesystem Connector version

 Submissions from DocuPhase Forms are posted to the Filesystem Connector using the Doc Action Filesystem Connector#ConnectForms/FlowswiththeSavetoFilesystemwizard.

The Filesystem Connector is available for cloud and in-house DocuPhase Forms customers.

Generation of a metadata file for each submission can imported into a document management system. This is possible with the Send to File System wizard and a descriptor file that provides the instructions in freemarker language.  Once the metadata file is generated, it is the customer's responsibility to import it into the document management system. 

Installing the Filesystem Connector

Cloud Customers

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

1. If you use the DocuPhase Forms Cloud hosted server,  you must ensure that the connector is accessible from the DocuPhase Forms 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

   We recommend that you use https and not http. Https is a secure channel.

2. Customers that use firewall white-listing, should make sure the DocuPhase Forms cloud outgoing server IP 54.86.85.105 (host outgoing.frevvo.com) is added to the list.

3. If you want to install the Filesystem Connector in the DocuPhase Forms In-House tomcat bundle, follow these easy steps: (You don't have to use the DocuPhase Forms application from this bundle).

   1. Review the Supported Platforms list.

   2. Download and install the certified version of the Java Development Kit (JDK) and set the JAVA_HOME environment variable as described here. 

   3. Download the DocuPhase Forms tomcat bundle

   4. Unzip the DocuPhase Forms zip file into a location of your choice: e.g. c:\frevvo.   We'll refer to this directory below as <frevvo-home>.

   5. Install the Filesystem connector inside that same tomcat. 

      1. Download the filesystem zipflile 

      2. Extract the filesystem.war to <frevvo-home>\tomcat\webapps directory.

      3. Delete the <frevvo-home>\tomcat\webapps\frevvo directory.

      4. Configure the Filesystem Connector

4. Start DocuPhase Forms by clicking on the startup.(bat,sh) file for your operating system in the <frevvo-home> directory. It is also possible to configure frevvo as a Windows service

On Premise Customers with an existing DocuPhase Forms tomcat bundle installation

The Filesystem connector can be installed in behind your firewall where it can connect to your back end system in order to read/write data. These instructions assume you have an on premise installation of DocuPhase Forms up and running and you are running DocuPhase Forms and the Filesystem Connector in the same tomcat.

To install the Filesystem connector in the same tomcat as DocuPhase Forms:

1. Stop DocuPhase Forms.

2. Download the filesystem connector zipfile

3. Extract filesystem.war to your <frevvo-home>\tomcat\webapps directory.

4. Configure the Filesystem Connector

5. Start DocuPhase Forms

Upgrading from a previous version

To upgrade a previous version of the Filesystem Connector to the latest version in your existing Tomcat bundle installation:

1. Ensure you have downloaded the supported version of OpenJDK. Check Supported Platforms before beginning.

2. Stop DocuPhase Forms

3. Download the latest version of the Filesystem Connector

4. Extract the filesystem.war to your <frevvo-home>\tomcat\webapps directory.

5. Verify that the Filesystem Connector configuration is correct for the new version. 

6. Proceed to Connect Forms/Workflows with the Send to File System wizard to continue.

Configuring the Filesystem Connector

The Filesystem Connector is configured using properties in the <frevvo-home>\tomcat\conf\frevvo-config.properties file.

Follow these steps to configure the Filesystem connector:

1. Modify the File Connector settings section of the frevvo-config.properties file.

   1. the frevvo.filesystem.connector.url - The location of the Filesystem connector is set for the installation with this property. It defaults to http://localhost:8082/filesystem. Change the <localhost:8082> in the default URL to the <server:port> where you installed the Filesystem connector in your environment.

   2. Uncomment the property by deleting the # that precedes it.

      # File Connector settings frevvo.filesystem.connector.url=http://localhost:8082/filesystem

2. Add these properties to the <frevvo-home>\tomcat\conf\frevvo-config.properties file. You can add them to the existing File Connector settings section or make a new section with a comment as shown in the example below. Refer to the table for a description of the configurable properties:

   Here is an example of the Filesystem Connector properties added to the File Connector settings section of the frevvo-config.properties file. When executed, DocuPhase Forms submissions will be:

   • Saved on the local drive in a directory specified in the wizard that is located under the root directory configured here. Ex: C:\Submissions.

   • Individual file names will be retained.

   • Attachments in the submission will be saved.

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

     • In a properties file, a backslash is considered as a continuation character when splitting across lines. Escape it with another backslash i.e. C:\\ or use the forward slash i.e. C:/ when specifying the connector.file.root.dir property.

       # File Connector settings frevvo.filesystem.connector.url=http://localhost:8082/filesystem connector.file.root.dir=C:/ connector.file.name.keep=true connector.file.descriptor.suffix=_desc.txt connector.file.metadata.subdir=metadataFile/

3. Start the Insight server first, then start DocuPhase Forms.  

4. 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 (not recommended because Windows mapped drives cannot be reliably accessed from java), 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.

5. Browse http://<your server:port>/filesystem/health (replace <your server:port> with your DocuPhase Forms server:port) to check the status of the connector. If the connector is up and running, you will see { "status" : "UP" }

Connect Forms/Workflows with the Send to File System wizard

Saving files to a local or remote location is easily done with the Send to File System wizard if generating metadata is not required

Open

Let's begin with a very simple example. Here are the requirements:

1. You have created a small form that has a Name, Address, City, State and Zip Code fields. A mapped W - 4 PDF is included in the form. The Save PDF property is selected and the PDF Name property is configured with the template {Name}.

2. You want to store the submission files for this form in a directory on your local machine named Submissions. 

3. You want to create a subdirectory for each submission under the Submissions directory. The name of the subdirectory is created from the value entered into the Name field on the form

4. You want to save the form/workflow PDF, any mapped PDFs associated with the form, an xml file and any attachments uploaded to the form in the subdirectory. 

Follow these steps to fulfill the requirements by using the doc action Send to File System wizard

1. Log into your DocuPhase Forms tenant as a designer user.

2. Open your form/workflow.

3. Going the the Settings mode in the Guided Designer navigation toolbar.

4. Click the Document Actions tab. You will be on the Send Documents sub-tab. Click ADD DOCUMENT ACTION, then select Send to File System.

5. To fulfill the requirements listed above, we only need to fill in the URL, Submission Directory and File sections of the wizard. Here is an explanation of the fields:

   1. The URL: this is the URL to the location where you installed the Filesystem Connector. Be sure to include the /filesystem/submission in the URL after you change the server and port.

      1. In-house: The location of the Filesystem connector is set for the installation using the frevvo.filesystem.connector.url parameter in the <frevvo-home>\tomcat\conf\frevvo-config.properties file. It defaults to http://localhost:8082/filesystem in the tomcat build. The <localhost:8082> in the default URL can be changed to the <server:port> where you installed the Filesystem connector in your environment. This is a required field. The value entered here overrides the value in the frevvo-config.properties file.

      2. Cloud customers will see the placeholder http(s)://host:port/filesystem/submission - enter the https url to the location where you installed your DocuPhase Forms Filesystem Connector.

   2. Submissions Directory - Enter a relative path from the root directory specified by the connector.file.root.dir parameter in the configuration file created above. Control templates are allowed in this field. You can use a control template to store submissions in subdirectories. The template, {Name}, will populate the Template field. Copy the template from the Template field and add it to the Submissions Directory path after the forward or backward slash. Note the forward or backward slash can be used to create subfolders.

   3. Examples

      1. If the value of the connector.file.root.dir parameter in the configuration file is "c:\" then entering Submissions in the Submission Directory field in the wizard saves the files in the local directory c:\Submissions.

      2. File Section - One or more types of submission content can be specified by checking the Send Snapshot, Files, Gen Forms and Data checkboxes:

         1. Select the snapshot format to be sent by selecting a choice form the Send Snapshot dropdown. The format choices are PDF, PNG or JPEG.

            1. Check the Attachments checkbox to send any file attachments uploaded to the form.

            2. Check the Gen Forms(PDF) checkbox to send the mapped W - 4 PDF.

            3. Check the Data checkbox to send the form XML document for the form.

6. Save the form.

7. Create some submissions by testing the form, filling in the form and clicking submit.

8. The results of 3 submissions are shown in the image.
   
   

Generating Metadata

The Filesystem Connector saves the submission form xml, attachments and PDFs in the configured location. In addition, a metadata file, which describes the data, is created. This is helpful if your document management system has the capability to import files.

Generating metadata in xml format is the most common use case.

Follow these steps to connect your form/workflow to the Filesystem Connector:

1. Create a descriptor file named file-descriptor.ftl in your <frevvo-home>\tomcat\lib directory. The file MUST be named file-descriptor.ftl.

2. Use the Send to File System wizard to generate a map to provide the submission data to the connector 

Create the Metadata Descriptor File Template

The metadata descriptor file template generates a metadata file for every submission using the map that is generated by the wizard and the template. This file will vary depending on the ECM that you are using and your specific requirements.

1. If you are using the tomcat bundle, it should be located in the <frevvo-home>\tomcat\lib directory.

2. The content of the file-descriptor.ftl file uses freemarker template language v2.3.23 syntax.

Below are examples of the filesystem descriptor files that integrate with the DocuWare Management System, DocuShare Management System and ImageNow Imaging and Document Management Systems.

File Descriptor File Examples

Let's take a look at the file-descriptor.ftl file for DocuShare. In general, freemarker syntax is identified by the <# symbols.

• In the file, #compress, #escape, #function, #return, etc... are freemarker instructions

• The characters in this section of the file will be included in the metadata output file interspersed with freemarker instructions.

  • The submission.file.name is a special string, that adds a line in the xml file with a full path to the location where attachments, form/mapped PDFs and the form.xml are being saved for the submission.

• The last two lines in the file, </#escape and </#compress are the closing tags for the instructions specified at the top of the file.

These examples are offered as a guide to help you create your filesystem descriptor file. Even if you are working with one of the ECM systems represented by the examples below, you will need to customize the descriptor file to work for you.

Generating Metadata using the Send to File System wizard

Once the file-descriptor.ftl file is in place, the wizard must be configured to specify the Name-value pairs that will be used to generate the metadata file. This is done in the Metadata section of the wizard. The Name and Value columns are required. The Metadata Prefix is used to distinguish submission data fields from metadata fields. The default value of the prefix is md. The Name or Group value is prefixed with the metadata prefix when the doc action is executed. There is no limit to the number of rows allowed in the metadata table.

The Name column is to used to represent a unique entry on its own or within a Group. The following entry will cause a md.name=Tray Jenkins parameter to be sent to the connector.

The Group column is used to group name-value pairs. To represent a metadata entry with attributes you would use the Group column to indicate the entry name. The following entries will cause a md.EMPLOYMENTDATE={"type":"Date","value":"2014-04-03","culture":"en-US","format":"yyyy-MM-dd"} parameter to be sent to the connector.

The Value column can contain one or more control template strings. To create a template string, type an open curly brace { and the first few letters of the control name, then select the control from the dropdown that appears. 

To include values from repeating controls in your form/workflow, the value should be a template string that resolves to multiple values. The recommended approach is to create a template that results in a JSON array using the built-in separator 'json' i.e. {json|controlname}. This special separator resolves to JSON format. The same result can be accomplished by specifying the JSON format i.e. ["{","|controlname}"]. 

To include the comment values from selection controls with a comment enabled in your form/workflow, the value should be a template string that resolves to multiple values. The recommended approach is to use the syntax
["{,|controlname.commentValue}"].

Filesystem Connector Example:

Let's say you have a small form with the following controls: First Name, Last Name, Address, Date of Birth, a Signature control and a repeating control named State. Using the DocuShare file-descriptor.ftl file and setting up the The Send to File System wizard as shown in the above image results in these files the submission directory.

The generated metadata file contains the following:

Troubleshooting

Some common issues with solutions are listed below.

Doc Post Failure

If the destination for saving submissions that you have specified cannot be reached, all users with the tenant admin role or a workflow admin (if configured) will receive a Doc Post Failure notification email reporting an HTTP Status error. There can be a number of causes; check the following to determine the root cause and resolve it.

1. Check the submission repository to see a more detailed error message. 

2. Check the file-connector.<date>.log file and the frevvo.<date> log file for the date when the error was received. The logs are located in <frevvo home>\frevvo\tomcat\logs. Look for any ERROR level entries; these will often have more details about what went wrong.

If all submissions are failing,

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

• If this is a new installation, revisit the installation steps to ensure the filesystem.war is correctly installed.

• Ensure configuration settings are correct in the connector.file.root.dir parameter (in the frevvo-config.properties file) and the URL in the Send to File System wizard screen. Double-check spelling and capitalization. 

• Ensure the frevvo service user has permission to access and write to the submissions directory. If there is an issue with the submissions directory, you may see an error in the logs like "Root directory not found: <path>".

• Check that your SSL certificate is valid and current.

If one submission is failing but others are successful, there is likely an issue with the metadata being passed from that submission. Your logs may show a message like "The filename, directory name, or volume label syntax is incorrect." Remember that file and folder names must follow POSIX naming standards. View the submission XML document to see if there is an invalid file name or folder name being passed. 

Determine your Filesystem Connector version

To determine the version of the Filesystem connector that you are using:

1. Browse http(s)://<your server:port>/filesystem/info  - the version information is returned as shown in the image.