Microsoft: Remote Fax Service for Windows

Retarus Remote Fax Service is an application running as a Windows Service. It monitors a configurable number of folders and sends the files as fax messages via the Retarus infrastructure. This tutorial explains the installation of the service and the configuration of the service parameters.

Developer: Retarus

Category: Cloud Fax Connector

Prerequisites

Microsoft Windows .NET Framework 4
Administrative user rights for installation
API credentials (“Login-ID”) for Retarus Fax-for-Applications.
https connection to the Retarus infrastructure
Sufficient hard disk storage for log file output (adjustable, but with a default retention period of 30 days)

This application exclusively uses Microsoft .NET libraries and components provided by the .NET Framework 4. No third-party libraries and components have been used. The application will create distinct log files. Errors and start/stop notifications will also be monitored in the Windows Event Viewer under Applications.

Service Installation

Installation

Three files are required to run the Retarus RemoteFaxService application:

RetarusRemoteFaxService.exe (the executable application with version no. 1.0.0 build 15, or higher)
RetarusRemoteFaxService.exe.config (this configuration file contains information for integration of Retarus SOAP interfaces for Fax-for-Applications)
RetarusRemoteFaxServiceConfig.xml (the actual configuration file for using the application and monitoring folders)

To install the application, perform the following steps:

Create the installation folder and copy the three files mentioned above.
Open the Windows Command Line (cmd.exe) with administrator user rights.
Change the directory to the created installation folder.
Run the following command line to install the application as a Windows service:

C:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe RetarusRemoteFaxService.exe

(using parameter /u will uninstall the Windows Service)

Please take note of any notifications that appear during the installation process. The log file created by the operating system in the working directory with detailed information on the installation process is named InstallUtil.InstallLog.

The startup type for this service has been deliberately set to Manual. Please start the service after successful configuration via Windows Services and, if necessary, change the start-up type to Automatic.

Service Mode of Operation

Workflow Sequence

Start/read the configuration file
After a successful start, the RetarusRemoteFaxServiceConfig.xml configuration file will be parsed. For each folder to be monitored, a distinct process will be started.
Queue Check
The process will begin checking whether files are in the monitored folder queue, e.g., after a server restart. The queued files will be processed immediately and forwarded to the Retarus infrastructure.
Event-based processing
The service monitors the folder for new, ready-to-be-processed files.

The Retarus RemoteFaxService can process multiple files simultaneously; however, its performance depends on operating system factors and filename length. Our benchmark tests produced values ranging from ca. 20 – 25 files simultaneously processed with an average speed of ca. 4 – 5 files per second.

After each file is handled, the process will check whether new files are in the monitored folder and place them immediately in the queue for processing.

Specifics

The Retarus RemoteFaxService facilitates the transmission of user credentials via a configuration flat file. Based on Windows user account data, the application exports specific values from the User Directory for report generation (sender email, cost center-specific values, and sender data (TSID, etc.). This process can be automated by using another Retarus service (DirSync). The RemoteFaxService identifies changes in the configuration flat file and loads new values immediately. This action will be logged in the application logfile.

The application reacts to modifications made to the configuration file. As soon as changes have been identified in the configuration file, all the running processes will be stopped and restarted with the newly added values.

If a new configuration contains the deactivation or deletion of a monitored folder, it could result in files that have not been fully processed remaining in the folders. Please consider this and verify the contents of those folders manually to ensure the successful transmission of queued fax messages.

Configuration

RetarusRemoteFaxServiceConfig.xml

The XML code for the configuration file options is as follows:

CODE

<?xml version="1.0" encoding="utf-16"?>
<Config xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Options UseApplicationDataPath="true"
	CustomDataPath=""
	UserAccountFileName="C:\Users\...\UserMailReference.txt"
	LogRotationDays="30"
	ApplicationLogLevel="DEBUG"
	EventLogLevel="INFO"
	ConfigFileType="RetarusRemoteFaxService" ConfigFileVersion="1.0" />

The potential parameters located in the configuration file are explained in the following table:

Optional parameter	Value	Description
UseApplicationDataPath (a folder `\Logs` will be created in the working directory)	true	Logfiles are created in the system-specific Program Data Path, where the `Retarus\RemoteFaxService` directory is also located.
UseApplicationDataPath (a folder `\Logs` will be created in the working directory)	false	The service installation path will be used.
CustomDataPath (a folder `\Logs` will be created in the selected path)	valid path	Specifying a valid path will overwrite the UseApplicationDataPath attribute. If the path does not exist, the application will attempt to create it
UserAccountFileName	valid flat file	An optional flat file can be specified to include user-account information from an existing User Directory.
LogRotationDays	Number of days	Logfile retention period
ApplicationLogLevel	NONE, TRACE, DEBUG, INFO, WARN, ERROR, FATAL	The trace level for log entries is saved in the application log file.
EventLogLevel	NONE, TRACE, DEBUG, INFO, WARN, ERROR, FATAL	The trace level for log entries is saved in the Windows Eventlog (application). Not every entry in the application logfile will be logged in the Windows Eventlog.
ConfigFileType	Reserved	Use only on-demand.
ConfigFileVersion	Reserved	Use only on-demand.

Configuration File Default Parameter

The configuration file’s code for its default parameter is as follows:

NONE

<Defaults EMailAddress="friedrich.schiller@retarus.de" />

This Configuration File Default Parameter is explained in the following table:

Default parameter	Value	Description
EMailAddress	a valid email address	Default email address used for reporting purposes if no email address could be determined in the job data or parameters.

Configuration File Credentials

The configuration file’s code for the login credentials to the Retarus infrastructure is as follows:

XML

<Credentials>
<Credential Name="retarus" UserId="user.id@retarus.de"
Password="password" ServerAddress="" Port="0" />
</Credentials>

The login credential parameters are explained in the following table:

Credential parameter	Value	Description
Name	Alphanumeric	A distinct name for referencing specific configurations and login credentials.
UserId	Alphanumeric	The user ID will be provided by Retarus relating to the Fax-for-Applications account. There is a cost for the Fax-for-Applications account, monthly fees, and a charge per fax page.
Password	Alphanumeric	This is the password related to the UserID. The password can be modified in the Retarus EAS Portal by an administrator.
ServerAddress	URL	URL information, if different from the default Retarus Gateway.
Port	Positive numeric value	Port information, if different from the default port for data transmission.

Watch Folder Parameters

The configuration file’s code for the monitored folder’s parameters is as follows:

XML

<Folders>
<WatchFolder CredentialName="retarus"
PathName="C:\Users\...\folder2watch01" CheckForOrphanedFiles="15"
CompletedDocuments="MOVE" RuntimeMode="ACTIVE" TestAddress="">

The Watch Folder Parameters are explained in the following table:

Optional parameter	Value	Description
CredentialName	Alphanumeric	Cross-reference to the Credential-entry in the configuration files. The upload of the fax job will use this information.
PathName	valid path	The name of the folder to be monitored.
CheckForOrphanedFiles	positive, numeric value	The time in minutes to schedule the monitoring of the declared folder, independent from other potential processes.
CompletedDocuments	DELETE	Successfully processed files will be deleted.
CompletedDocuments	MOVE	Successfully processed files will be moved into a subfolder named Done and are located in the folder defined in PathName. If the folder does not exist it will be created. The name and path of this subfolder currently cannot be configured.
RunTimeMode	NOTACTIVE	Monitoring of this folder is deactivated.
RunTimeMode	ACTIVE	Monitoring of this folder is activated and fax jobs will be forwarded with the corresponding parameters to the Retarus infrastructure.
RunTimeMode	TEST	Monitoring of this folder is activated, but the fax job will be simulated or routed to a test number (please consult information on TestAddress).
RunTimeMode	NOUPLOAD	Monitoring of this folder is activated and the application will process the data, but there will be no upload to the Retarus infrastructure.
TestAddress	Empty or valid fax number	If RunTimeMode is set to TEST, each destination fax number will be overwritten with this value. This ensures that tests from systems in operation will not be sent. If the TestAddress is empty, a “Magic Number” will be used. The “Magic Number” triggers a transmission simulation, which means the process will be processed through the Retarus infrastructure. However, the job will not be completed and the transmission result will be determined by a random computation.

DocumentType Parameters

The configuration file’s code for the monitored folder’s DocumentType parameters is as follows:

XML

<Documents>
<Document FilenameFilter="" DocumentType="RETARUSJOBFILE">

These DocumentType Parameters are explained in the following table:

Optional parameter	Value	Description
FileNameFilter	Alphanumeric	Filter for filenames corresponding to the defined pattern (e.g., *.pdf, .xml, fax**.tif).
DocumentType	SINGLEFILE	A single file containing the document to be transmitted along with the information needed for the file transmission.
DocumentType	FILENAMEARGS	A single file representing the fax message. Information needed for transmission will be parsed from the actual filename.
DocumentType	CLEARHEADER	Like SINGLEFILE, the information needed for transmission is expected in the text header, which is deleted before transssion. Currently supported formats are PCL and PDF (this information will be sought at the beginning of each valid file format).
DocumentType	MULTIFILE	The file containing the transmission information will be filtered/selected. To be transmitted, this file must contain a reference to the actual document to be transmitted.
DocumentType	SAMENAME	Like MULTIFILE, a document with the same filename but a different file extension will be filtered (e.g., fax_message.txt and fax_message.tif). The FindDocumentWithExtension attribute is also required.
DocumentType	RETARUSJOBFILE	The application expects an XML file with the corresponding RETARUSJOBFILE format. As is the case for MULTIFILE, this XML file contains transmission information and references to the different documents (fax messages). The DocumentType must be specified.
FindDocumentWithExtension	valid file extension	Needed for DocumentType=SAMENAME (e.g., .tif, .pdf, .doc).

JobFieldType Parameters

The configuration file’s code for the JobFieldType parameters is as follows:

XML

...
          <JobDataFields />
        </Document>
      </Documents>
    </WatchFolder>
    <WatchFolder CredentialName="retarus" PathName="C:\Users\...\folder2watch02" CheckForOrphanedFiles="15"
CompletedDocuments="MOVE" RuntimeMode="ACTIVE" TestAddress="">
      <Documents>
        <Document FilenameFilter="*.pdf" DocumentType="FILENAMEARGS">
          <JobDataFields>
            <JobDataField JobFieldType="FAXNO">
              <RegularExpressions>
                <RegularExpression Pattern="^\+*\d*" />
              </RegularExpressions>
            </JobDataField>
            <JobDataField JobFieldType="JOBID">
              <RegularExpressions>
                <RegularExpression Pattern="(?i)^.*_(\w*)\.pdf" Replace="$1" />
              </RegularExpressions>
            </JobDataField>
            <JobDataField JobFieldType="OSACCOUNT">
              <RegularExpressions>
                <RegularExpression Pattern="^.*_(\w*)_.*" Replace="$1" />
              </RegularExpressions>
            </JobDataField>
          </JobDataFields>
        </Document>
      </Documents>
    </WatchFolder>
...
...
  </Folders>
</Config>
...

The JobDataField contains parsing information that is required for delivery. JobFieldType specifies which internal field type has to be searched for and how the parsed information must be used.

These parameters are explained in the following table:

Parameter	Value	Description
JobFieldType	JOBID	Used for referencing the fax jobs to the data.
JobFieldType	BC	Billing code for financial accounting.
JobFieldType	FAXNO	Receiver fax number.
JobFieldType	FILENAME	Filename for the actual documents and is required when the `DocumentType=MULTIFILE`.
JobFieldType	OSACCOUNT	User account utilized for the transmission of the fax message. Using a flat file (please see UserAccountFileName in Table 4.1) to reference the user account and corresponding email address. Used for report delivery.
JobFieldType	FROM	Sender information used for report delivery.
JobFieldType	CSID	Sender ID used for the destination fax devices.
JobFieldType	OVERLAY	Used in correlation with the fax overlay stored in the Retarus infrastructure. The overlay can be uploaded as a TIFF file into the EAS-Portal, corresponding to a Retarus Fax-for-Applications account.

JobFieldType Regular Expression Parameters

Any number of regular expressions (RegularExpression tags) can be used. The mode of operation is similar to I/O pipelines: the result of the first RegularExpression becomes the input for the second RegularExpression and so forth.

These parameters are explained in the following table:

Optional parameter	Value	Description
Pattern	valid RegEx pattern	Simple (reasonably structured) documents can be parsed using regular expressions and deliver reliable transmission information.
Replace	valid RegEx replace-string	The specification of a valid path will overwrite the UseApplicationDataPath attribute. If the path is not present, the application will try to create it.
Conversion	NOCONVERSION	No conversion will be done (default).
Conversion	TOUPPER	Results will be converted to upper case.
Conversion	TOLOWER	Results will be converted to lowercase.