VFS Connector

Usage

A VFS (Virtual File System) Connector enables communication of the INUBIT Process Engine with local and remote file systems such as Windows Shared directories or the local repository. The connector supports the CIFS/Samba and the repository protocol.

Connector types

The following configuration options are available:

Input connector

Imports files from a virtual directory structure and forwards them to a workflow for processing.
Output connector

Writes the result of a workflow to a file in a virtual directory.

Module Variables

When executing a VFS connector, module variables are set.

Input Connector

The following variables are available if a file is read and if DATA is selected as output format.

ReadFileDate

Last change date for the input file in the format yyyy-MM-dd’T’HH:mm:ss.
ReadFileName

Name of the input file including the extension.
ReadFileSize

Size of the input file in bytes.

Output Connector

The following variables are available if a file is written and if DATA is selected as input format.

WriteFileDate

Creation date of the output file in the format yyyy-MM-dd’T’HH:mm:ss.
WriteFileName

Name of the output file.
WriteFileDir

Name of output directory
WriteFileSize

Size of output file

For information about other variables and their use refer to Workflow Variables and Mappings.

Dialog Descriptions

Dialog VFS Connector Base Configuration

(Input and output connectors)

In this dialog, you configure the basic settings of the VFS Connector.

Protocol

Protocol

Possible values:
- cifs (Common Internet File System)
  
  Protocol for remote access to file systems via networks.
  
  To connect to the DFS Server, select the checkbox.
- repository
  
  To access the local INUBIT Repository.
- ftp (File Transfer Protocol)
  
  Protocol to access files via IP networks.
- samba
  
  To connect to Samba 2 and higher versions.

Authentication

Type
- If no authentication is required to access the server, select Anonymous.
- If you have chosen the repository protocol, the With user/group of the workflow type is also available. Then, the VFS Connector authenticates with the login data of the workflow.
  
  When using the With user/group of the workflow type, a published VFS Connector can only read files from the INUBIT Repository.

Use static login data

Login/Password

If your server requires an authentication, enter the necessary login data here.

Usually, server and client negotiate the desired type of password transfer. If required, you can manually disable the support of plain-text passwords for all cifs connections. To do this, you must create the additional Java System Property jcifs.smb.client.disablePlainTextPasswords and assign the value true to it, refer to Java System Properties. Note that if the server explicitly requires a plain-text password afterward, an error message is thrown.

When reading IBISDirectory structure via cifs connections under windows, the VFS Connector can only display the settings of direct read and write permissions of the data. The permissions inherited from parent directories cannot be displayed.

Select from Credentials Manager

For authentication, you can also use credentials managed by the Credentials Manager. Refer to Using the Credentials Manager for Authentication.

Host configuration

Host

Host name or domain address of the server, e.g. xyz.INUBIT.com.
Port
- cifs: The default port number is 445.
- ftp: The default port number is 21.
Default
- cifs: Restores the default port number 445, if required.
- ftp: Restores the default port number 21, if required.
Windows domain (cifs and samba only)

Name of the Windows domain if the server runs in a Windows domain.
Connection mode (FTP only)
- Active
  
  The client opens the configured port and informs the server of the port number and of its own IP address using the PORT command.
- Passive
  
  The client sends a PASV command and the server opens the configured port and passes it to the client along with the IP address.
- Default
  
  The client uses the server settings.
Transfer type

Specify whether the files to be transferred contain binary or ASCII data. Select Default in order that the client uses the server settings.
Locale

Server locale. The server locale defines the choice of the character set and date specification amongst others.

Encoding

Specify the encoding of the control channel for the communication connection between the connector and the FTP server.

The control channel is used to send commands, including file names as character strings. In order to make sure that special characters (e.g. umlauts) are correctly transmitted, defining the encoding is essential since it can differ from server to server.

Enable network speed limit (only for FTP/repository)

Select this option to limit the network bandwidth. This checkbox is deselected by default.

Speed (KB/s)

If Enable network speed limit checkbox is selected configure the speed by specifying the required value (whole multiples of 256 KB/s).

Connection test

Test connection

For testing whether the connection can be successfully established using your configuration.

Dialog Input Connector Configuration

In this dialog, you configure the input messages of the connector.

Directory

Path

Absolute path to the directory from which files are to be read.

When accessing files from the repository, use the path that is indicated in the Details tab of the respective file.

Refer to Details of a Repository File.

You can use the following wildcards, for example, to read out files from directories with changing names or from any directory depth.
- * (one asterisk): for filtering directory names or parts thereof. You can also use several wildcards in one name.
  
  Examples:
  - /*/bar searches /foo/bar
  - /*oo/bar searches /foo/bar or also /goo/bar
  - /*o*/bar searches /foo/bar or also /goa/bar
- * * (two asterisks): for filtering the directory name or parts thereof, for any deeply nested structures:
  
  /**/bar searches /foo/bar and /xyz/gfd/bar
  
  When using cifs or samba, the share name has to be prepended to the path.
Force directory deletion after reading (only for FTP protocol and output format XML or ZIP)

If selected, files, sub folders, empty sub folders, and the directory itself are deleted on the external file system.

If selected, the option Delete empty directories and Delete files after reading are deselected and disabled.
Delete empty directories (not available for Samba)

If selected, empty directories are deleted if the path contains wildcards.

File

Name: File name.
Use wildcard: If selected, you can use a wildcard (asterisk *).
Use regular expression

If selected, you can use Perl-compliant regular expressions to create character string patterns to select the files to be read.

Refer to Regular Expressions.
Invert selection

If selected, the pattern specified for the file name by using a wildcard or a regular expression is inverted. As a result, all files whose names do not correspond to the pattern are read.
Delete files after reading: If selected, files are deleted after they have been read.
Maximum number of executions per scheduled call

You use this specification to define the maximum number of times the workflow is to be started per triggering event. The triggering event is the reaching of a particular time point (if the scheduler is activated). The workflow is then started as many times as necessary until either:
- there is no more data to be fetched/sent or,
- the number defined in Maximum number of executions per call has been reached. By restricting the maximum number of executions, you control the system load on the server. In Test mode, this specification is ignored and the workflow is only started once.
  
  This option can only be used when the scheduler is active!

Reading order

If more than one file is transmitted, you can define if files are to be transmitted in a sorted way, and if yes, in which order.

Limits

Max. number files

Maximum number of files that can be read. Default value is 1.
Max. total size

Cumulative maximum size up to which files are read during workflow execution.

Default value is 10 MB.

If selected, the VFS Connector goes on reading files until, by accumulation, the defined total size is reached.

If DATA is selected as the output format, as a rule, only one file is read until the defined maximum size for this single file is reached.

If values have been set to less-than-or-equal 0 for limits, the restriction is unlimited.

Module output configuration

DATA

The output message consists of data that are forwarded in unchanged form.
XML

Defines that the output message is forwarded in IBISDirectory XML format.

You find the XML schemas in the INUBIT Repository under Global/System/Mapping Templates/File Connector.
ZIP

The output message is compressed in a Zip file.

For XML/Zip output: If you have configured wildcards in the directory name, the read data in the XML or Zip are output in a tree structure.

Examples:

The directory name is /foo/bar/*/blub.
The subdirectories starting with `/foo/bar `are read out.
The directory name is /foo/bar/xyz/blub.
The directory `/xyz/blub `is read out.

XML configuration

(Only if XML is selected as output format.)

Inclusive directories

If selected, in addition to the files the output message contains the directories.

Having selected both options Inclusive directories and Create XML output message with status information on whether the file exists or not, the directory structure is included in the XML output message.

Inclusive data

If selected, the entire file is read and its base64-encoded content is included in the XML output message. If not selected, only the file metadata are read, for example, name, file size, and date.

Zip configuration

(Only if ZIP is selected as output format.)

Inclusive directories

If selected, in addition to the files the output message contains the directories.
Encoding

Defines the encoding of file and Zip directory names.

File check

Abort workflow if file does not exist:
- In test mode:
  
  If access to the specified file fails, the workflow execution is terminated with an error.
- Scheduled input VFS Connector:
  
  According to the interval specified, the VFS Connector checks if a file is available. The workflow is only started if a file exists.
- Input VFS Connector in the middle of a workflow:
  
  If the file does not exist, the execution is continued with an empty message. No entry is made in the log.

Create XML output message with status information on whether the file exists or not

The VFS connector specifies an XML file that contains a single <FileExists> attribute. This value is false if the specified file does not exist and true if the specified file exists.

Having selected both options Create XML output message with status information on whether the file exists or not and Inclusive directories, the directory structure is included in the XML output message.

Create XML output message with status information that the file does not exist, otherwise abort workflow

If the input file does not exist, the VFS Connector outputs an XML file with the element FileExists="false". In all other error cases, the workflow execution terminates with an error.

Dialog Output Connector Configuration

(Output Connector)

You use this dialog to configure the output of the connector.

Input format

DATA

The input message consists of data that are forwarded in unchanged form. Select this option if the input message is e.g. in XML format.
XML

Defines that the input message is available in IBISDirectory XML format. Refer to Dialog Input Connector Configuration section Module output configuration.
ZIP

The input files are compressed in a Zip file.

Encoding

(Only if ZIP is selected as input format)

Encoding

Defines the encoding of file and Zip directory names.

Directory

Path

Absolute path to the directory that the VFS connector is to use when writing files. Must be based on the pattern /Root/AB_TestGroup/AB_Testdata/.
Create non-existent directories

Creates all non-existent directories from the path specification.

File

(Only for <DATA> input format.)

Name

File name. Optional wildcard or regular expression.
Overwrite existing file

If selected, an existing file with the same name is overwritten.
Append data to file

If selected, each time the workflow is executed the file to be read is appended to an existing file, should one exist. This can be useful if you want to record cumulative log data in a file.

This option cannot be used if wildcards are specified in the file name.
Throw error, if file exists

If selected, an error item is displayed in the Queue Manager for the workflow containing this VFS Connector if a file with the same name exists. If an error output is configured, it runs. Otherwise, the execution of the module is terminated.

Permissions

(Only if protocol repository is selected for output connectors)

Anonymously readable

Sets read permission for all users. Applies only to newly created files, permissions for existing files are not changed.