|
The Filesystem connector can be installed behind your firewall where it can connect to your back end system in order to read/write data.
HTTPs Ports: 443 or 19443
We recommend that you use https and not http. Https is a secure channel. |
Start frevvo 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
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 in-house installation of frevvo up and running and you are running frevvo and the Filesystem Connector in the same tomcat.
To install the Filesystem connector in the same tomcat as frevvo:
To upgrade a previous version of the Filesystem Connector to the latest version in your existing Tomcat bundle installation:
Ensure you have downloaded the supported version of OpenJDK. Check Supported Platforms before beginning.
Stop frevvo
Download the latest version of the Filesystem Connector
Extract the filesystem.war to your <frevvo-home>\tomcat\webapps directory.
Verify that the Filesystem Connector configuration is correct for the new version.
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:
Modify the File Connector settings section of the frevvo-config.properties file.
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.
Uncomment the property by deleting the # that precedes it.
# File Connector settings frevvo.filesystem.connector.url=http://localhost:8082/filesystem |
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:
Configuration Parameter | Description |
---|---|
connector.file.root.dir | This is the location in your file system where the submission docs will be saved. Set the submissions directory field in the Save to Filesystem wizard as a relative path from the root directory specified by the connector.file.root.dir in the connector deployment configuration. It's value can contain one or more control template strings. For example, if the configuration file contains C:\ for the connector.file.root.dir parameter, enter the name of the directory where you want to save the submissions in the Submissions field in the Save to Filesystem wizard. This will save the submissions in C:\<DIRECTORY NAME>. 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.descriptor.suffix | The metadata descriptor filename is a generic GUID filename, 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. Ex: 432e0d1f-d084-4cd4-8bbe-50f6e9bd5ee6_desc.txt |
connector.file.metadata.subdir | This directory must be a child of the root directory i.e. a relative path. When provided, and the directory exists, all metadata files will be created here. The metadata files are uniquely named, so there will be no conflict. |
Here is an example of the Filesystem Connector properties added to the File Connector settings section of the frevvo-config.properties file. When executed, frevvo submissions will be:
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/ |
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:
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
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. |
Browse http://<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" }
Saving files to a local or remote location is easily done with the Save to File System wizard if generating metadata is not required. Let's begin with a very simple example. Here are the requirements:
Follow these steps to fulfill the requirements by using the doc action Send to Filesystem wizard
|
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:
If metadata generation is required, the configuration can become significantly complex. For example, you may need to provide more attributes for a field than just a name or value. For these reasons, we recommend using the Save to File System wizard going forward. The wizard is simpler to implement and maintain. |
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.
If you are using the tomcat bundle, it should be located in the <frevvo-home>\tomcat\lib directory.
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.
If you are not familiar with the freemarker template language or you do not see an example for the Document Management System that you want to use, contact Sales to arrange a help session with frevvo Client Services. |
Let's take a look at the file-descriptor.ftl file for DocuShare. In general, freemarker syntax is identified by the <# symbols.
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.
DocuShare Management System: - this template should work for the DocuShare Management System, provided there are no future changes to the format. This descriptor file is compatible with the Save to Filesystem and Post data to your web application wizards.
|
DocuWare Management System: - this template should work for the DocuWare Management System, provided there are no future changes to the format. This descriptor file is compatible with the Save to Filesystem and Post data to your web application wizards.
|
|
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.
Name | Value |
---|---|
name | Tray Jenkins |
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.
Value | Group | |
---|---|---|
type | Date | EMPLOYMENTDATE |
value | 2014-04-03 | EMPLOYMENTDATE |
culture | en-US | EMPLOYMENTDATE |
format | yyyy-MM-dd | EMPLOYMENTDATE |
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}"].
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 Save to Filesystem wizard as shown in the above image results in these files the submission directory.
The generated metadata file contains the following:
<?xml version="1.0" encoding="UTF-8"?> <Records> <Record> <Field id="LF__User" length="-1" type="string"> <Value>administrator</Value> </Field> <Field id="my_name" length="-1" type="string"> <Value>{"First Name":"Arnold","Last Name":"Smith"}</Value> </Field> <Field id="Address" length="-1" type="string"> <Value>34 Some Street New City</Value> </Field> <Field id="EMPLOYMENTDATE" length="-1" type="string"> <Value>{"culture":"en-US","format":"yyyy-MM-dd","type":"3/31/1954","value":"3/31/1954"}</Value> </Field> <Field id="State" length="-1" type="string"> <Values> <Value>NY</Value><Value>MN</Value> </Values> </Field> <Field id="LF__Document" length="-1" type="document"> <Values> <Value>c:\Submissions\Arnold Smith\form.xml</Value> <Value>c:\Submissions\Arnold Smith\Letter of Recommendation 1.docx</Value> <Value>c:\Submissions\Arnold Smith\Arnold Smith.pdf</Value> <Value>c:\Submissions\Arnold Smith\W - 4 for Smith</Value> </Values> </Field> </Record> </Records> |
Some common issues with solutions are listed below.
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 an Doc Post Failure notification email reporting an HTTP Status error - 404.
Check the connector.file.root.dir parameter in the frevvo-config.properties file, the URL in the POST data to your web application wizard or the Save to File System wizard screen depending on the wizard you are using.
To determine the version of the Filesystem connector that you are using: