rightfax integration module guide

7/31/2019 RightFax Integration Module Guide

1/226

Version 9.3

Integration Module Guide

www.ingeniumsw.com770-936-0600


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


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


4/226


5/226


6/226

RightFax 9.3 Integration Module Guide vi


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


8/226


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


10/226

RightFax 9.3 Integration Module Guide 10


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.


12/226


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


14/226



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


16/226


4. Configure the Integration Module software, as described later inthis 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.



18/226


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


19/226



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.


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.



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.


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



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


25/226


3. Enter a descriptive name in the Queue Manager box, and clickNext. The Create Queue Manager (Step 2) dialog boxappears.


4. Accept all defaults by clicking Next. The Create QueueManager (Step 3) dialog box appears.


5. Accept all defaults by clicking Next. The Create QueueManager (Step 4) dialog box appears.




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.


27/226


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.



28/226


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



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.


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.



32/226


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



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.


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.



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



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.


37/226


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



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



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)


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


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



39/226


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



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



4 Complete the entries in the dialog box as described in the TCP/IP port To configure the input you specify the channel name


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



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.


41/226


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



42/226


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.


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.


4. Start the Integration Module service in Enterprise Fax Manager. To test the connection


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.


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.


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.


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



46/226


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.


48/226


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


50/226


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



52/226


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


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.


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.


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.



56/226


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.


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


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


Invoice No. 16

Item SKU Qty CostPen 16 1 294.99Clip 24 10 190.08Ink 09 30 104.32


{{begin}}Skyline Office Supply1418 Melody DriveIdaho Falls, ID 83402


Invoice No. 16

Item SKU Qty Cost

Pen 16 1 294.99Clip 24 10 190.08Ink 09 30 104.32


{{fax 206-555-4322}}{{company Jones & Smith Law Firm}}{{end}}

1

2 3

4


59/226


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


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


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.


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.


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


63/226


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.


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


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


65/226


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.


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


67/226


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.


C S ifi th i i t M thi fi ld t th

Table 11b MapText Field Types (Continued)

Field

type Description


this data element

E il S ifi th il Th il dd f th


Field

type Description


this data element


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)


69/226


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


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


this data element


Owner Specifies the sender's Map this field to the


Field

type Description


this data element

TemplateI Specifies the filter template Map this field to text that


Field

type Description


this data element


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.


71/226


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


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


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


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


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}}


To create broadcast lists from a mainf