RightFax Integration Module Guide
-
Upload
henrykylaw -
Category
Documents
-
view
343 -
download
1
Transcript of RightFax Integration Module Guide
-
7/31/2019 RightFax Integration Module Guide
1/226
Version 9.3
Integration Module Guide
www.ingeniumsw.com770-936-0600
-
7/31/2019 RightFax Integration Module Guide
2/226
Edition
Information in this document applies to version 9.3 of the RightFax Integration Module Guide.
Copyright Notice
2006 Captaris. All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form by any means without the written permission
of Captaris. Captaris products Interchange, RightFax and Teamplate are trademarks of Captaris. All other company, brand and product names are the property and/or trademarks of their respective companies.
Captaris
10885 NE 4th Street
Suite 400
Bellevue, WA 98004
(425) 455-6000
http://www.captaris.com
Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted.
Portions of this product Copyright 2002-2006 Glyph & Cog, LLC. Portions Copyright 2001 artofcode LLC. This software is based in part on the work of the Independent JPEG Group. This software is based in part on the
work of the Freetype Team. Portions Copyright 1998 Soft Horizons. Portions Copyright 2001 URW++. All Rights Reserved. Outside In Viewer Technology 1992-2004 Stellent Chicago, Inc. All rights reserved. Includes
Adobe PDF Library technology. Adobe, Acrobat and the Acrobat logo are trademarks of Adobe Systems Incorporated. Portions Copyright 1999 Ligature. Portions Copyright TMS, Inc. 1994-2001. All rights reserved.
Certain portions of this software are copyrighted by Ligature Ltd. who makes no representation or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability and fitness for
any particular purpose. The Ligature portion of the software is licensed by Ligature as is.
For More Information
Captaris is a leading provider of Business Information Delivery solutions that integrate, process and automate the flow of messages, data and documents. Captaris produces a suite of proven products and services, in partnership
with leading enterprise technology companies, delivered through a global distribution network. Captaris has installed over 80,000 systems in 44 countries, with 93 of the Fortune 100 using the company's award-winning products
and services to reduce costs and increase the performance of critical business information investments. For more information please contact us at www.captaris.com or call +1.520.320.7000.
RightFax 9.3 Integration Module Guide ii
-
7/31/2019 RightFax Integration Module Guide
3/226
iii
Chapter 1 Introduction.............................................................................. 7
Using This Guide...............................................................................8Other Resources for RightFax Users ...........................................8Getting Help Online .........................................................................8Captaris Training Services..............................................................9Captaris Implementation Services ................................................9Customer Support............................................................................9
Chapter 2 Overview ................................................................................. 11Features of the Integration Module ............................................11Understanding Document Recognition .................................... 12Understanding Document Distribution...................................... 12
Chapter 3 Installing the RightFax Integration Module ..................15
Installing the Integration andBusiness Integration Modules .................................................15
Chapter 4 Connecting to the RightFax Server ................................. 17
Guidelines for Common Connection Methods....................... 18
Chapter 5 Connecting with IBM WebSphere MQ............................21
Minimum System Requirements..................................................21Installing and Configuring the
IBM WebSphere MQ Software ...............................................21Installing WebSphere MQ on the RightFax Server.................22Installing WebSphere MQ as a Server......................................23Creating Message Queues in WebSphere MQ......................23
Chapter 6 Using the Integration Setup Wizard ................................29
Chapter 7 Configuring the Integration Moduleto Receive Data .....................................................................33
Creating an Input Device ..............................................................33Setting Up a Named Pipe Capture.............................................35Setting Up Directory Scanning................................................... 36Setting Up a Serial Capture.........................................................37Setting Up a TCP/IP Port Capture ............................................ 39Setting Up an IBM WebSphere MQ Connection.................. 40
Contents
-
7/31/2019 RightFax Integration Module Guide
4/226
-
7/31/2019 RightFax Integration Module Guide
5/226
-
7/31/2019 RightFax Integration Module Guide
6/226
RightFax 9.3 Integration Module Guide vi
-
7/31/2019 RightFax Integration Module Guide
7/226
7
Chapter 1
Introduction
The RightFax Integration Module enables applications forinformation exchange by integrating with applications onmainframe, mid-range, and local area network host systems.Together, the RightFax server and the Integration Module will sendany document created by these applications via fax, e-mail, or overthe Internet.
The RightFax Integration Module automates batch-oriented,
repetitive processes. It is designed to support applications thatproduce output that traditionally is sent to a printer, printed onpre-printed forms, folded, stuffed in envelopes, and then mailed ormanually faxed. These documents can include invoices, itineraries,purchase orders, statements, order confirmations, loanapplications, bills of lading, change orders, financial reports, andmaterial safety data sheets.
The RightFax system can integrate with many applications. Theintegration options are listed in the following table, along with theRightFax documentation where you can refer for more information.
Table 1a RightFax Integration Options
Integration option
Refer to these resources for
information
Integration Module serviceson the RightFax server withFacsimile CommandLanguage (FCL)
Chapters 2-24 in this guideRightFax Administrators Guide
RightFax XML Interface Chapter 25, Programming for theRightFax XML Interface in this guide
RightFax API for Java Chapter 26, Programming for theRightFax API for Java in this guide
RightFax COM Module RightFax COM Module Guide
RightFax C, C++, andVisual Basic API
www.captaris.com/implementation_services
-
7/31/2019 RightFax Integration Module Guide
8/226
-
7/31/2019 RightFax Integration Module Guide
9/226
Chapter 1 Introduction 9
Captaris Training Services
RightFax training gives you the skills to optimize your RightFaxsolution. Our comprehensive technical, administrative, and usertraining programs produce full utilization and understanding ofRightFax products. Regular classes are held at the state-of-the-artRightFax Training Center in Tucson, Arizona, throughout the year, oryou can choose the convenience of training at one of our regionallocations. Training materials and computer-based training tools arealso available. For more information on RightFax training, please
visit our Web site at www.captaris.com/training, or call us at(520) 320-7098 and let us help you develop a customized trainingplan for your organization.
Captaris Implementation Services
Captaris Implementation Services offers a team of highly skilledengineers who are experts in the deployment, implementation, and
integration of RightFax solutions. Implementation services includeinstallation and configuration, upgrades, configuration review, andadvanced integration services. Whether it's through remote dial-in,an on-site implementation, or a combination of both, theImplementation Services team can quickly integrate RightFaxsolutions with your existing applications.
Customer SupportYour Customer Support Guide includes detailed information aboutthe support options available to RightFax customers. Please fill outthe RightFax Software Warranty & Registration Cardand return itimmediately. If you have questions of a technical nature, contactyour organizations RightFax administrator or network administratorbefore calling the RightFax customer support department. On theRightFax Web site, a database of customer support knowledge
contains a wealth of information on installing, configuring, andmaintaining RightFax software.
RightFax Customer Support:
CaptarisSuite 2106303 E. Tanque VerdeTucson, Arizona 85715 USA
Voice: (520) 320-7070Fax: (520) 321-7461Web: www.captaris.com/rightfaxE-mail: [email protected]
5:00 A.M. to 5:00 P.M. Pacific time, Monday through Friday
7:00 A.M. to 3:00 P.M. Pacific time, Saturday
Support Sales and Administration: (520) 320-7000
-
7/31/2019 RightFax Integration Module Guide
10/226
RightFax 9.3 Integration Module Guide 10
-
7/31/2019 RightFax Integration Module Guide
11/226
11
Chapter 2
Overview
This chapter provides an overview of the Integration Moduleservices that can be implemented on the RightFax server withFacsimile Command Language (FCL). It describes the features ofthe Integration Module and the workflow and programs thatrecognize data, assemble the data into documents, distributedocuments, and report the results.
Features of the Integration Module
In addition to the power of the RightFax server for managingtransmissions, the Integration Module provides the followingfeatures.
Formatting documents
The Integration Module can:
Add lines, boxes, and other shapes to a document.
Set fonts, margins, and tabs.
Add graphics to a document, such as a signature or a companylogo.
Add a background form over which the document data is placed,such as a purchase order form, bill of lading, or itinerary.
Scheduling documents
In addition to the scheduling control provided by the RightFaxserver, the Integration Module can:
Delay the sending of a document by minutes or schedule thedate and time for a document to be sent.
Prioritize a document for sending.
Hold a document for approval. Send documents in batches.
Broadcast faxes.
Attaching cover sheets and other attachments
When a document is processed by the Integration Module,additional documents can be attached, including cover sheets.Information for the cover sheet can be provided by FCL codes.
Including data from a lookup table
A document from a host-based application may not include all theinformation that is needed to send it, such as a fax number. You cancreate a table of data where the Integration Module can look upthe needed data.
-
7/31/2019 RightFax Integration Module Guide
12/226
-
7/31/2019 RightFax Integration Module Guide
13/226
Chapter 2 Overview 13
For a list of the programs that process and send documents, see
Appendix A, Integration Module Programs.Figure 2.1 Flow of Documents in the Integration Module
Figure 2.2: Integration Module Data Flow shows how FCL
documents are processed after the Integration Module receives thedata stream from a host application. It explains the programs, suchas Makedoc.exe, that are shown briefly in Figure 2.1: Flow ofDocuments in the Integration Module.
Figure 2.2 Integration Module Data Flow
-
7/31/2019 RightFax Integration Module Guide
14/226
RightFax 9.3 Integration Module Guide 14
-
7/31/2019 RightFax Integration Module Guide
15/226
15
Chapter 3
Installing the RightFax Integration Module
The RightFax Integration Module enables applications forinformation exchange by integrating with applications onmainframe, mid-range, and local area network host systems. Tomeet the needs of small, medium, and large enterprises, theRightFax Integration Module comes in two versions: the IntegrationModule which includes full functionality, and the BusinessIntegration Module which includes a limited set of features for useby smaller organizations.
Installing the Integration and Business
Integration Modules
The RightFax Integration Module and Business Integration Modulesoftware are installed automatically during the RightFax serverinstallation. To enable the functionality of these modules, they mustbe licensed and then simply enabled on the RightFax server. Forinformation on enabling or adding new components to a RightFaxserver, refer to the RightFax Installation Guide.
To install the RightFax Enterprise Integration Module
1. Install the RightFax server, as described in the RightFaxInstallation Guide.
2. Configure the RightFax server, as described in the RightFaxAdministrators Guide.
3. If the Integration Module service does not appear in EnterpriseFax Manager, you need to create the service. To do so, openWindows Control Panel. Double-click the RightFax Integrationprogram to start it. The Integration Module Configurationwindow opens. ClickOK, and the service will be created.
Table 3a RightFax Integration Module types
Module Features
RightFax IntegrationModule
70 input channels.
Output methods of fax, certified email,encrypted email, or print.
Up to 70 filter templates.
Up to 128 notification channels. Unlimited notification messages.
RightFax BusinessIntegration Module
Two input channels.
One output method (fax or print) perinput channel.
Two fax channels for each fax output.
One filter template per input channel.
Unlimited notification messages.
RightFax 9 3 Integration Module Guide 16
-
7/31/2019 RightFax Integration Module Guide
16/226
RightFax 9.3 Integration Module Guide 16
4. Configure the Integration Module software, as described later inthis guide.
-
7/31/2019 RightFax Integration Module Guide
17/226
17
Chapter 4
Connecting to the RightFax Server
This chapter explains the most common methods for connecting ahost computer to the Integration Module computer for FCL-baseddocuments.
Because several methods can be used to connect a host computerto the Integration Module on the RightFax server, you mustdetermine the best choice for the capabilities of the host systemenvironment and the distribution methods for documents and
notifications about sent documents.Because of the wide range of host applications, environments, andpotential connection scenarios, this chapter does not providestep-by-step connection procedures.
RightFax 9.3 Integration Module Guide 18
-
7/31/2019 RightFax Integration Module Guide
18/226
RightFax 9.3 Integration Module Guide 18
The following figures illustrate the most common connectionmethods. Some connections require third-party software thatCaptaris does not provide or support.
Figure 4.1 Connections to Applications that Generate FCL or ASCII Data
Figure 4.2 Connections to Host Applications that Generate XML and Java Data
Guidelines for Common Connection Methods
The most common communication connection methods and basicrequirements are described in the following sections:
Line printer remote (LPR) connection on page 19
3270 emulation on page 19 TCP/IP socket connection on page 19
File Transfer Protocol (FTP) connection on page 19
5250 emulation on page 19
IBM WebSphere MQ client v5.1 for Microsoft Windows NT onpage 20
-
7/31/2019 RightFax Integration Module Guide
19/226
RightFax 9.3 Integration Module Guide 20
-
7/31/2019 RightFax Integration Module Guide
20/226
The protocol converter sends data to the RightFax server via aserial cable connected between the converter and one of the COMports on the RightFax server. If this method is used, the IntegrationModule must be configured to accept input on the serial port.
To send notification messages back to the host, SQL via ODBC isrecommended. Emulation software via 32-bit high level languageapplication programming interface (HLLAPI) or via a serialconnection also can be used.
To configure the Integration Module to receive data via this method,see Setting Up a Serial Capture on page 37.
IBM WebSphere MQ client v5.1 for Windows NT
The RightFax Integration Module can communicate with an IBMWebSphere MQ channel via TCP/IP. For instructions onconnecting with IBM WebSphere MQ, see Chapter 5,Connecting with IBM WebSphere MQ.
To configure the Integration Module to receive data via this method,see Setting Up an IBM WebSphere MQ Connection on page 40.
-
7/31/2019 RightFax Integration Module Guide
21/226
21
Chapter 5
Connecting with IBM WebSphere MQ
This chapter explains how to connect the host computer to theRightFax Integration Module computer using IBM WebSphereMQ v5.1 for Window NT 4.0. This installation usually is performedwith support from Captaris Implementation Services.
Minimum System Requirements
Before installing WebSphere MQ, install the RightFax server andIntegration Module software on the server computer.
Install the following on the client and the server computers:
Adobe Acrobat v3.02 or later
Microsoft Internet Explorer v5.5 or later
Microsoft Active Directory Services Interface (ADSI) v2.0 orlater
Microsoft Management Console (MMC) v1.1 or laterIn addition, WebSphere MQ requires that the two computers beconfigured with static IP addresses.
Installing and Configuring the
IBM WebSphere MQ Software
WebSphere MQ offers numerous configuration options that are notdescribed in the steps in this chapter. The procedures in thischapter are for a basic setup, but you can set options for limitingmessage sizes, limiting the number of messages, default priority,default persistence, etc. For more information on these
configurations, see the WebSphere MQ documentation.
To install and configure IBM WebSphere MQ to work with theRightFax Integration Module, complete the following steps:
1. Install the WebSphere MQ client on the RightFax server(page 22).
2. Install the WebSphere MQ server on a separate computer(page 23).
3. Create message queues in WebSphere MQ (page 23).
4. Configure the RightFax Integration Module to communicate withWebSphere MQ. For instructions, see Setting Up an IBMWebSphere MQ Connection on page 40.
RightFax 9.3 Integration Module Guide 22
-
7/31/2019 RightFax Integration Module Guide
22/226
Installing WebSphere MQ on the RightFax Server
This step installs WebSphere MQ on the RightFax server as aclient.
Before you begin, arrange down-time for the Integration Module.Performing these steps (which include restarting the computer) onthe Integration Module computer will cause document transmissionto stop.
To install WebSphere MQ on the RightFax server
1. Insert the WebSphere MQ CD into the computer running theRightFax Integration Module.
2. Run the WebSphere MQ setup program by double-clickingSetup.exe. The Select Setup Language dialog box appears.
3. Select the appropriate language, and clickNext. The ChooseInstallation Folders dialog box appears.
4. Select the folder where the WebSphere MQ software shouldbe installed, and clickNext. The Setup Type dialog boxappears.
5. Select Custom, and clickNext. The Select Componentsdialog box appears.
Figure 5.1 The Select Components Dialog Box
6. Select the Clients and Documentation in Englishcheck-boxes, and clickNext. The Select Program Folderdialog box appears.
7. Select a folder to install the program icons, and clickNext. TheInstallation Summary dialog box appears.
8. Review the installation summary.
If the installation summary is correct, clickNext.
If the installation summary is notcorrect, clickBackto makecorrections.
When you clickNext, the Setup Complete dialog box appears.
9. Clear all of the check boxes, and clickFinish.
10.Restart the computer.
-
7/31/2019 RightFax Integration Module Guide
23/226
Chapter 5 Connecting with IBM WebSphere MQ 23
Installing WebSphere MQ as a Server
This step installs WebSphere MQ as a server.
To install WebSphere MQ on another computer as a server
1. Insert the WebSphere MQ CD into the WebSphere MQ servercomputer.
2. Run the WebSphere MQ setup program by double-clickingSetup.exe. The Select Setup Language dialog box appears.
3. Select the appropriate language, and clickNext. The ChooseInstallation Folders dialog box appears.
4. Select the folder in which you want to install the WebSphereMQ software, and clickNext. The Setup Type dialog boxappears.
5. Select Custom, and clickNext. The Select Componentsdialog box appears.
Figure 5.2 The Select Components Dialog Box
6. Select the Server and Documentation in English check boxes,and clickNext. The Set Up Default Configuration dialog boxappears.
7. Clear the Set up a default configuration check box, and clickNext. The Select Program Folder dialog box appears.
8. Select a folder to install the program icons, and clickNext. TheInstallation Summary dialog box appears.
9. Review the installation summary.
If the installation summary is correct, clickNext. Dependingon the version of WebSphere MQ, you might be promptedregarding licensing. If so, follow the prompts until you reachthe Setup Complete dialog box
If the installation summary is not correct, clickBackto makecorrections.
When you clickNext, the Setup Complete dialog box appears.
10.Clear all of the check boxes, and clickFinish.
11.Restart the computer.
Creating Message Queues in WebSphere MQ
In this step, you create and configure queues in WebSphere MQ.For detailed information on these settings, see the WebSphere MQdocumentation.
1. Create a queue manager (page 24).2. Create a local queue for sending documents and a local queue
for receiving notifications messages from the RightFaxIntegration Module (page 26).
3. Create a client channel (page 27).
RightFax 9.3 Integration Module Guide 24
-
7/31/2019 RightFax Integration Module Guide
24/226
To create a queue manager
1. On the WebSphere MQ server computer, on the Start menu,clickIBM MQSeries, and then MQSeries Explorer. TheWebSphere MQ console window appears.
Figure 5.3 The Console Window
2. Right-clickQueue Managers and choose New > QueueManager. The Create Queue Manager (Step 1) dialog boxappears.
Figure 5.4 The Create Queue Manager (Step 1) Dialog Box
-
7/31/2019 RightFax Integration Module Guide
25/226
Chapter 5 Connecting with IBM WebSphere MQ 25
3. Enter a descriptive name in the Queue Manager box, and clickNext. The Create Queue Manager (Step 2) dialog boxappears.
Figure 5.5 The Create Queue Manager (Step 2) Dialog Box
4. Accept all defaults by clicking Next. The Create QueueManager (Step 3) dialog box appears.
Figure 5.6 The Create Queue Manager (Step 3) Dialog Box
5. Accept all defaults by clicking Next. The Create QueueManager (Step 4) dialog box appears.
Figure 5.7 The Create Queue Manager (Step 4) Dialog Box
RightFax 9.3 Integration Module Guide 26
-
7/31/2019 RightFax Integration Module Guide
26/226
6. In the Listen on port number box, enter 1414. This is thedefault port assigned to WebSphere MQ. If you need to useanother port number, contact your WebSphere MQ systemadministrator. ClickFinish.
To create local queues
In this step, create two local queues: a local queue for sendingdocuments and a local queue for receiving notifications messagesfrom the RightFax Integration Module.
1. In the WebSphere MQ console window, right-clickQueues,and choose New > Local Queue.
Figure 5.8 The Console Window
The Create Local Queue dialog box appears.
Figure 5.9 The Create Local Queue Dialog Box
2. In the Queue Name box, enter a descriptive name for sendingdocuments. Leave all other fields and options at their defaultsettings, and clickOK. The WebSphere MQ window appears.
3. Repeat this procedure to create a local queue for notificationmessages.
-
7/31/2019 RightFax Integration Module Guide
27/226
Chapter 5 Connecting with IBM WebSphere MQ 27
To create a client channel
1. In the WebSphere MQ console window in the Advanced folder,right-clickChannels and choose New > Server ConnectionChannel. The Create Server Connection Channel dialog boxappears.
Figure 5.10 The Create Server Connection Channel Dialog Box
2. In the Channel Name box, enter a descriptive name. Leave allother fields and options at their default settings, and clickOK.
RightFax 9.3 Integration Module Guide 28
-
7/31/2019 RightFax Integration Module Guide
28/226
-
7/31/2019 RightFax Integration Module Guide
29/226
29
Chapter 6
Using the Integration Setup Wizard
The RightFax Integration Module includes a wizard that helps youto create configurations for many of the connection methods. Usethe wizard to:
Configure the Integration Module service and set defaults fordocuments that are sent from the Integration Module.
Configure input channels from the host application to theIntegration Module.
Set notification actions and messages. You can choose to printor fax copies of documents as they are transmitted. You also candefine messages with descriptive information about thedocuments as they are transmitted.
Format documents with filter templates.
The Integration setup wizard is designed to guide you through eachstep of configuring the Integration Module. Instructions in thisguide supplement the instructions in the wizard. Captaris
recommends that you review the topics in this guide before youbegin using the wizard.
To start the wizard
1. On the Start menu, select Programs > RightFax > EnterpriseFax Manager. The Enterprise Fax Manager window opens.
2. In the Fax Servers list, click the name of the server where the
Integration Module is running.
3. In the Service Name list, double-clickRightFax IntegrationModule. The Integration Module Configuration windowopens.
Figure 6.1 The Integration Module Configuration Window
RightFax 9.3 Integration Module Guide 30
-
7/31/2019 RightFax Integration Module Guide
30/226
4. ClickIntegration Setup Wizard. The wizard starts, and theIntegration Setup Wizardwindow appears.
Figure 6.2 The Integration Setup Wizard
This window is the starting point for the configuration. Select fromthe configuration tasks, as described in the following sections.
Configure the Integration Module service
In this series of steps, you can define information that will appearon each fax that is sent from the Integration Module. Some of thesesettings can be overridden with facsimile command language(FCL) in the documents that are sent.
You can make the following default settings for documents:
Name and fax number to appear on the cover sheet.
File to send as the cover sheet. The default printer for documents sent from the Integration
Module.
Fax image quality.
Page length, page size, and reducing the image size to fit thepage.
These settings are also described in Chapter 10, Setting Defaultsfor FCL Documents.
Define inputs for the host application
In this series of steps, you can define the settings for receiving datafrom host applications via a named pipe, directory, TCP/IP, IBMWebSphere, or a custom input type.
For each communication method, you will specify thecommunications protocol and transmission method, port, directory,or queue to monitor, and the configurations needed for eachprotocol. You will:
1. Name the input.
2. Specify the input type.
3. Configure the input.
These settings are also described in Chapter 7, Configuring theIntegration Module to Receive Data.
Set notification actions and messages
In this series of steps, you can define notification actions and
messages.
Notification actions can:
Fax sent documents, whether successfully or not successfullytransmitted, to an internal fax number.
Print or fax documents that cannot be successfully transmittedbecause data is missing.
Notification messages can:
Notify users that a document was sent.
Notify an administrator of the status of documents.
-
7/31/2019 RightFax Integration Module Guide
31/226
Chapter 6 Using the Integration Setup Wizard 31
Notification messages can provide descriptive information, such aswhether or not a document was transmitted, explanations of errors,
and transmission duration, dates, and times. These messages aresent to a host application from the Integration Module when itprocesses and sends documents.
These settings are also described in:
Chapter 22, Setting Up Notification Messages of DocumentTransmission
Chapter 24, Setting Up Actions on Document Transmission
Format documents
In this series of steps, you can create filter templates fordocuments with MapText. These settings are also described inChapter 11, Creating Filter Templates.
RightFax 9.3 Integration Module Guide 32
-
7/31/2019 RightFax Integration Module Guide
32/226
-
7/31/2019 RightFax Integration Module Guide
33/226
33
Chapter 7
Configuring the Integration Moduleto Receive Data
This chapter describes the procedures for configuring the RightFaxIntegration Module to receive data. You will create an input devicefor receiving or retrieving data by writing a command line for eachtype of input needed in the system.
Note that command lines are case-sensitive.
Creating an Input Device
1. On the Start menu, select Programs > RightFax > EnterpriseFax Manager. The Enterprise Fax Manager window opens.
2. In the Fax Servers list, click the name of the server where theIntegration Module is running.
3.In the Service Name list, double-clickRightFax IntegrationModule. The Integration Module Configuration windowopens.
4. In the left pane of theIntegration Module Configurationwindow, clickInputs. The input settings appear.
Figure 7.1 The Inputs Settings
RightFax 9.3 Integration Module Guide 34
-
7/31/2019 RightFax Integration Module Guide
34/226
5. Right-clickInputs, and select Add Input Device from theshortcut menu. The Add Input Device dialog box appears.
Figure 7.2 The Add Input Device Dialog Box
6. In the Input Type list, select the type of data input needed forthe communication method implemented for the host system.When you select an option, the available settings for the input
appear in theIntegration Module Configurationwindow.
7. Enter the settings for the type of data input, as described in thefollowing sections:
Setting Up a Named Pipe Capturepage 35
Setting Up Directory Scanningpage 36
Setting Up a Serial Capturepage 37 Setting Up a TCP/IP Port Capturepage 39
Setting Up an IBM WebSphere MQ Connectionpage 40
To create the settings for an input, you will type a command lineor select options in the dialog box. When you select an option inthe dialog box, the option appears in the command line. Forexample, when you select the check box Display VerboseOutput, -v appears in the Complete Command Line box.
Figure 7.3 The Integration Module Configuration Window
Thecommandline appearsas you makeentries.
-
7/31/2019 RightFax Integration Module Guide
35/226
Chapter 7 Configuring the Integration Module to Receive Data 35
Setting Up a Named Pipe Capture
This procedure creates an input device that receives data from ahost application via a named pipe. The program Nplisten.execreates a named pipe, scans it, and then executes a command ondata found in the pipe. Typically, this input type accommodatesdata that is formatted for a line printer (LPR).
To set up a named pipe capture
1. In the Input Type list, select Named Pipe (LPR). The named
pipe settings appear.
Figure 7.4 Settings for a Named Pipe Input Device
2. Select the check box Enable this Input device.
3. In the Name box, enter a descriptive name for this input device.
4. Complete the entries in the dialog box, as described in thefollowing table. These settings correspond to Nplisten.exe
command line options.
Example nplisten.exe -c makedoc $$ -p hplpr
In this example, Nplisten.exe will run the command makedoc on
files received via the named pipe. The variable $$ indicates that allfiles will be processed with Makedoc.exe. Hplpr is a name for anLPR printer.
Table 7a Add Input Device Settings for a Named Pipe
Setting
Command line
option Description
Named Pipe toCreate
-ppipename The name of the named pipethat Nplisten.exe will monitorfor files. You can enter any
name for the pipe in one of thefollowing formats:
pipename
\\.\pipe\pipename
Execute onInput (-coption)
-c makedoc $$ The command to execute onfiles received via the namedpipe. Makedoc.exe begins theprocess of converting data
from the host application into afax.
The variable $$ indicates thatall files should be processedwith Makedoc.exe.
RightFax 9.3 Integration Module Guide 36
-
7/31/2019 RightFax Integration Module Guide
36/226
Setting Up Directory Scanning
This procedure creates an input device that retrieves data byscanning a folder for files. The program Bufdir.exe retrieves thefiles.
To set up directory scanning
1. In the Input Type list, select Directory. The directory settingsappear.
Figure 7.5 Settings for a Directory Scanning Device
2. Select the check box Enable this Input device.
3. In the Name box, enter a descriptive name for this input device.
4. Complete the entries in the dialog box, as described in thefollowing table. These settings correspond to Bufdir.execommand line options.
Table 7b Add Input Device Settings for Directory Scanning
Setting
Command
line option Description
Pattern to usefor FilenameSearch
-ppattern Enter the file types for whichBufdir.exe will scan, for example,*.txt. The default is *.*.
Dont deleteInput Files
-d This setting is useful when testingthe connection to the host
application. It determines whetheror not the files in the folder aredeleted after they are retrieved byBufdir.exe.
Files are deleted by default.
Exit Code -r code This setting determines that fileswill not be deleted until theprogram encounters a specifiedexit code.
# of Threads -t threads Specifies the maximum number ofthreads of Bufdir.exe to runsimultaneously. The default is 1.
Exit after onepass throughFolder
-o Quit after scanning the folderonce.
Secs. to Loop -l seconds This setting is commonly used
with a shared folder on WindowsNT.
Enter the interval in seconds thatBufdir.exe will scan for files. Thedefault is to scan the folder whennotified by Windows that a filehas been placed in the folder.
-
7/31/2019 RightFax Integration Module Guide
37/226
Chapter 7 Configuring the Integration Module to Receive Data 37
Example bufdir -c makedoc $$ c:\program
files\rightfax\production\inboxIn this example, Bufdir.exe will run the command makedoc on filesin the specified directory. The variable $$ indicates that all files willbe processed with Makedoc.exe.
Setting Up a Serial Capture
This procedure creates an input device that retrieves data via aserial port. The program Capture.exe retrieves the data.
To set up a serial capture
1. In the Input Type list, select Serial Capture. The serial capturesettings appear.
Figure 7.6 Settings for a Serial Capture Input Device
2. Select the check box Enable this Input device.
3. In the Name box, enter a descriptive name for this input device.
Secs. to Age -w seconds This setting assures that the file isup to date before it is processed.If your network is slow, this settingprovides time for the completeddocument to be delivered to thefolder.
Enter the number of seconds to
wait before retrieving the file.
Dont check forfile in use
-u This setting determines thatBufdir.exe will not check for files inuse before retrieving them.
Folder toMonitor
Folder nameand path
Enter the name of or the path tothe folder to watch fordocuments.
Execute onInput (-c option) -c makedoc$$ The command to execute on filesreceived. Makedoc.exe begins theprocess of converting data fromthe host application into a fax.
The variable $$ indicates that allfiles should be processed withMakedoc.exe.
Table 7b Add Input Device Settings for Directory Scanning (Continued)
Setting
Command
line option Description
RightFax 9.3 Integration Module Guide 38
4 C l t th t i i th di l b d ib d i th T bl 7 Add I t D i S tti f S i l C t (C ti d)
-
7/31/2019 RightFax Integration Module Guide
38/226
4. Complete the entries in the dialog box, as described in thefollowing table. These settings correspond to Capture.execommand line options.
Table 7c Add Input Device Settings for a Serial Capture
Input setting
Command
line option Description
End Sequence -S sequence Specify the sequence ofcharacters that will indicate theend of each document that isreceived via this serial port.
Handshaking -H
-x
Specify the handshaking method
for the serial port.H = Hardware handshaking
x = XON\XOFF (software)handshaking
Baud Rate -b baud rate The baud rate at whichCapture.exe will scan the serialport.
Bits/Character -C size Specify the number of bits (7 or
8) per character.ASCII Mode -a Select this check box to convert
carriage returns in a document tocarriage return-line feed pairs. Inother words, (carriagereturn) will be converted to (carriage return andline feed).
Left Brace Char -L character Specify one or more charactersthat form the left (opening)delimiter for FCL commands indocuments that are received viathis serial port. Usually this is apair of left braces ({{).
Right Brace
Char
-R character Specify one or more characters
that form the right (closing)delimiter for FCL commands indocuments that are received viathis serial port. Usually this is apair of right braces (}}).
Allow EOT orETB to endinput
-E Select this check box to specifythat an end-of-text character(ASCII 4 or CTRL+D) or anembeddedend-of-transmission-block (ETB)character (ASCII 23 orCTRL+W) will mark the end eachdocument that is received via thisserial port.
Stop Bits -s stopbits Specify the bit (0 or 1) that willindicate the end of eachdocument that is received via this
serial port.Parity -e
-o
Specify the parity for this serialport.
-e establishes even parity.
-o establishes odd parity.
Table 7c Add Input Device Settings for a Serial Capture (Continued)
Input setting
Command
line option Description
-
7/31/2019 RightFax Integration Module Guide
39/226
Chapter 7 Configuring the Integration Module to Receive Data 39
Example capture -b 9600 -c makedoc $$ com1
In this example, Capture.exe will read input from the COM1 serialport and then execute the command makedoc on the data. Thevariable $$ indicates that all files will be processed withMakedoc.exe.
Setting Up a TCP/IP Port Capture
This procedure creates an input device that retrieves data via aTCP/IP port. The program Portlstn.exe retrieves the data.
To set up a TCP/IP port capture
1. In the Input Type list, select TCP/IP Port. The TCP/IP portsettings appear.
Figure 7.7 Settings for a TCP/IP Port Input Device
2. Select the check box Enable this Input device.
3. In the Name box, enter a descriptive name for this input device.
COM1 orCOM2
N/A Specify the COM port. Thedefault is COM1.
Execute onInput (-c option)
-c makedoc$$
The command to execute on filesreceived. Makedoc.exe beginsthe process of converting datafrom the host application into afax.
The variable $$ indicates that allfiles should be processed withMakedoc.exe.
Table 7c Add Input Device Settings for a Serial Capture (Continued)
Input setting
Command
line option Description
RightFax 9.3 Integration Module Guide 40
4 Complete the entries in the dialog box as described in the TCP/IP port To configure the input you specify the channel name
-
7/31/2019 RightFax Integration Module Guide
40/226
4. Complete the entries in the dialog box, as described in thefollowing table. These settings correspond to Portlstn.execommand line options.
Example portlstn -c makedoc $$ -p 6250
In this example, Portlstn.exe will read input from TCP/IP port 6250
and then execute the command makedoc on the data. Thevariable $$ indicates that all files will be processed withMakedoc.exe.
Setting Up an IBM WebSphere MQ Connection
This procedure describes the configuration needed tocommunicate with an IBM WebSphere MQ remote queue
manager to retrieves messages (outgoing documents).The program mqget.exe utilizes the IBM WebSphere MQ client toconnect to the remote queue manager and retrieve messages fromthe specified remote queue. The communication input device is a
TCP/IP port. To configure the input, you specify the channel name,the host name, the queue manager, and the queue to retrieve themessages from.
To set up an IBM WebSphere MQ connection
1. In the Input Type list, select Custom. The custom settingsappear.
Figure 7.8 Settings for a Custom Input Device
2. Select the check box Enable this Input device.
3. In the Name box, enter a descriptive name for this input device.
Table 7d Add Input Device Settings for a TCP/IP Port Capture
Input setting
Command line
option Description
TCP/IP Port # -p number Enter the number of the port tomonitor.
Execute onInput (-coption)
-c makedoc $$ The command to execute onfiles received. Makedoc.exebegins the process ofconverting data from the hostapplication into a fax.
The variable $$ indicates thatall files should be processedwith Makedoc.exe.
-
7/31/2019 RightFax Integration Module Guide
41/226
Chapter 7 Configuring the Integration Module to Receive Data 41
4. In the Complete Command Line box, enter a command. TheMqget.exe command line syntax and options are described in
the following section.Syntax mqget -C channel-H hostname-M queuemanager
-Qqueue [options]
Example mqget -C RF_Chan -H qmmaster2 -M RightFax-Q RF_Queue -c makedoc $$ -p 1414 -1
In this example, Mqget.exe will monitor the IBM WebSphere MQchannel RF_Chan in the domain named Qmmaster2. It will connectto the queue manager RightFax and the queue named RF_Queue.
Data will be read via TCP/IP port 1414, and the command
makedoc will be executed on the data. The variable $$ indicatesthat all files will be processed with Makedoc.exe.
Table 7e Mqget.exe Command Line Options
Option Description
-C channel Name to use for this connection channel.
-H hostname Fully qualified domain name of the IBMWebSphere MQ queue manager.
-M queue manager Queue manager for RightFax that is defined onthe IBM WebSphere MQ server.
-Qqueue Queue to retrieve messages from. TheIntegration Module will monitor and retrievemessages from this queue.
-c makedoc $$ The command to execute on files received.
Makedoc.exe begins the process of convertingdata from the host application into a fax.
The variable $$ indicates that all files should beprocessed with Makedoc.exe.
-d Display debugging output. This is helpful if youexperience difficulty connecting to the server.
-pport TCP/IP port number to use for remoteconnection. The default is 1414.
-s seconds Interval for scanning the queue, in seconds. Thedefault is 15.
-1 Selects Version 1 of the WebSphere MQApplication Programming Reference.
This option must be used because MQGet.exeis not designed to work with the WebSphereMQ API Version 2.
-tCCSID Specifies the codeset name for a language. Alist of the codeset IDs (CCSIDs) supported by
WebSphere MQ is available from IBM.
Table 7e Mqget.exe Command Line Options (Continued)
Option Description
RightFax 9.3 Integration Module Guide 42
-
7/31/2019 RightFax Integration Module Guide
42/226
-
7/31/2019 RightFax Integration Module Guide
43/226
43
Chapter 8
Testing a Connection and an Input Device
This chapter describes methods for testing that the RightFaxserver, Integration Module, and host application are connected andcommunicating.
Testing a Named Pipe Connection
This procedure tests the connection from the host application to aprint input device on the RightFax server, as described in SettingUp a Named Pipe Capture on page 35.
To test the connection
1. Pause printing to the printer that was created for the namedpipe input.
2. Temporarily change the printer port to File.
3. Send a test document from the host application to the printer.
4. Look in the print queue to verify that the test document hasbeen sent to print.
5. Activate printing to the Integration Module printer, specifying thefile name for the document.
6. Open and examine the test document.
Documents that are created with filter templates (filter mode)will be plain ASCII text.
Documents that are created in native mode will be FCLdocumentsa combination of FCL commands and documentdata from the host application.
PCL or PostScript documents will be in PCL or PostScript
format with FCL commands on the first false page.7. Change the printer port back to the named pipe.
Testing Directory Scanning
This procedure tests the connection from a host system to a folderthat is scanned for files by the Bufdir.exe program, as described inSetting Up Directory Scanning on page 36.
To test the connection
1. Stop Bufdir.exe by stopping the Integration Module service inEnterprise Fax Manager.
2. Send a test document from the host application to the folderspecified in the Bufdir.exe command line.
3. Look in the target folder on the Integration Module to verify that
the test document was received.
RightFax 9.3 Integration Module Guide 44
4. Start the Integration Module service in Enterprise Fax Manager. To test the connection
-
7/31/2019 RightFax Integration Module Guide
44/226
Testing a Serial Connection
This procedure tests the connection from the host system to aserial port on the RightFax server, as described in Setting Up aSerial Capture on page 37.
To test the connection
1. Stop Buffer.exe using one of the following methods:
Stop it from the Process tab in Windows Task Manager.
Enter signal HFBufferStop at the command prompt. Enter kill /f buffer.exe at the command prompt (not
recommended).
2. Verify that Buffer.exe is stopped by looking in Windows TaskManager.
3. Send a test document from the host application to the serialport specified in the Capture.exe command line.
4. In Windows Explorer, navigate toRightFax\Production\Makedoc and verify that the test documentwas received.
5. In Enterprise Fax Manager, start Buffer.exe by stopping andstarting the Integration Module service.
Testing a TCP/IP Port Connection
This procedure tests the connection from the host application to aTCP/IP port on the RightFax server, as described in Setting Up aTCP/IP Port Capture on page 39
1. Stop Buffer.exe using one of the following methods:
Stop it from the Process tab in Windows Task Manager.
Enter signal HFBufferStop at the command prompt.
Enter kill /f buffer.exe at the command prompt (notrecommended).
2. Verify that Buffer.exe is stopped by looking in Windows TaskManager.
3. Send a test document from the host application to the TCP/IPport specified in the Portlstn.exe command line.
4. In Windows Explorer, navigate toRightFax\Production\Makedoc and verify that the test documentwas received.
5. In Enterprise Fax Manager, start Buffer.exe by stopping andstarting the Integration Module service.
Testing an IBM WebSphere MQ Connection
This procedure tests the connection from the host system to anIBM WebSphere MQ queue on the RightFax server, as describedin Setting Up an IBM WebSphere MQ Connection on page 40.
To test the connection
1. Open a command prompt window.
2. At the commandprompt, enter the command line that was
written to create the IBM WebSphere MQ input, and then pressENTER.
-
7/31/2019 RightFax Integration Module Guide
45/226
Chapter 8 Testing a Connection and an Input Device 45
If the connection is successful, then you should see text similar tothat shown in the following example. If the input connection is not
successful, then you will see error messages.
Figure 8.1 Successful Test of IBM WebSphere MQ Connection
RightFax 9.3 Integration Module Guide 46
-
7/31/2019 RightFax Integration Module Guide
46/226
-
7/31/2019 RightFax Integration Module Guide
47/226
47
Chapter 9
Creating FCL Documents
To create documents with FCL, you must insert FCL commandsinto the data stream that comes from the host application. Whenthe Integration Module receives this data stream, it uses the FCL toformat and send the document.
Because of the range of host-based applications, systemenvironments, and document formats, specific instructions foraccessing and manipulating document data is beyond the scope ofthis guide.
About 100 FCL commands are available. For a detailed list seeAppendix B, FCL Commands.
-
7/31/2019 RightFax Integration Module Guide
48/226
-
7/31/2019 RightFax Integration Module Guide
49/226
Chapter 9 Creating FCL Documents 49
Understanding the Format of FCL Commands
The most important requirement for forming FCL commands is thatthey begin with two left braces ({{) and end with two right braces(}}). Unique delimiters can be defined for serial capture input. Forinstructions, see Setting Up a Serial Capture on page 37.
All FCL commands have the same format, and most of them caninclude arguments and variables:
{{command argument variable}}
Use one or more spaces to separate commands from arguments
and variables.
You can list several FCL commands in a sequence. Do not typespaces between the commands in a line:
{{begin}}{{fax 503-555-1234}}{{onsuccess fax 555-6892}}
You can place FCL commands anywhere in a document, butCaptaris recommends that you place them at the end unlessotherwise specified for the FCL command (see Appendix B, FCL
Commands).
Example FCL Documents
The following figure (Figure 9.1: Other Files Can Be Added to theDocument) and the numbered paragraphs following it illustratehow other documentssuch as cover sheets, background forms,and attachmentscan be included in a document with the use of
FCL commands.
Figure 9.1 Other Files Can Be Added to the Document
January Invoices
Invoice #1: AAAAAAA
Invoice #2: BBBBBBB
Invoice #3: CCCCCCC
Invoice #4: DDDDDDD
Invoice #5: EEEEEEE
Smith Hardware Co.Purchase Order
{{begin}}
{{cover sales.cov}}
{{fax 503-555-1234}}
{{attach januaryinvoices.doc}}
{{include februaryorders.inc}}
{{form purchorder.tif}}
Item SKU Qty CostRail 16 1 294.99Clip 24 10 190.08Pin 09 30 104.32
{{end}}
{{lm 0.5}}
{{moveto 0.5 1.0}}
Fax Transmission
from Smith
Hardware {{end}}
{{tm 4.0}}
{{lm 0.5}}
{{font ariel10 10 14}}
January Invoices
Invoice #1: AAAAAAA
Invoice #2: BBBBBBB
Invoice #3: CCCCCCC
Invoice #4: DDDDDDD
Invoice #5: EEEEEEE
Smith Hardware Co.Purchase Order
Item SKU Qty CostRail 16 1 294.99Clip 24 10 190.08Pin 09 30 104.32
Fax Transmission fromSmith Hardware
1
2
34
5
6
7
-
7/31/2019 RightFax Integration Module Guide
50/226
-
7/31/2019 RightFax Integration Module Guide
51/226
Chapter 9 Creating FCL Documents 51
3. These four commands format the document. {{Tm}} specifies atop margin of 1.25 inches. {{Lm}} specifies a left margin of 0.25
inches. {{Font}} specifies a font of Times New Roman, 12-point.{{Orient}} specifies that the document will be in landscapeorientation.
4. These three commands will populate the variables in anotification message that will notify the sender when thedocument is sent.
5. The {{onerror}} command specifies that the Integration Moduletake a particular action if a document fails to send properly. If an
error occurs in transmission, the document will be faxed to503-555-4592, which is a fax machine in the senders office.
6. The {{notifyhost}} command specifies that the sender willreceive a notification message when the document is sent.
Figure 9.3 Finished Invoice from NW Distributors to Portland Trading Co.
Anne PaigePortland Trading Co.11990 S.W. Capitol Hill RoadPortland, OR 97034
Portland Trading Co.11990 S.W. Capitol Hill RoadPortland, OR 97034(503) 555-9182
18277 8/8/01
50 lb 13654 Beef Jerky $ 8.50/lb $ 425.00
Qty Item AmountPriceDescription
Date ordered
Your order # Our order #
Date shipped
Sales person
Terms
Invoice # Date
Ship toSold to
NW
Distributors
John Bardolph
2% 10 days
13579
8/7/01
55222
8/4/01
$1,025.00 $75.00 $75.00 $1,175.00
Subtotal Sales tax Shipping Total
50 lb 13655 Smoked Salmon $ 12.00/lb $ 600.00
Page 1 of 4ptc6mos.xls
Data DataDataData DataData Data Data
RightFax 9.3 Integration Module Guide 52
-
7/31/2019 RightFax Integration Module Guide
52/226
-
7/31/2019 RightFax Integration Module Guide
53/226
Chapter 10 Setting Defaults for FCL Documents 53
Chapter 10
Setting Defaults for FCL Documents
To set most default values, you must make configurations to theIntegration Module Configuration program. In many cases, you canoverride the default in specific documents by including FCLcommands in the document data from the host application.
You can also set defaults for things like margins and fonts byinserting relevant FCL commands in a global include file. Forinformation on include files, see Chapter 14, Including the SameFiles and Commands in Many Documents.
Opening the Integration Module Configuration
Program
1. On the Start menu, select Programs > RightFax > EnterpriseFax Manager. The Enterprise Fax Manager window appears.
2. In the Fax Servers list, click the name of the server on which the
Integration Module is running.3. In the Service Name list, double-clickRightFax Integration
Module. The Integration Module Configuration windowappears.
Setting General Defaults1. In the left pane, clickGeneral. The General settings appear in
the right pane.
Figure 10.1 General settings
RightFax 9.3 Integration Module Guide 54
2. In the Company name box, enter a name to appear on thecover sheet of each sent fax. Usually this is the company name.
7. In the Event Log Level box, select the level of reporting to theWindows Event Log.
-
7/31/2019 RightFax Integration Module Guide
54/226
This setting can be overridden for a document with the {{rti}}command. For more information on this command, seeAppendix B, FCL Commands.
3. In the CSID box, enter a voice telephone number to appear onthe cover sheet of each sent fax. This is usually the telephonenumber for the company.
This setting can be overridden for a document with the {{csi}}command. For more information on this command, seeAppendix B, FCL Commands.
4. In the Default cover page box, enter the file name for a cover
sheet. Enter none for no cover sheet. For more information oncover sheets, see Chapter 15, Creating and Attaching CoverSheets.
5. In the Default Printer box, specify the printer to use for printingdocuments when an error is encountered or when printing adocument with the {{type print}} FCL command. Enter a printerthat has been defined in Enterprise Fax Manager.
This setting can be overridden for a document with the
{{printer}} command. For more information on this command,see Appendix B, FCL Commands.
6. Under Transmission quality, specify the image quality forfaxes.
Fine is 200 x 200 dots-per-inch.
Standard is 200 x 100 dots-per-inch.
This setting can be overridden for a document with the
{{quality}} command. For more information on this command,see Chapter 19, Setting Page Orientation and Image Quality.
None records no errors
Terse records critical errors only
Normal records the most significant events only and is thecorrect setting for normal use
Verbose records all significant events and is the most usefulfor tracking and resolving problems
Caution If this value is set to verbose indefinitely, the event log canbecome full. This can prevent new events from being logged.
8. In the Server name box, enter the name of the RightFax server.
9. In the Protocol list, select the communication protocol for theRightFax server.
-
7/31/2019 RightFax Integration Module Guide
55/226
Chapter 10 Setting Defaults for FCL Documents 55
Setting Defaults for FCL Processing
1. In the left pane, clickFCL Processes. The FCL Processorsettings appear in. the right pane.
Figure 10.2 The FCL Processor Settings
2. In the Units of measurebox, specify the unit of measurementthat will be used for indentation, page length, and for FCL
commands. With FCL commands, his setting is used to specifythe x- and y-coordinates for placing data on a page. This settingcan be overridden for a document with the {{units}} command.For more information on this command, see Appendix B, FCLCommands.
3. In the Indentationbox, specify the indentation of the fax imageon the left side of the page. The unit of measurement isdetermined by the Units of measure setting.
4. In the Page length box, enter the maximum page length for afax. For example, this setting prevents a legal-size page (11
inches wide x 14 inches long) from being cut off at 11 inches.The unit of measurement is determined by the Units ofmeasure setting.
5. In the Maximum attached pages box, specify the maximumnumber of attached pages for each fax. The Integration Modulecan attach up to 1024 pages to a fax.
6. A document attached to a fax that is 300 dots-per-inch will befaxed as two pages. To reduce the image size and send the
image as one page, select the check box Shrink 300 DPI filesto fit page.
7. In the Minimum page length box, specify the minimum pagelength for faxes. This setting ensures that a fax with very littledata is printed on a page that is long enough, so that it does notget lost or discarded by the recipient. The unit of measurementis determined by the Units of measure setting.
8. White space at the end of a fax is sent as data to the receiving
fax machine. You can speed up the transmission of the fax if thisdata is not sent. To remove this data from the fax, select theTrim trailing white space check box.
RightFax 9.3 Integration Module Guide 56
-
7/31/2019 RightFax Integration Module Guide
56/226
-
7/31/2019 RightFax Integration Module Guide
57/226
57
Chapter 11
Creating Filter Templates
Understanding Filter TemplatesThe RightFax Integration Module processes documents from thehost application by interpreting facsimile command language (FCL)and performing functions based on the commands. The IntegrationModule can do this in one of two ways: native mode or filter mode.
With native mode, you include FCL commands in the documentdata that is sent from the host application. This may requirecustom programming to add FCL to documents or to templatesin the host application or to insert FCL in the data stream.
With filter mode, you create filter templates that add FCL to thedocument data after it is sent to the Integration Module forprocessing. A filter template is a map of the document data thatcontains the FCL that is required to create and send thedocument.
This chapter discusses the creation of filter templates that support
filter mode.
Filter templates provide the following features: Data mapping provides sending information to the RightFax
Integration Module, such as the recipient name, fax number, ande-mail address. It also provides information from the sourcedocument for the fax cover sheet.
Data mapping provides information from the source document fornotification messages, such as the sender's name and e-mailaddress. Combined with the RightFax Integration Module,
notifications provide the status of the sent document to thesender, to a system administrator, or another recipient.
Background forms can provide visual interest to the filtertemplate, with the features of a pre-printed form such as apurchase order or stationery. Background forms are included bylinking an image file to a filter template.
Graphics can be added. Graphics are included by linking animage file to a filter template.
Data tables can be linked to the form so that information can beadded to a document before it is sent. This is useful for addingdata that is not sent from the host application with the document.
User-defined data fields and facsimile command language (FCL)can further extend the filter template.
RightFax 9.3 Integration Module Guide 58
In the following example, the mapped data elements are thecompany name and fax number.
1 An invoice document is sent from host application that does not
4. The document data now contains FCL. The {{company}} and{{fax}} FCL commands are created by the mapped fields in thefilter template. The document can now be processed and sent
-
7/31/2019 RightFax Integration Module Guide
58/226
1. An invoice document is sent from host application that does notinclude FCL.
2. On the RightFax server, Filter.exe receives the document dataand it retrieves a filter template. The filter template identifiesdata in the document that is needed for addressing and sendingthe document. In this filter template, the company name and faxnumber are mapped.
3. The filter software extracts the content of the company nameand fax number fields and creates the {{company}} and {{fax}}FCL commands.
p pby the Integration Module.
Figure 11.1 Filter Mode Document Flow
Skyline Office Supply1418 Melody DriveIdaho Falls, ID 83402
Jones and Smith Law Firm6060 Sanford DriveSan Jose, CA 97219Fax: (206) 555-4322
Invoice No. 16
Item SKU Qty CostPen 16 1 294.99Clip 24 10 190.08
Ink 09 30 104.32
Invoice Date: 01/03/2002Please remit payment by: 02/03/2002
Host
Company
Fax
Integration Moduleon RightFax server
Filter on RightFaxserver
Skyline Office Supply1418 Melody DriveIdaho Falls, ID 83402
Jones and Smith Law Firm6060 Sanford DriveSan Jose, CA 97219Fax: (206) 555-4322
Invoice No. 16
Item SKU Qty CostPen 16 1 294.99Clip 24 10 190.08Ink 09 30 104.32
Invoice Date: 01/03/2001Please remit payment by: 02/03/2001
{{begin}}Skyline Office Supply1418 Melody DriveIdaho Falls, ID 83402
Jones and Smith Law Firm6060 Sanford DriveSan Jose, CA 97219Fax: (206) 555-4322
Invoice No. 16
Item SKU Qty Cost
Pen 16 1 294.99Clip 24 10 190.08Ink 09 30 104.32
Invoice Date: 01/03/2002Please remit payment by: 02/03/2002
{{fax 206-555-4322}}{{company Jones & Smith Law Firm}}{{end}}
1
2 3
4
-
7/31/2019 RightFax Integration Module Guide
59/226
RightFax 9.3 Integration Module Guide 60
Step 5: Preview the filter (page 66)
The instructions in this chapter refer to sample files that areinstalled with the Integration Module The files are described in the
Step 1: Overlay the sample data on a MapText document
1. On the RightFax server in Windows Explorer, navigate toRightFax\Production\Bin and run MapText.exe. The MapText
-
7/31/2019 RightFax Integration Module Guide
60/226
installed with the Integration Module. The files are described in thefollowing table.
RightFax\Production\Bin and run MapText.exe. The MapTextwindow opens with a blank document called MapText1.
Figure 11.2 The MapText Window
2. On the Toolsmenu, clickOverlay Data File.
Table 11a Sample Files Installed with Filter for Production
Sample file Location Description
SampleData.txt RightFax\Production\Include
An example of a documentthat a host applicationmight create. It isformatted as a single printstream capture thatcontains two documents:
a three-page purchaseorder and a one-pagepurchase order.
SampleForm.tif RightFax\Production\Forms
An example of a form ontowhich you might print apurchase order. MapTextwill merge SampleData.txtwith SampleForm.tif to
create an image of thedocument printed on apre-printed form.
3 S l t l d t S l D t t t d th li k Fi 11 3 H t D t M d ith Bl k M T t D t
-
7/31/2019 RightFax Integration Module Guide
61/226
Chapter 11 Creating Filter Templates 61
3. Select your sample document or SampleData.txt, and then clickOpen. The following example illustrates that SampleData.txt is
placed in the blank MapText document. This image shows thedata that forms Metropolitan Inc. purchase orders. In this case,the purchase order will go to Universal Suppliers.
Figure 11.3 Host Data Merged with a Blank MapText Document
The horizontal and vertical rows of numbers at the leftand top borders are part of the sample fileSampleData.txt. They are provided to illustrate thatMapText filter templates are grids on which you createfields at x- and y-coordinates.
This is the recipient of the purchase order.Universal Suppliers will bill to the firstaddress and ship to the second address.
This is the ship to addressand contact information.
This is the bill to addressand contact information.
RightFax 9.3 Integration Module Guide 62
Step 2: Map the document data to MapText fields
In this step, you identify pieces of data in the document thatRightFax will use to process and send the documents. You will:
1. Define the field in the document template that will contain thename of the recipient company. Drag the mouse to selectUniversal Suppliers. The New Field dialog box appears.
-
7/31/2019 RightFax Integration Module Guide
62/226
Locate the data on the page (create a field for the data).
Identify the type of data in the field. Map facsimile command language (FCL) to the field.
You can map host data to 25 FCL codes. The following steps mapthree host data elements (company name, fax number, andpurchase order number) to three fields (company, fax, andcomment).
For a detailed description of each type of field, see Understandingthe Field Types on page 67.
In the following figure, the name of the company that will receivethe document (Universal Suppliers) is selected. It will be
defined as a field. Note that the field is longer than the text itcontains. This provides space for long company names thatmight appear in future documents.
Figure 11.4 Defining the Company Name as a Field
2 In the New Field dialog box in the Description box enter a 5 Define the field in the document template that will contain the
-
7/31/2019 RightFax Integration Module Guide
63/226
Chapter 11 Creating Filter Templates 63
2. In the New Field dialog box, in the Description box, enter adescription for the field, such as Company Name.
Figure 11.5 Assigning Attributes to the Field
3. In the Field Type list, clickCompany.
4. ClickOK.
5. Define the field in the document template that will contain thepurchase order number. Drag the mouse to select the purchase
order number. The New Field dialog box appears.In the following figure, the purchase order number (PO 13579)is selected.
Figure 11.6 Defining the Purchase Order Number as a Field
6. In the Description box, enter a description for the field, such asPO Number.
Enter a descriptive name forthe field youre creating.
(13,12) describes the x-and y-coordinates for theupper-left corner of the
field.
Select a field type.
RightFax 9.3 Integration Module Guide 64
7. In the Field Type list, clickComment.
One attribute of the Comment field type is that it starts a newdocument when the data in the field changes. In this case, a
9. Define the field in the document template that will contain thefax number of the company that will receive this document. Dragthe mouse to select the fax number. The New Field dialog boxappears
-
7/31/2019 RightFax Integration Module Guide
64/226
new purchase order document will be created with each newpurchase order number that is received. For detailed information
on the Comment field type, see Understanding the Field Typeson page 67.
Figure 11.7 Mapping the Purchase Order Field
8. ClickOK.
appears.
In the following figure, the fax number (520-555-3282) is
selected.
Figure 11.8 Defining the Recipient Fax Number as a Field
10.In the New Field dialog box, in the Description box, enter adescription for the field, such as Fax Number.
11.In the Field Type list, clickFax.
Figure 11.9 Mapping the Fax Field Type
-
7/31/2019 RightFax Integration Module Guide
65/226
RightFax 9.3 Integration Module Guide 66
To insert FCL
1. On the File menu, clickProperties, or click the Propertiesbutton on the toolbar. The Properties dialog box appears.
7. On the File menu, clickSave, or click the Save icon on thetoolbar. The following example illustrates how FCL appears inthe Properties dialog box after it is defined.
-
7/31/2019 RightFax Integration Module Guide
66/226
g pp
2. ClickNew. The Custom FCL dialog box appears.
Figure 11.11 The Custom FCL Dialog Box
3. Enter the FCL using the proper syntax and delimiters.
4. To specify that the commands will be inserted at the beginningof each document, select the Beginning of page check box.
5. Select one of the following options:
To specify that the FCL should apply to every page of thedocument, clickEvery page.
To specify that the FCL should apply to only the first page ofthe document, clickFirst page.
To specify that the FCL should apply to only the first page ofthe document, clickLast page.
To specify the page number for the FCL, clickPage #, andenter the page number.
6. ClickOK. The MapText window appears.
Figure 11.12 Custom FCL Added to the Filter
Step 5: Preview the filter
To preview the filter, use the Generate Image function. GenerateImage displays the background form merged with the sampledocument data and therefore helps you fine-tune the alignment. Itdoes not test that the RightFax server can receive data from thehost application and process the data correctly with the filter.
To preview the filter
On the Toolsmenu, clickGenerate Image, or click the Generate
Imagebutton on the toolbar. MapText generates the image, andthe default TIFF image viewer opens with the finished document.
Examine all the pages of the finished document. If you are using abackground form, verify that it aligns with the document data.
01 indicates that this is thefirst line of FCL code in this filtertemplate, and so on.
BE indicates that this line ofFCL will apply to the beginningof every page of the documentthat uses this filter template.
BF indicates that this line ofFCL will apply to the beginningof the first page of the documentthat uses this filter template.
In the following example, the form is not aligned with the document Understanding the Field Types
-
7/31/2019 RightFax Integration Module Guide
67/226
Chapter 11 Creating Filter Templates 67
data. For help troubleshooting filter templates, seeTroubleshooting on page 71.
Figure 11.13 Your First Attempt Might Yield Alignment Errors
g yp
The following table lists the field types and their uses.
Table 11b MapText Field Types
Field
type Description
Map the field type to
this data element
Abort Cancels the creation of adocument when thespecified text appears inthe field.
Corresponds to the{{abort}} FCL code.
This field type iscommonly used fortesting purposes.
ExampleFor testing, you mightcreate documents in alarge batch that containthe word test in theAbort field. Thedocuments would not besent.
Comment Starts a new document
when text in this fieldchanges.
Map this field to data that
is unique in eachdocument.
ExampleThe purchase ordernumber is unique in eachdocument. When thepurchase order numberchanges, a newdocument is started.
See also the Page fieldtype. The Page field typeoverrides the Commentfield type.
RightFax 9.3 Integration Module Guide 68
C S ifi th i i t M thi fi ld t th
Table 11b MapText Field Types (Continued)
Field
type Description
Map the field type to
this data element
E il S ifi th il Th il dd f th
Table 11b MapText Field Types (Continued)
Field
type Description
Map the field type to
this data element
-
7/31/2019 RightFax Integration Module Guide
68/226
Company Specifies the recipientcompany name.
Corresponds to the{{company}} FCL code.
Map this field to the nameof the company that
should receive thedocument.
This information may beplaced on the cover sheetor in a notificationmessage.
Contact Specif ies the recipientname.
Corresponds to the{{contact}} FCL code.
Map this field to the nameof the person who should
receive the document.This information may beplaced on the cover sheetor in a notificationmessage.
Cover Specifies the cover sheet.
Corresponds to the{{cover}} FCL code.
Map this field to the coversheet file name.
The cover sheet file must
be stored in the directoryRightFax\Production\Covers. If the file is not foundin the directory when thedocument is created, thedefault cover sheet isused.
Email Specifies the e-mailaddress to send.
Notifications about thesent document to the hostapplication.
The document via e-mailusing the InternetLinkModule.
Corresponds to the{{email}} FCL code.
For more information, seethe InternetLink ModuleGuide.
The e-mail address of theperson or company who
is sending this document(used to send anotification to the e-mailaddress).
The e-mail address of theperson or company towhich you are sendingthis document (requires
InternetLink).
Fax Specifies the fax number.
Corresponds to the {{fax}}FCL code.
Map this field to the faxnumber where thedocument should be sent.
Table 11b MapText Field Types (Continued) Table 11b MapText Field Types (Continued)
-
7/31/2019 RightFax Integration Module Guide
69/226
Chapter 11 Creating Filter Templates 69
Graphic File name of a graphic. Map this field to thegraphic file name. The filename must match the textin the mapped field. Forexample, Mark Jones'signature file must benamed MarkJones.tif.
The graphic file formatmust be .tif. The file mustbe stored in the directoryRightFax\Production\Forms. If the file is not foundin the directory when thedocument is created,then the image will notappear in the document.
ExampleAn image such as asignature or a companylogo can be inserted.
Include Specifies the fi le name ofan include file.
Corresponds to the{{include}} FCL code.
An include file cancontain commands anddata that are common tomany documents.
Map this field to theinclude file name.
The file must be stored inthe directory
RightFax\Production\Include. If the file is not foundin the directory when thedocument is created,then an error will occurand the document will notbe processed.
Field
type Description
Map the field type to
this data elementLookup
Lookup2 -Lookup9
Specifies the file name of alookup table.
Corresponds to the{{lookup}} FCL code.
A lookup table can provideinformation that is notcontained in the document
that is sent from the hostapplication, such as therecipient company nameand fax number.
The text in the mappedfield of the document willbe compared to the firstcolumn in the specifiedlookup table. When amatch is found, theassociated data in therow will be used to send
the document, includedon the cover sheet, orincluded in a notificationmessage.
When you create aLookup field, you cancreate or edit a lookupfile. To do this, clickEdit
lookup file.The lookup table must bestored in theRightFax\Production\Include directory.
ExampleThe mapped field maycontain a vendor ID. Inthe lookup table, vendor
ID data includes thecompany name and faxnumber. The companyname will be printed onthe cover sheet, and thefax number will be usedto send the document.
Field
type Description
Map the field type to
this data element
RightFax 9.3 Integration Module Guide 70
Owner Specifies the sender's Map this field to the
Table 11b MapText Field Types (Continued)
Field
type Description
Map the field type to
this data element
TemplateI Specifies the filter template Map this field to text that
Table 11b MapText Field Types (Continued)
Field
type Description
Map the field type to
this data element
-
7/31/2019 RightFax Integration Module Guide
70/226
Owner Specifies the sender sname.
Corresponds to the{{owner}} FCL code.
Map this field to thesender's name.
The name can appear onthe cover sheet or innotification messages.
Page Starts a new documentwhen the number 1appears in this field
Map this field to the pagenumber.
See also the Commentfield type. The Page fieldtype overrides the
Comment field type.
SendFax Use this field to print adocument rather than fax itor send it through anothermethod.
The document will beprinted if N, a space, or nullcharacters are found in this
field.
Map this field to the faxnumber.
This field type is usedwhen not all recipientshave a fax number orother address fortransmission. Such
documents would beprinted so that they couldbe mailed.
TemplateID
Specifies the filter templateto use to format the
document.
Map this field to text thatdescribes the document
or indicates thedocument type. Forexample, the wordsPurchase Order mayindicate that thePurchase Order templatebe used to format thedocument.
When text in the mappedfield matches the textspecified, the specifiedtemplate will be used toformat the document.
User1
User 2
User3
Specifies user-definedinformation.
Corresponds to theuser-defined {{user1}},
{{user2}}, and {{user3}}FCL commands.
Map this field to text thatyou want to appear onthe cover sheet or in anotification message.
Voice Specifies the telephonenumber for the recipient.
Map this field to thephone number of theperson who will bereceiving the document.
The number can appearon the cover sheet or in
notification messages.
-
7/31/2019 RightFax Integration Module Guide
71/226
RightFax 9.3 Integration Module Guide 72
Documents are not addressed or are not sent correctly
Documents are incompletely addressed, the destination faxnumber is incomplete, or other information appears truncated in thedocument.
The command line for the input channel must specify the filtertemplate. The following table describes the command line optionsto use.
Table 11d Add Input Device Settings for a Named Pipe
-
7/31/2019 RightFax Integration Module Guide
72/226
Possible cause
The fields for the data elements are not long enough.
Solution
Re-size the fields.
Creating an Input Channel for Filter DocumentsYou can create up to 70 unique input channels for the documentsthat must be processed with filter templates. One input channelcan process documents for one filter template. The most commoninput channels are:
Named pipe capture (page 35)
Directory scanning (page 36)
Serial capture (page 37) TCP/IP port capture (page 39)
Example nplisten.exe -c filter -i invoice.mtd -f $$| makedoc -p hplpr
In this example, Nplisten.exe will run the filter command againstthe data file (represented by $$) received on the named pipe. Filterwill add FCL commands as designated by the invoice.mtd templateand pipe the result to makedoc for processing.
Table 11d Add Input Device Settings for a Named Pipe
Command lineoption Description
-c filter |makedoc
The option -c specifies one or more commandsto execute on files received via the channel.
Filter.exe extracts the document data usingthe filter template.
Makedoc.exe begins the process ofconverting document data from the host
application into a fax.The pipe symbol (|) separates the twocommands in the command line. Thecommands must be enclosed in quotationmarks.
-i filename.mtd The option -i specifies that the specifiedMapText document (filename.mtd) should beincluded with the incoming data.
-f Identifies filename.mtd as a file.
Chapter 12
-
7/31/2019 RightFax Integration Module Guide
73/226
73
Specifying the Destination of the Document
A document can be sent to a fax number, an e-mail address, anSMS number, a printer, or a file. Use the following FCL commandsto specify the destination for documents.
Sending One Document to a Single Fax Number
To address a document to a single recipient, add the {{fax}}command to the FCL. The following example shows an FCLdocument that is addressed to 503-555-4489.
{{begin}}{{fax 503-555-4489}}Body of the document to be sent.{{end}}
Table 12a Destination FCL Commands
Code Description
{{fax}} Sends documents to a fax number.
If you have the InternetLink Module, then
you can use an e-mail address with the{{fax}} command and send documentsvia e-mail. For more information, see theRightFax InternetLink Module Guide.
The {{altfax}} command provides analternative fax number that is used if thenumber provided with the {{fax}}command fails.
{{type certified}} Sends the document as a certified e-mailmessage. This option requires theRightFax SecureDocs Module.
{{type email}} Sends the document as the body of ane-mail message. This option requires theRightFax InternetLink Module.
{{type file}}{{file}}{{list}}
Sends the documents as files to aspecified folder.
{{type mime}} Sends the document as an attachment toan e-mail message. This option requiresthe RightFax InternetLink Module.
{{type print}} Sends documents to a specified printer.
{{type SMS}}{{smsmsg MessageText}}{{sms PhoneNum}}
Specifies that a message will be sent toan SMS-compatible device.
Table 12a Destination FCL Commands (Continued)Code Description
-
7/31/2019 RightFax Integration Module Guide
74/226
Figure 12.1: Broadcast Documents with an {{Include}}Command shows the same broadcast document with an
In Figure 12.1: Broadcast Documents with an {{Include}}Command, the data from WestCoastCustomers.inc would replace
-
7/31/2019 RightFax Integration Module Guide
75/226
Chapter 12 Specifying the Destination of the Document 75
{{include}} command that inserts multiple addresses, instead of theaddresses themselves.
Figure 12.1 Broadcast Documents with an {{Include}} Command
the {{include}} command in the original data. Thus, you need toinsert only one command to address a document to multiplerecipients. By having multiple broadcast include files stored on theIntegration Module, you can easily broadcast a document towhatever group of numbers you choose.
Note Include files can do much more than store broadcast data. Forinformation on different uses, how to create them, and where to savethem, see Chapter 14, Including the Same Files and Commands in ManyDocuments. The following section deals with broadcast lists, just one
form of include files.
Creating Lists of Recipients for a Broadcast
Use the following guidelines to create a list of recipients for abroadcast transmission.
Place the {{fax}} command first in each command on each line in an
FCL document.Correct {{fax 503-555-3829}}{{company Acura of Salem}}
Incorrect {{company Acura of Salem}}{{fax 503-555-3829}}
Do not insert any characters, such as spaces, between FCLcommands that are listed in a line.
Correct {{fax 503-555-3829}}{{company Acura of Salem}}
Incorrect {{fax 503-555-3829}} {{company Acura of Salem}}
{{begin}}
Dear customer,
Our office will be closed on
Friday, March 25 for inventory. We
will be open again as usual on
Monday.
Thanks,
International Finance Corporation{{include WestCoastCustomers.inc}}
{{end}}{{fax 555-3374}}
{{company Salem Publishing Co.}}
{{contact Juan Garcia}}
{{fax 206-555-6530}}
{{company Oswego Boats}}
{{contact Gabriella Navarro}}
{{fax 503-555-0905}}
{{company West Coast Shippers}}
{{contact Andy Wells}}
This is the file namedWestCoastCustomers.inc
{{begin}}
Dear customer,
Our office will be closed on
Friday, March 25 for inventory. We
will be open again as usual on
Monday.
Thanks,
International Finance Corporation
{{fax 555-3374}}
{{company Salem Publishing Co.}}
{{contact Juan Garcia}}
{{fax 206-555-6530}}
{{company Oswego Boats}}
{{contact Gabriella Navarro}}
{{fax 503-555-0905}}
{{company West Coast Shippers}}
{{contact Andy Wells}}
{{end}}
RightFax 9.3 Integration Module Guide 76
To create broadcast lists from a mainf