Virtual File Processing (VFS) Transport¶
About the VFS transport¶
This transport is used to process files in the specified source directory. After processing the files, it moves them to a specified location or deletes them. Note that files cannot remain in the source directory after processing because they will be processed again. Therefore, if you need to maintain these files or keep track of which files have been processed, specify the option to move them instead of deleting them after processing. If you want to move files into a database, use the VFS transport and the DBReport Mediator.
Note
When you transfer a file to a remote FTP location via VFS, the integrator tries to detect the FTP location by navigating from the root folder first. If the integrator does not have at least list permission to the root (/), the file transfer fails.
Paramers¶
Given below is the list of VFS transport parameters that can be configured.
VFS Service-Level Parameters¶
The VFS transport does not have any global parameters to be configured. Rather, it has a set of service-level parameters that must be specified when you create a proxy service.
Parameter | Description |
---|---|
transport.vfs.FileURI |
The URI of the location of your files. This should be the source location of the files (if you are configuring the Micro Integrator to read files) or the destination of the files (if you are configuring the Micro Integrator to send files). You can specify connection-level parameters on the URL (see VFS URL parameters below).
When you need to access the absolute path of the URL, you can define the URL with
You need to specify a valid file URI in the following form: sftpPathFromRoot as shown below. Also, note that transport.vfs.AvoidPermissionCheck is a mandatory parameter for this URL when SFTP is used.
file://path .
|
transport.vfs.ContentType |
Content type of the files processed by the transport. To specify the encoding, follow the content type with a semi-colon and the character set. For example: parameter name="transport.vfs.ContentType“text/plain;charset=UTF-32/parameter .
When writing a file, you can set a different encoding with the CHARACTER_SET_ENCODING property: property name="CHARACTER_SET_ENCODING" value="UTF-8" scope="axis2" type="STRING"/ .
Specify a valid content type. For example, text/xml . You can specify the encoding after the content type, such as text/plain;charset=UTF-32 .
|
transport.vfs.FileNamePattern |
If the VFS listener should process only a subset of the files available at the specified file URI location, use this parameter to select those files by name using a regular expression. Specify a regular expression. For example: *\.xml .
|
transport.PollInterval | The polling interval for the transport receiver to poll the file URI location. The value is expressed in seconds unless you add "ms" for milliseconds. For example, "2" or "2000ms" to specify 2 seconds. Specify a positive integer. |
transport.vfs.ActionAfterProcess |
Whether to move, delete or take no action on the files after the transport has processed them. Possible values are MOVE , DELETE , or NONE . The default value is DELETE .
|
transport.vfs.ActionAfterFailure |
Whether to move, delete or take no action on the files if a failure occurs. Possible values are MOVE , DELETE , or NONE . The default value is DELETE .
|
transport.vfs.MoveAfterProcess |
Where to move the files after processing if **ActionAfterProcess** is MOVE. This parameter is required if the ActionAfterProcess is MOVE .
|
transport.vfs.MoveAfterFailure |
Where to move the files after processing if **ActionAfterFailure** is MOVE. This parameter is required if the ActionAfterFailure is MOVE .
|
transport.vfs.ReplyFileURI | The location where reply files should be written by the transport. |
transport.vfs.ReplyFileName |
The name for reply files written by the transport. The default value is response.xml .
|
transport.vfs.MoveTimestampFormat |
The pattern/format of the timestamps added to file names as prefixes when moving files. Specify a valid timestamp pattern. For example, yyyy-MM-dd'T'HH:mm:ss.SSSZ .
|
transport.vfs.Streaming |
Whether files should be transferred in streaming mode, which is useful when transferring large files. The default setting is false .
|
transport.vfs.ReconnectTimeout |
Reconnect timeout value in seconds to be used in case of an error when transferring files. Specify a positive integer. The default values is 30 seconds.
|
transport.vfs.MaxRetryCount |
Maximum number of retry attempts to carry out in case of errors. Specify a positive integer. The default values is 3 .
|
transport.vfs.Append |
When writing the response to a file, whether the response should be appended to the response file instead of overwriting the file. This value should be defined as a query parameter in the out/reply file URI. For example:vfs:file:///home/user/test/out?transport.vfs.Append=true or, parameter name="transport.vfs.ReplyFileURI"file:///home/user/test/out?transport.vfs.Append=true/parameter .By default, the parameter is set to false (the response file will be completely overwritten).
|
transport.vfs.MoveAfterFailedMove | Where to move the failed file. |
transport.vfs.FailedRecordsFileName | The name of the file that maintains the list of failed files. Example file name: vfs-move-failed-records.properties. |
transport.vfs.FailedRecordsFileDestination | Where to store the failed records file. |
transport.vfs.MoveFailedRecordTimestampFormat |
Entries in the failed records file include the name of the file that failed and the timestamp of its failure. This property configures the time stamp format. Specify a valid timestamp pattern. For example, yyyy-MM-dd'T'HH:mm:ss.SSSZ . By default, the parameter is set to dd-MM-yyyy HH:mm:ss .
|
transport.vfs.FailedRecordNextRetryDuration |
The time in milliseconds to wait before retrying the move task. Specify a positive integer. The default value is 3000 miliseconds.
|
transport.vfs.Locking | By default, file locking is enabled in the VFS transport. This parameter lets you configure the locking behavior on a per service basis. You can also disable locking globally by specifying the parameter at the receiver level and selectively enable locking only for a set of services. The setting is enabled by default. |
transport.vfs.FileProcessCount | This setting allows you to throttle the VFS listener by processing files in batches. Specify the number of files you want to process in each batch. Specify a positive integer such as 10 .
Note: If you specify the transport.vfs.FileProcessCount parameter, you do not need to specify the transport.vfs.FileProcessInterval parameter in a configuration, and vice versa. These two parameters cannot be used at the same time. |
transport.vfs.FileProcessInterval | The interval in milliseconds between two file processes. Specify a positive integer, such as 10 |
transport.vfs.FileSizeLimit | Only file sizes that are less than or equal to the defined limit are processed. Specify the file size in bytes. The default value is -1 (unlimited file size). |
transport.vfs.AutoLockReleaseInterval |
The timeout value for stale locks where the VFS transport will ignore those file locks once the defined time period is reached. The time period is calculated from the time the lock is created to the time you attempt to access it. If you need stale locks to never timeout provide -1 as the timeout value. Specify the time in miliseconds. The default value is 20000 .
|
transport.vfs.SFTPIdentities | Location of the private key. |
transport.vfs.SFTPIdentityPassPhrase | Passphrase of the private key. |
transport.vfs.SFTPUserDirIsRoot | If the SFTP user directory should be treated as root. By default, this parameter is set to true . |
transport.vfs.ResolveHostsDynamically |
Whether hostnames should be resolved at the time of deployment or whether it is necessary to resolve hostnames dynamically at runtime. By default hostnames are resolved at the time of deployment. If you want to resolve hostnames at runtime, set this parameter to true .
Note: Resolving hostnames at runtime is only possible for the Server Message Block (SMB) protocol.
By default, this setting is false .
|
transport.vfs.AutoLockRelease |
Set to true if you need to release locking in order to avoid files not being processed due to faulty locking. This works together with the transport.vfs.AutoLockReleaseInterval and transport.vfs.LockReleaseSameNode parameters.
|
transport.vfs.LockReleaseSameNode | Set to true if you need to release the locks only accrued by the same worker node.If this is set to false , locks accrued by other nodes will be released according to the value specified in transport.vfs.AutoLockReleaseInterval . By default, this setting is true .
|
transport.vfs.FileSortAttribute | The attribute by which the files should be sorted and processed. The possible values are NONE , Size , or Lastmodifiedtimestamp . |
transport.vfs.FileSortAsscending |
The sort order to sort and process the files. If set to true , files will be sorted in ascending order based on the attribute you specify in transport.vfs.FileSortAttribute . By default, this setting is true .
|
transport.vfs.CreateFolder |
Set to true to create a folder if a folder does not exist when moving files. By default, this setting is false .
|
transport.vfs.SubFolderTimestampFormat |
The pattern/format of the timestamps added to the folder structure when moving files. You need to set transport.vfs.CreateFolder to true in order to specify a value for this parameter. Specify a valid timestamp pattern. For example, yyyy-MM-dd'T'HH:mm:ss.SSSZ .
|
transport.vfs.Build |
Set to true if you need to build the content inside the file before injecting the file to the mediation engine. If there is a build error, the file will not be injected to the mediation engine. By default, this setting is false .
|
The following service-level parameters are required for Inbound Endpoints.
Parameter | Description |
---|---|
interval | The time duration in milliseconds between two file scans that checks for updates. |
sequential | Files will be processed sequentially when this parameter is set to true. |
coordination |
This should be true for clustered deployments in order to prevent two nodes from retrieving the same file. |
VFS URL Parameters¶
When you use the transport.vfs.FileURI parameter, you can set connection-specific VFS parameters as URL query parameters. For example, to use SFTP with SSL, you could specify the URL as shown below. Note that transport.vfs.AvoidPermissionCheck is a mandatory parameter for this URL when SFTP is used.
<parameter name="transport.vfs.FileURI">vfs:ftps://test:[email protected]/vfs/in?vfs.ssl.keystore=/home/user/openssl/keystore.jks&vfs.ssl.truststore=/home/user/openssl/vfs-truststore.jks&vfs.ssl.kspassword=importkey&vfs.ssl.tspassword=wso2vfs&vfs.ssl.keypassword=importkey;transport.vfs.AvoidPermissionCheck=true</parameter>
Parameter | Description | |
---|---|---|
transport.vfs.AvoidPermissionCheck | Be sure to set this parameter to true for an SFTP connection. This is because (by default) the VFS transport checks whether the user has permission to access the location of the files (the source location or the destination). However, since the system is reading files in an external server through the SFTP connection, this permission check is not required and should be avoided. | |
vfs.passive |
Enable FTP passive mode. This is required when the FTP client and server are not in the same network. By default, this setting is false .
|
|
transport.vfs.Append |
If a file with same name exists, this parameter tells whether to create a new file and write content or append content to existing file. By default, this setting is false .
|
|
vfs.protection |
Set data channel protection level using FTP PROT command. Possible values are as follows:
C .
|
|
vfs.ssl.keystore | Private key store to use for mutual SSL. Your keystore must be signed by a certificate authority. For more information, see http://docs.oracle.com/cd/E19509-01/820-3503/ggfen/index.html. Possible value: String (Path of keystore). | |
vfs.ssl.kspassword | Private key store password. | |
vfs.ssl.keypassword | Private key password | |
vfs.ssl.truststore | Trust store to use for SFTP | |
vfs.ssl.tspassword | Trust store password | |
transport.vfs.CreateFolder | If the directory does not exists create and write the file. The default setting is false . |
|
transport. vfs.SendFileSynchronously |
Whether to send files synchronously to the file host. When this parameter is set to true , files will be sent one after another to the file host. This synchronous write can be configured on a per host basis. The default setting is false .
|
Configuring a Proxy Server over FTP and SFTP¶
Proxy server specific parameters can be set as URL query parameters. For example, to use Proxy over FTP, you could specify the URL as follows:
ftp://username:[email protected]/home/wso2/res?proxyServer=127.0.0.1&proxyPort=3128&proxyUsername=proxyuser&proxyPassword=proxyPass&timeout=2500&retryCount=3
Following are the URL parameters you can set:
Parameter | Description |
---|---|
proxyServer |
The IP address of the proxy server. Possible value: 127.0.0.1 . This parameter is set to false by default.
|
proxyPort |
The port number on which the proxy server is listening for requests. Possible value: 1328 . This parameter is set to false by default. |
proxyType |
The proxy server type. This can either be HTTP or SOCKS . The default is SOCKS .
Note: In a configuration, if the proxy server type is not specified or an unknown proxy server type is specified, the proxyType will be considered as HTTP .
|
proxyUsername | The user name of the proxy server. |
proxyPassword | The password of the proxy server. |
timeout |
The connection timeout in milliseconds. Possible value: 1000 . The default value is 5000 .
|
retryCount | The number of retry attempts in case of a connection timeout. Possible value: 3 . The default value is 5 . |