ReplixFax Batch Loader

ReplixFax Batch Loader Admin Guide December 2015 Version 3.1.15

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.

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 TROUBLESHOOTING... 12 ii

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. 1

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. Do not start the service until you have completed all the configuration steps. 2

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. 3

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 auto_recover continue_on_error control_file_filter delete_when_done errors_to_event_log files_full_path folder_done Description 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 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. 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 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. Write event to Windows Event Log. Codes in event log: 100: bad control file 200: bad configuration. 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 to put completed control files and corresponding documents. This will only be used if delete_when_done is set to false. 4

folder_monitor ignore_fax logging_level replix_password replix_url replix_user Folder to poll for control files that indicate faxes to send. This folder must exist or the Batch Loader will log an error. Do not send faxes to this fax number. Logging level. Accepted values are: 0 - errors only 1 successful sent fax information 2 warnings and errors 3 - log everything Encrypted password for the Replix user. See "Encrypting passwords" section for details on how to encrypt a password. 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 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 comment_indicator common_section_end Description String indicating that line should be ignored Example: # String indicating end of common section. Example: @+COMMON 5

fax_section_end key_batch key_cover key_delimiter key_file key_from keys_ignore key_message key_project1 key_project2 key_recipient_company String indicating end of fax section. Example: @+END The name of the batch. This should be in the common section of the control file. Example: BATCH_NAME Cover page key. This should be in the common section of the control file. Example: COVERPAGE Separator for key and value. Example: = Key to indicate name of the file to send in the fax. Example: FILE_NAME 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 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 Cover Page message key. Only use if use_coverpage is true. Example: COVERPAGE_MESSAGE Key for project code 1. In the Softlinx Cloud service clients, this is referred to as Keyword. Example: PROJECT_CODE1 Key for project code 2. In the Softlinx Cloud service clients, this is referred to as Account. Example: PROJECT_CODE2 Key for recipient s company. Only applicable if using Softlinx cover page template. Example: RECIPIENT_COMPANY 6

key_recipient_fax key_recipient_name key_recipient_title key_recipient_voice key_unique_fax_id key_unique_fax_key Key for recipient s fax number. Example: RECIPIENT_FAX Key for recipient s name. Only applicable if using Softlinx cover page template. Example: RECIPIENT_NAME Key for recipient s title. Only applicable if using Softlinx cover page template. Example: RECIPIENT_TITLE Key for recipient s voice number. Only applicable if using Softlinx cover page template. Example: RECIPIENT_VOICE 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 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. 7

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. 8

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. 9

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. 10

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] 7. Now copy the test.pdf file from the samples folder to the c:\faxes folder. 11

8. Rename unique_id.ctrl.error to unique_id.ctrl. ReplixFax Batch Loader Administration Guide 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. 12

Softlinx, Inc. 100 Riverpark Drive North Reading, MA 01864 Tel: +1.978.881.0560 Fax: +1.978.664.0181 www.softlinx.com