ReplixFax Batch Loader
Admin Guide
December 2015
Copyright 2015 Softlinx, Inc. All rights reserved.
Made in the United States of America.
This guide and the accompanying software are supplied under a license agreement, which is included in this package. Permission to use, copy, modify, and distribute the software and documentation is restricted under the terms of the license agreement.
No part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Softlinx, Inc.
Softlinx, Inc. reserves the right to make changes to the product or this guide any time without notice.
Other software programs that are used with ReplixFax are under copyright by their respective owners.
Trademarks
Replix and Softlinx are registered trademarks of Softlinx, Inc. Microsoft is a registered trademark of Microsoft Corporation.
ii
Table of Contents
INTRODUCTION ... 1
INSTALLATION OVERVIEW ... 2
CONFIGURATION STEPS ... 3
REVIEW OF REGISTRY SETTINGS ... 3
CHANGE THE CONFIGURATION FILE ... 3
ENCRYPTING PASSWORDS ... 7
START THE WINDOWS SERVICE ... 8
CONTROL FILE SYNTAX ... 9
GENERAL PROCESSING ... 9
ERROR HANDLING AND RECOVERY ... 9
SAMPLES ... 11
1
Introduction
ReplixFax Batch Loader is a Windows Service that polls folders for faxes to send to the Softlinx Cloud Fax Service. ReplixFax Batch Loader reads control files in the monitored folders that indicate fax parameters such as the fax number, and identifies documents to fax. Configuration options allow the ReplixFax Batch Loader to work with varying control file formats. Fax requests are sent using the ReplixFax Web Services API over HTTPS so the communication channel is secure.
This documentation will guide you through the setup and operation of the ReplixFax Batch Loader application.
2
Installation Overview
In order for the ReplixFax Batch Loader to install properly, the following prerequisites must be met:
Supported Operating Systems: Microsoft Windows 2012, 2008, 8, 7
User has Windows administration privileges
Microsoft Dot Net 3.5 or higher is installed on the system
To start the installation, run the ReplixFaxBatchLoaderSetup.exe application. Accept the default installation options. The installation creates a Windows service “ReplixFax Batch Loader” which is set to Automatic startup.
3
Configuration Steps
Review of Registry Settings
The installation creates the following registry entry:
HKEY_LOCAL_MACHINE\SOFTWARE\Softlinx\ReplixFax Batch Loader
If installed on a 64-bit OS, then the registry will be under the WOW6432Node. There are two string values in this section: working_dir and poll_interval_sec. The “working_dir” key is the folder that contains the service executable and the
configuration files named BatchLoad<n>.config. It will also contain the log file once the service starts.
The “poll_interval_sec” is the number of seconds the batch loader waits between polling the folders.
Change the Configuration File
Edit the configuration file and change the appropriate values. If Softlinx support has provided a configuration file for you, replace the BatchLoad1.config file with the one provided by Softlinx. Make sure the file name remains BatchLoad1.config.
If you want to poll more than one folder, create BatchLoad<n>.config files for each folder. Number them sequentially. The order the folders are polled is determined by the number in the configuration file name.
Sample configuration and control files are installed on your system under the "Documents" directory of the user. You can also navigate to the Samples directory from Start, All Programs, Softlinx, ReplixFax BatchLoader Samples. See the Samples section later in this document for more details.
Generally, it is helpful to set the logging_level in the configuration file to “3” while
configuring the service. By doing this, the Batch Loader will log details of its actions. This is very helpful while debugging any issues with the setup. Remember to set this value to 0 when done with initial setup and the Batch Loader is processing files.
The value for the replix_password in the control file must be encrypted. Use the encryption application that is installed with the Batch Loader to encrypt the password and copy that string into the configuration file. See following sections for more details.
4
The configuration file tells the Batch Loader which folder to poll as well as how to process the folder. For example, where to copy the files once processed. Additionally, the
configuration file defines the keywords that will be found in the control files.
Below is a table which shows the parameters in the configuration file that control Batch Loader behavior. All of the parameters must be preset and set in the configuration file or the control files will NOT be processed.
Key Description
auto_recover Automatically process “bad” control files. If set to true, then
before each cycle of polling, the Batch Loader will rename “*.working” files so they will be retried.
continue_on_error Continue processing the control file if the errors occur while
processing a fax. For example: a missing attachment file. If this occurs, the control file will be processed and then renamed to be *.working.
control_file_filter Search string used to look for control files in the monitored
folder. Ex: “*.ctrl” means all files with the “ctrl” extension are control files.
delete_when_done Delete the control file and corresponding documents that were
faxed after all faxes identified in the control file are successfully submitted to the fax server. Note: when the
files_full_path parameter is set to true, the original file will
not be deleted (only the copy under the folder_monitor directory). If this is set to false, then the fax files, control file and sent file will be moved to the folder_done directory.
errors_to_event_log Write event to Windows Event Log. Codes in event log:
100: bad control file 200: bad configuration.
files_full_path Set to true if the fax files identified in the control file contain
the full path. If this is set to true, then the fax files CANNOT be located in the same directory as the control file.
folder_done Folder to put completed control files and corresponding
documents. This will only be used if delete_when_done is set to false.
5
folder_monitor Folder to poll for control files that indicate faxes to send. This
folder must exist or the Batch Loader will log an error.
ignore_fax Do not send faxes to this fax number.
logging_level Logging level. Accepted values are:
0 - errors only
1 – successful sent fax information 2 – warnings and errors
3 - log everything
replix_password Encrypted password for the Replix user. See "Encrypting
passwords" section for details on how to encrypt a password.
replix_url The URL to the ReplixFax server Web Service.
The test server is:
https://faxtest.softlinx.com:8083/softlinx/replixfax/wsapi The production server is:
https://api.rpxfax.com/softlinx/replixfax/wsapi
replix_user The ReplixFax user that will be used to make the web services
calls. If use_pseudouser is true then the relix_user needs to be a user that has the pseudo user permission set. The username should be in the format: user@organization. Example: admin@demo
use_basic_auth This should be set to 0.
Important: The polling folder must be set in order for the service to start.
Additionally, the configuration file contains parameters that identify the keywords that will be used in the control files.
Key Description
comment_indicator String indicating that line should be ignored
Example: #
common_section_end String indicating end of common section.
6
fax_section_end String indicating end of fax section.
Example: @+END
key_batch The name of the batch. This should be in the common
section of the control file. Example: BATCH_NAME
key_cover Cover page key. This should be in the common section of
the control file.
Example: COVERPAGE
key_delimiter Separator for key and value.
Example: “=”
key_file Key to indicate name of the file to send in the fax.
Example: FILE_NAME
key_from Key for use with pseudo user. If use_pseudouser=true in the
config file, then faxes can be sent as different Replix users. You can specify this user in the common section or in each fax section.
Example: FROM_USER
keys_ignore Ignore these keys in the control file. Separate with semi
colons. Only enter keys that are not defined in the Control file. For example if keys_ignore=shape, then all lines that begin with “shape=” will be ignored. This should be in the common section of the control file.
Example: IGNORE_KEYS
key_message Cover Page message key. Only use if use_coverpage is true.
Example: COVERPAGE_MESSAGE
key_project1 Key for project code 1. In the Softlinx Cloud service clients,
this is referred to as “Keyword”. Example: PROJECT_CODE1
key_project2 Key for project code 2. In the Softlinx Cloud service clients,
this is referred to as “Account”. Example: PROJECT_CODE2
key_recipient_company Key for recipient’s company. Only applicable if using
Softlinx cover page template. Example: RECIPIENT_COMPANY
7
key_recipient_fax Key for recipient’s fax number.
Example: RECIPIENT_FAX
key_recipient_name Key for recipient’s name. Only applicable if using Softlinx
cover page template.
Example: RECIPIENT_NAME
key_recipient_title Key for recipient’s title. Only applicable if using Softlinx
cover page template.
Example: RECIPIENT_TITLE
key_recipient_voice Key for recipient’s voice number. Only applicable if using
Softlinx cover page template. Example: RECIPIENT_VOICE
key_unique_fax_id Unique identifier for a fax in a specific batch file. Used during recovery. If this is set, then do NOT set
key_unique_fax_key. This is necessary if the same fax number can occur in a single control file. The value
associated with this key in the control file must be unique in the control file. It is the responsibility of the application that generates the control file to set the unique value.
Example: UNIQUE_FAX_ID
key_unique_fax_key Key used to help uniquely identify a fax in a given control file. Used during recovery. This is used when the same fax number can occur in a single control file. The value for this key must be a valid supported key name. The value of the corresponding key in the control file along with the fax number are concatenated to make a unique id. If this is set, then do NOT set key_unique_fax_id.
Example: UNIQUE_FAX_KEY
Encrypting Passwords
After the installation, you will need to encrypt the Replix user’s password. Navigate to the encryption program by going to:
Start > Programs > Softlinx > ReplixFax Batch Loader > Password Encryptor
Enter the password in the “Password:” field, and click Encrypt.
The encrypted password will be shown in the “Encrypted:” field. Copy this value into the config file for the key: “replix_password”.
8
Start the Windows Service
After completing the configuration changes, start the ReplixFax Batch Loader Service. When the service is started, the folders into which the completed batches are put will be created if they are not present.
9
Control File Syntax
<key><delimiter><value> <common section end> <key><delimiter><value> <fax section end>
…
<key><delimiter><value> <fax section end>
All control files must have a common section, even if there are no keys in the common section.
General Processing
The Batch Loader will poll a fax folder for all control files. For each control file it finds it will parse the control file for keys and values representing fax information. The keys are defined in the configuration file. There can be more than one fax defined in a single control file. As the control file is being processed, its name is changed to “*.working”.
When a control file is successfully completed, it is deleted along with the corresponding fax files. Optionally the control, sent file, and fax files can be moved to another folder and not be deleted. The sent file contains Fax job IDs so this file could be used for a fax completion verification process.
When the Batch Loader is done with all of the control files, it will repeat the above steps for the next folder to poll. Once all folders have been polled, it will stop and wait a configured amount of time before polling the folders again.
Error Handling and Recovery
The error recovery mechanism is controlled by the auto_recover parameter. If auto recovery is enabled, then each control file is appended with “.working” as it is processed. If there is an error, the control file’s name is unchanged. When the batch loader starts its next iteration, all *.working files will be processed again.
If auto recovery is disabled, then after a control file is processed, if there is an error, the file will be renamed to “*.error”. These error files need to be corrected and then renamed without the “.error” extension. Then they will be picked up by the Batch Loader on its next iteration. If the configuration setting, delete_when_done, is set to false, and there is an issue while moving the control file to the “done” folder, then the control file will be renamed to *.error. An administrator will need to manually address this issue.
10
After a successful fax request is made to the Softlinx Cloud Service, a *.sent file is created that corresponds to the control file being processed. Contained in the *.sent file will be a line for each fax request made. The recipient fax number will be on each line unless the
key_unique_fax_key or key_unique_fax_id parameters are set. Additionally each line will
contain the Fax Job ID (Ex: [FAXID: 123]). If an error occurs when processing subsequent faxes from the same control file, this *.sent file is used to ensure duplicate faxes are not sent when the control file is reprocessed.
Logging is sent to the ReplixFaxBatchLoader.log file. This file will contain all errors and may contain send, info and warning messages depending on the logging_level parameter.
The Windows Event Log will contain an Application error for every “bad” control file if the
errors_to_event_log parameter is set to true.
Event ID will be “100” for control file issues. Event ID will be 200 for configuration or other issues.
A ReplixFaxBatchLoaderError.log is also created when there is an error processing a control file. The specific control file with the issue is appended to the file. Note that if auto recovery is enabled and there are errors in a control file, this error file and the log file will grow in size.
On startup of the service, informational information will be added to the event viewer, such as registry values. If there are errors, these too will be in the event viewer.
11
Samples
1. Obtain the following from Softlinx Support:
a. admin username (including organization name ex: admin@demo) b. admin password
c. non-admin username 2. Stop the Batch Loader Service
3. Copy batchload1.config from samples folder to installation folder. 4. Create a folder called c:\faxes
5. Copy the sample control files and sample PDF files that you want to try to the c:\faxes folder
6. Edit the batchload1.config and set the replix_user and replix_password based on the values obtained from Softlinx. Remember to encrypt the password.
7. Edit the control files and replace the username with the non-admin user obtained from Softlinx. If you want to try the control file that uses two non-admin users, then ask Softlinx support for another non-admin user. You can also create another user by accessing the web portal at https://faxtest.softlinx.com (https://www.rpxfax.com for production). Use the admin username and password to login.
8. Start the Batch Loader via Windows Services.
9. The control files should be processed and moved to the “done” folder. To see how error recovery works, try the following steps:
1. Stop the Batch Loader service
2. Set auto_recover=false in the configuration file
3. Copy unique_id.ctrl and test1.pdf from the samples folder to the c:\faxes folder. Do NOT copy test2.pdf.
4. Start the Batch Loader service.
5. The first fax should have been send, but not the second fax because of a missing pdf file.
6. In the c:\faxes folder, the file unique_id.ctrl should have been renamed to
unique_id.ctrl.error. There should also be a file named unique_id.ctrl.sent. If you open unique_id.ctrl.sent, there should be a line with the unique id of the fax and the fax job id. Ex: “1 [FAXID: 82]”
12 8. Rename unique_id.ctrl.error to unique_id.ctrl.
9. The files should be processed and moved to the c:\faxes\done folder.
10. Open the c:\faxes\done\unique_id.ctrl.sent file. There should be two lines in there. One for the first fax and then one for the second fax.
Troubleshooting
If the Batch Loader Service fails to start, look in the Windows Event Viewer. If there are any missing registry values, they will be reported in the Event Viewer.
If the Batch Loader fails to process a control file, then look in the ReplixFaxBatchLoader.log file located in the installation folder. If details of the error are not in the log file, then make sure the logging_level in the configuration file is set to “3”.
Errors with a specific control file will result in the control file being renamed *.error. If there is an issue with the configuration file, then no control files will be processed.
Softlinx, Inc. 100 Riverpark Drive North Reading, MA 01864 Tel: +1.978.881.0560 Fax: +1.978.664.0181 www.softlinx.com
