OpenText RightFax 10.5 Integration Module Guide

OpenText RightFax 10.5 Integration Module Guide
OpenText RightFax 10.5
Integration Module Guide
OpenText RightFax 10.5 Integration Module Guide
Edition
Integration Module Version 10. This document was last updated May 17, 2012
Trademarks
OpenText is a registered trademark of OpenText Corporation. All other company names, brand names, and product names are the property and/or trademarks of their respective companies.
Copyright Notice
©2012 OpenText, Inc. All rights reserved.
OpenText Corporation
275 Frank Tompa Drive
Waterloo, Ontario, Canada
N2L 0A1
(519) 888-7111
http://www.opentext.com
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. Includes Adobe® PDF Library technology. Adobe, Acrobat and the Acrobat logo are trademarks
of Adobe Systems Incorporated. Portions Copyright © TMS, Inc. 1994-2001. All rights reserved.
ii
Contents
Chapter 1
Introduction.............................................................................. 5
Features of the Integration Module ...............................................6
Understanding Document Recognition .......................................7
Understanding Document Distribution.........................................8
Chapter 5
Reusing FCL Commands Across Many Documents ....45
Understanding Include Files.........................................................45
Creating Include Files ....................................................................47
Linking Include Files .......................................................................47
Chapter 2
Connecting the OpenText
RightFax Integration Module .............................................. 9
Guidelines for Common Connection Methods ....................... 10
Using the Integration Setup Wizard .......................................... 12
Chapter 6
Chapter 3
Configuring the RightFax Integration Module
to Receive Data..................................................................... 15
Creating an Input Device.............................................................. 15
Setting Up a Named Pipe Capture............................................ 17
Setting Up Directory Scanning ................................................... 19
Setting Up a Serial Capture ........................................................ 20
Setting Up a TCP/IP Port Capture ............................................ 23
Setting Up an IBM WebSphere MQ Connection .................. 24
Creating and Attaching Cover Sheets
and Other Files......................................................................49
Understanding Cover Sheets .................................................... 49
Creating Cover Sheet Templates .............................................. 50
Attaching a Cover Sheet to a Document with FCL ............... 54
RightFax Cover Sheet Logic .......................................................55
Example Cover Sheet and Document ...................................... 56
Attaching Other Types of Files ...................................................57
Chapter 7
Defining Fax Page Appearance.........................................59
Drawing Shapes ............................................................................ 59
Embedding Signatures with FCL ...............................................63
Embedding Graphics with FCL.................................................. 64
Setting Margins ...............................................................................65
Setting Tabs with FCL ................................................................. 66
Selecting and Configuring Fonts ................................................67
Setting Page Orientation ............................................................. 69
Setting Fax Image Quality.............................................................70
Chapter 4
Creating Filter Templates ................................................... 27
Understanding Filter Templates .................................................. 27
Preparing to Create Filter Templates......................................... 29
Creating a New Filter Template .................................................. 29
Understanding the Field Types ................................................... 38
Troubleshooting .............................................................................. 41
Creating an Input Channel for Filter Documents .................... 42
iii
OpenText RightFax 10.5 Integration Module Guide
Chapter 8
Document Transmission and Notifications ................... 71
Scheduling Document Transmission..........................................71
Creating Notification Messages with FCL................................72
Creating Notification Templates ..................................................73
Creating Notification Channels ...................................................79
Including the {{Notifyhost}} Command in Documents .......... 89
Testing That the Host Application
Is Correctly Receiving Notifications ........................................91
Troubleshooting Notification Messages ....................................92
Setting Up Actions on Document Transmission..................... 94
Chapter 9
Programming for the RightFax XML Interface............. 99
Introduction to the RightFax XML Interface............................. 99
Installing the XML Interface......................................................... 99
XML Interface Functions ............................................................ 100
Transports...................................................................................... 102
Understanding Body and Cover Text ...................................... 105
The Schemas ................................................................................106
Sample Documents Based on the Schemas ........................ 117
Chapter 10
Creating FCL Documents ................................................. 125
Understanding the Format of FCL Commands .................... 125
Setting Defaults for FCL Documents...................................... 126
Sending Basic FCL Jobs ........................................................... 128
Creating and Linking Background Forms .............................. 132
Example FCL Documents .......................................................... 133
Chapter 11
Programming for the RightFax API for Java ............... 137
Installing the API for Java ........................................................... 137
Sending Outbound Documents ..............................................138
Querying Documents.................................................................. 142
Performing Actions on Documents.......................................... 143
Using Debug Mode ..................................................................... 145
Error and Status Codes for XMLand Java-Based Documents .................................................. 146
Chapter 12
Creating FCL Documents
with InternetLink Commands ..........................................149
System Requirements................................................................. 149
Activating the InternetLink Module .......................................... 149
Understanding the InternetLink FCL Commands ................ 150
Attaching Native Files to InternetLink Documents ............... 151
Sending Documents as E-mail if Faxes Fail........................... 153
Receiving Notification When a Fax Fails
and Is Sent as an E-mail ......................................................... 153
Chapter 13
OpenText RightFax Connector
for Oracle Purchasing 11i .................................................155
Activating the Oracle Purchasing 11i Connector ................ 155
How the Oracle Purchasing 11i Connector Works ............ 155
Editing the Default Templates ................................................... 156
Sending Documents by Email................................................... 161
Appendix A
RightFax Integration Module Programs1‘63
Appendix B
FCL Commands165
Index ...................................................................................................................197
iv
Chapter 1
Introduction
The OpenText RightFax Integration Module enables information
exchange by integrating with applications on mainframe, mid-range,
and local area network host systems. Together, OpenText RightFax
and the Integration Module will send any document created by
these applications via fax, e-mail, or over the Internet.
The Integration Module automates batch-oriented, repetitive
processes. It is designed to support applications that produce
output that traditionally is sent to a printer, printed on pre-printed
forms, folded, stuffed in envelopes, and then mailed or manually
faxed. These documents can include invoices, itineraries, purchase
orders, statements, order confirmations, loan applications, bills of
lading, change orders, financial reports, and material safety data
sheets.
The RightFax system can integrate with many applications. The
integration options are listed in the following table, along with the
RightFax documentation where you can find more information.
Table 1a Integration Options
Integration option
For more information
Integration Module
Chapters 2-9 in this guide, and the
services on the RightFax
server with Facsimile
Command Language (FCL)
RightFax Administrator’s Guide
RightFax XML Interface
Chapter 9, ”Programming for the
RightFax XML Interface” in this guide
RightFax API for Java
Chapter 11, ”Programming for the
RightFax API for Java” in this guide
RightFax C, C++, and
Visual Basic API
www.opentext.com
5
OpenText RightFax 10.5 Integration Module Guide
To meet the needs of small, medium, and large enterprises, the
Integration Module comes in two versions: the Integration Module
which includes full functionality, and the RightFax Business
Integration Module which includes a limited set of features for use
by smaller organizations.
Formatting documents
The Integration Module can:
z
z
z
Table 1b RightFax Integration Module types
Module
Features
Integration Module
z
70 input channels.
z Output methods of fax, certified email,
encrypted email, or print.
z Up to 70 filter templates.
z Up to 128 notification channels.
z Unlimited notification messages.
RightFax Business
z
Integration Module
z
Two input channels.
One output method (fax or print) per
input channel.
z Two fax channels for each fax output.
z One filter template per input channel.
z Unlimited notification messages.
The instructions in this guide apply to both versions of the module
unless otherwise specified.
z
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 company
logo.
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 OpenText
RightFax, the Integration Module can:
z
z
z
z
z
Delay the sending of a document by minutes or schedule the
date 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.
Features of the Integration Module
The Integration Module provides the following features.
Including data from a lookup table
A document from a host-based application may not include all the
information that is needed to send it, such as a fax number. You can
create a table of data where the Integration Module can “look up”
the needed data.
6
Sending notification messages
As a document is sent via OpenText RightFax, notification
messages can be generated and sent back to the sender of the
document, to a system administrator, to a central mailbox, to a file,
to a directory, or to a database on the host application. They can be
e-mailed or faxed, or files can be transferred.
Notification messages can be customized to contain descriptive
information about the sent document, such as:
z
z
z
Sender and recipient information, such as name, company name,
fax number, voice number, and e-mail address.
Document data such as the number of pages, transmission date
and time, image quality, and the duration of the fax call.
Status of the fax from the fax board.
Another form of notification is to fax or print documents that are
sent or documents that encounter errors in sending.
Understanding Document Recognition
The Integration Module can process ASCII text files, PostScript
files, and print control language (PCL) files that are generated by
an application.
ASCII text files
To process text files, you must do one of the following:
z
z
Include FCL commands in the document data. This may require
custom programming to add FCL to documents or to templates
in the host application or to insert FCL in the data stream. This is
known as native mode.
Create “filter templates” that add FCL to the document data after
it is sent to the Integration Module for processing. A filter
template is a map of the document data. It also contains the FCL
that is required to create and send the document. The FCL is
“laid over” the document according to the map. This is known as
filter mode.
PostScript files
To process and transmit a PostScript file, the host application must
send a “false” first page with the PostScript document. This page
must contain FCL codes in text form, which can be interpreted by
the Integration Module. The Integration Module interprets the FCL,
removes the false first page, formats the document, and transmits
it. This may require custom programming.
PCL files
To process and transmit a PCL file, the host application must send
a “false” first page with the PCL document. This page must contain
FCL codes in text form, which can be interpreted by the Integration
Module. The Integration Module interprets the FCL, removes the
false first page, formats the document, and transmits it. This may
require custom programming.
Chapter 1
Introduction
7
OpenText RightFax 10.5 Integration Module Guide
Understanding Document Distribution
The following figure shows how the Integration Module programs
receive, process, recognize, and distribute data from the host
application. This illustration shows the input channels that can be
configured to receive and recognize data. Up to 70 channels can
be configured.
Example The executable Bufdir.exe scans a folder for files sent by
the host application. Bufdir.exe retrieves the files and
sends them to Makedoc.exe, which begins the process
of converting them to documents and transmitting them.
Notify.exe creates a notification that is sent to an
application on the host system.
For a list of the programs that process and send documents, see
See ”RightFax Integration Module Programs” on page 163..
Figure 1.1 Flow of Documents in the Integration Module
“Figure 1.4: RightFax Integration Module Data Flow” shows how
FCL documents are processed after the Integration Module
receives the data stream from a host application. It explains the
programs, such as Makedoc.exe, that are shown briefly in “Figure
1.3: Flow of Documents in the RightFax Integration Module”.
Figure 1.2 Integration Module Data Flow
8
Chapter 2
Connecting the OpenText RightFax Integration Module
The Integration Module software (both standard and business
versions) is installed automatically during the OpenText RightFax
installation. To enable the functionality of these modules, they must
be licensed and then enabled on the server. For information on
enabling or adding new components to an OpenText RightFax,
installation, refer to the RightFax Administrator’s Guide.
Figure 2.1 Connections to Applications that Generate FCL or ASCII Data
Once the Integration Module is enabled, you must connect the
module to a host computer. This chapter explains the most
common methods for connecting a host computer to the
Integration Module computer for FCL-based documents.
The following figures illustrate the most common connection
methods. Some connections require third-party software that
OpenText does not provide or support.
9
OpenText RightFax 10.5 Integration Module Guide
Figure 2.2 Connections to Host Applications that Generate XML and Java Data
Guidelines for Common Connection Methods
The most common communication connection methods and basic
requirements are described in the following sections:
Line printer remote (LPR) connection on page 10
z 3270 emulation on page 10
z TCP/IP socket connection on page 11
z File Transfer Protocol (FTP) connection on page 11
z 5250 emulation on page 11
z IBM® WebSphere MQ® client v6 for Microsoft Windows on
page 11
After the communication methods are established, you must
configure the Integration Module to receive data via those
methods. See ”Configuring the RightFax Integration Module to
Receive Data” on page 15..
z
In general, the Integration Module is a printer connected to the host
computer. The host application will print to the Integration Module.
Line printer remote connection
To use a line printer remote connection, set up the host system to
print to the RightFax Integration Module as a remote Berkeley Style
Device (BSD) printer. In most cases, set the remote host name to
the host name of the Integration Module, and set the remote printer
name to “hostfax”. (By default, the Integration Module installs a
printer called “hostfax”. This is usually the default printer.)
The TCP/IP printing service or Print Services for Unix must be
installed and started on the OpenText RightFax. See ”Setting Up a
Named Pipe Capture” on page 17.
3270 emulation
You can set up a direct connection from the OpenText RightFax to
a mainframe host with 3270 emulation software. The protocol
standard TN3270 using TCP/IP over an Ethernet network adapter
10
is the recommended method. Systems Network Architecture
(SNA) can be used. Coaxial cable with a 3270 coaxial adapter can
be used, but it is not recommended.
Emulation software often has difficulty with a coaxial cable
connection in a Windows environment. TN3270 is often a better
choice and is easier to configure if the mainframe has a TCP/IP
connection.
In the event that connections are required from different regions or
different host computers, multiple sessions are supported up to the
limits of the adapter hardware and software. For example, a 3270
coaxial adapter typically will support five separate printer or
terminal sessions to a single cluster controller.
To send notification messages back to an application on the host
system, a separate connection method (known as a connection
channel) can be defined. See ”Setting Up a Named Pipe Capture”
on page 17.
5250 emulation
To send documents from the host computer to the Integration
Module, 5250 emulation software is recommended. A serial
connection with a protocol converter can be used, but it is not
recommended.
The protocol converter sends data to the OpenText RightFax via a
serial cable connected between the converter and one of the COM
ports on the OpenText RightFax. If this method is used, the
Integration Module must be configured to accept input on the serial
port.
To send notification messages back to the host, SQL via ODBC is
recommended. Emulation software via 32-bit high level language
application programming interface (HLLAPI) or via a serial
connection also can be used. See ”Setting Up a Serial Capture”
on page 20.
IBM WebSphere MQ client for Windows
TCP/IP socket connection
You can set up a direct socket connection via TCP/IP to and from
the OpenText RightFax through any available port. This usually
requires that you acquire or create connection software for the host
system. See ”Setting Up a TCP/IP Port Capture” on page 23.
The Integration Module can communicate with an IBM WebSphere
MQ 6 channel via TCP/IP. See ”Setting Up an IBM WebSphere
MQ Connection” on page 24.
File Transfer Protocol connection
The Integration Module can use FTP server services to accept
documents from the host computer. The Integration Module also
can use an FTP client to send notification messages back to an
FTP server on the host system.
For FTP connections, you must install and configure an FTP server
on the OpenText RightFax computer. See ”Setting Up Directory
Scanning” on page 19.
Chapter 2
Connecting the OpenText RightFax Integration Module
11
OpenText RightFax 10.5 Integration Module Guide
Using the Integration Setup Wizard
The Integration Module includes a wizard that helps you to create
configurations for many of the connection methods. Use the wizard
to:
z
z
z
z
Configure the Integration Module service and set defaults for
documents that are sent from it.
Configure input channels from the host application to the
Integration Module.
Set notification actions and messages. You can choose to print
or fax copies of documents as they are transmitted. You also can
define messages with descriptive information about the
documents as they are transmitted.
Format documents with filter templates.
The Integration setup wizard is designed to guide you through each
step of configuring the Integration Module. Instructions in this
guide supplement the instructions in the wizard. Review the topics
in this guide before you begin using the wizard.
To start the wizard
1. On the Start menu, select Programs > RightFax > Enterprise
Fax 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-click RightFax Integration
Module.
Note: If you don’t see Integration Module in the list, go to the
Control Panel and double-click the RightFax Integration Module from
there.
4. The Integration Module Configuration window opens.
Figure 2.3 The Integration Module Configuration Window
12
5. Click Integration Setup Wizard. The wizard starts, and the
Integration Setup Wizard window appears.
Figure 2.4 The Integration Setup Wizard
Define inputs for the host application
In this series of steps, you can define the settings for receiving data
from host applications via a named pipe, directory, TCP/IP, IBM
WebSphere, or a custom input type.
For each communication method, you will specify the
communications protocol and transmission method, port, directory,
or queue to monitor, and the configurations needed for each
protocol. You will:
1. Name the input.
2. Specify the input type.
3. Configure the input.
These settings are also described in Chapter 3, ”Configuring the
RightFax Integration Module to Receive Data”.
Set notification actions and messages
This window is the starting point for the configuration. Select from
the configuration tasks, as described in the following sections.
Configure the Integration Module service
In this series of steps, you can define information that will appear
on each fax that is sent from the Integration Module. Some of these
settings can be overridden with facsimile command language
(FCL) in the documents that are sent.
You can make the following default settings for documents:
z
z
z
z
z
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 the
page. See ”Setting Defaults for FCL Documents” on page 126.
In this series of steps, you can define notification actions and
messages.
Notification actions can:
z
z
Fax sent documents, whether successfully or not successfully
transmitted, to an internal fax number.
Print or fax documents that cannot be successfully transmitted
because data is missing.
Notification messages can:
z
z
Notify users that a document was sent.
Notify an administrator of the status of documents.
Notification messages can provide descriptive information, such as
whether or not a document was transmitted, explanations of errors,
and transmission duration, dates, and times. These messages are
sent to a host application from the Integration Module when it
processes and sends documents.
Chapter 2
Connecting the OpenText RightFax Integration Module
13
OpenText RightFax 10.5 Integration Module Guide
These settings are also described in Chapter 8, ”Document
Transmission and Notifications”.
Format documents
In this series of steps, you can create filter templates for
documents with MapText. These settings are also described in
Chapter 4, ”Creating Filter Templates”.
14
Chapter 3
Configuring the RightFax Integration Module to Receive Data
This chapter describes the procedures for configuring the RightFax
Integration Module to receive data. You will create an input device
for receiving or retrieving data by writing a command line for each
type of input needed in the system.
4. In the left pane of the RightFax Integration Module
Configuration window, click Inputs. The input settings appear.
Figure 3.1 The Inputs Settings
Note that command lines are case-sensitive.
Creating an Input Device
1. On the Start menu, select Programs > RightFax > Enterprise
Fax Manager. The Enterprise Fax Manager window opens.
2. In the Fax Servers list, click the name of the server where the
RightFax Integration Module is running.
3. In the Service Name list, double-click RightFax Integration
Module. The RightFax Integration Module Configuration
window opens.
15
OpenText RightFax 10.5 Integration Module Guide
5. Right-click Inputs, and select Add Input Device from the
7. Enter the settings for the type of data input, as described in the
shortcut menu. The Add Input Device dialog box appears.
following sections:
z
Figure 3.2 The Add Input Device Dialog Box
z
z
z
z
“Setting Up a Named Pipe Capture” page 17
“Setting Up Directory Scanning” page 19
“Setting Up a Serial Capture” page 20
“Setting Up a TCP/IP Port Capture” page 23
“Setting Up an IBM WebSphere MQ Connection” page 24
To create the settings for an input, you will type a command line
or select options in the dialog box. When you select an option in
the dialog box, the option appears in the command line. For
example, when you select the check box Display Verbose
Output, -v appears in the Complete Command Line box.
6. In the Input Type list, select the type of data input needed for
the communication method implemented for the host system.
When you select an option, the available settings for the input
appear in the RightFax Integration Module Configuration
window.
Figure 3.3 The RightFax Integration Module Configuration Window
The
command
line appears
as you make
entries.
16
Setting Up a Named Pipe Capture
This procedure creates an input device that receives data from a
host application via a named pipe. The program Nplisten.exe
creates a named pipe, scans it, and then executes a command on
data found in the pipe. Typically, this input type accommodates
data that is formatted for a line printer (LPR).
To set up a named pipe capture
4. Complete the entries in the dialog box, as described in the
following table. These settings correspond to Nplisten.exe
command line options.
Table 3a Add Input Device Settings for a Named Pipe
Command line
option
Setting
Named Pipe to
Create
-p pipename
1. In the Input Type list, select Named Pipe (LPR). The named
pipe settings appear.
Figure 3.4 Settings for a Named Pipe Input Device
Description
The name of the named pipe
that Nplisten.exe will monitor
for files. You can enter any
name for the pipe in one of the
following formats:
pipename
z \\.\pipe\pipename
z
Execute on
Input (-c
option)
-c “makedoc $$”
The command to execute on
files received via the named
pipe. Makedoc.exe begins the
process of converting data
from the host application into a
fax.
The variable $$ indicates that
all files should be processed
with Makedoc.exe.
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 all
files will be processed with Makedoc.exe. “Hplpr” is a name for an
LPR printer.
To test a named pipeconnection
2. Select the check box Enable this Input device.
To test a named pipe connection
3. In the Name box, enter a descriptive name for this input device.
Chapter 3
Configuring the RightFax Integration Module to Receive Data
17
OpenText RightFax 10.5 Integration Module Guide
1. Make sure you've created a printer on the OpenText RightFax
server for the named pipe input. This may be the HostFax
printer.
2. Stop the Integration module service.
3. Pause printing to the printer that was created for the named
pipe input.
4. Send a test document from the host application to the printer.
Typically this will be done by copying the file from a command
prompt.
5. Look in the print queue to verify that the test document has
been sent to print.
6. Take the printer out of pause mode.
7. Open a command prompt and navigate to
..RightFax\Production\bin.
8. Go to the Integration Module Configuration window in
Enterprise Fax Manager, and under Inputs highlight the pipe
you're testing; copy the Complete Command Line text and
paste it into the command prompt. Hit Enter.
9. Now navigate to ..RightFax\Production\MakeDoc.
10. Open and examine the test document.
Documents that are created with filter templates (filter mode)
will be plain ASCII text.
z Documents that are created in native mode will be FCL
documents-a combination of FCL commands and document
data from the host application.
z PCL or PostScript documents will be in PCL or PostScript
format with FCL commands on the first "false" page.
11. At the command prompt stop the running application by hitting
Ctrl/C.
z
12. Type "Buffer" or "Buffer.exe" and hit Enter.
13. The file in MakeDoc will disappear, and a new file will appear in
..RightFax\Production\Seq. l.
14. At the command prompt stop the running application by hitting
Ctrl/C.
15. Type "parse" or "parse.exe" and hit Enter.
16. Parse completes the conversion of the file. You will soon see
the fax in FaxUtil.
17. Re-start the Integration Module service.
18
Setting Up Directory Scanning
This procedure creates an input device that retrieves data by
scanning a folder for files. The program Bufdir.exe retrieves the
files, creates a subdirectory for each calling fax server then copies
the file into the subdirectory before processing. Having discrete
subdirectories prevents duplication of faxes.
To set up directory scanning
1. In the Input Type list, select Directory. The directory settings
appear.
Figure 3.5 Settings for a Directory Scanning Device
4. Complete the entries in the dialog box, as described in the
following table. These settings correspond to Bufdir.exe
command line options.
Table 3b Add Input Device Settings for Directory Scanning
Command
line option
Setting
Description
Pattern to use
for Filename
Search
-p pattern
Enter the file types for which
Bufdir.exe will scan, for example,
*.txt. The default is *.*.
Don’t delete
Input Files
-d
This setting is useful when testing
the connection to the host
application. It determines whether
or not the files in the folder are
deleted after they are retrieved by
Bufdir.exe.
Files are deleted by default.
Exit Code
-r code
This setting determines that files
will not be deleted until the
program encounters a specified
exit code.
# of Threads
-t threads
Specifies the maximum number of
threads of Bufdir.exe to run
simultaneously. The default is 1.
Exit after one
pass through
Folder
-o
Quit after scanning the folder
once.
Secs. to Loop
-l seconds
This setting is commonly used
with a shared folder on Windows.
Enter the interval in seconds that
Bufdir.exe will scan for files. The
default is to scan the folder when
notified by Windows that a file
has been placed in the folder.
2. Select the check box Enable this Input device.
3. In the Name box, enter a descriptive name for this input device.
Chapter 3
Configuring the RightFax Integration Module to Receive Data
19
OpenText RightFax 10.5 Integration Module Guide
Table 3b Add Input Device Settings for Directory Scanning (Continued)
Setting
Command
line option
Secs. to Age
-w seconds
Description
This setting assures that the file is
up to date before it is processed.
If your network is slow, this setting
provides time for the completed
document to be delivered to the
folder.
Enter the number of seconds to
wait before retrieving the file.
Don’t check for
file in use
-u
This setting determines that
Bufdir.exe will not check for files in
use before retrieving them.
Folder to
Monitor
Folder name
and path
Enter the name of or the path to
the folder to watch for
documents.
Execute on
Input (-c option)
-c “makedoc
$$”
The command to execute on files
received. Makedoc.exe begins the
process of converting data from
the host application into a fax.
The variable $$ indicates that all
files should be processed with
Makedoc.exe.
Example bufdir -c “makedoc $$” c:\program
files\rightfax\production\inbox
In this example, Bufdir.exe will run the command “makedoc” on files
in the specified directory. The variable $$ indicates that all files will
be processed with Makedoc.exe.
To test the directory scanning connection
1. Stop Bufdir.exe by stopping the RightFax Integration Module
service in Enterprise Fax Manager.
2. Send a test document from the host application to the folder
specified in the Bufdir.exe command line.
3. Look in the target folder on the RightFax Integration Module to
verify that the test document was received.
4. Start the RightFax Integration Module service in Enterprise Fax
Manager.
Setting Up a Serial Capture
This procedure creates an input device that retrieves data via a
serial port. The program Capture.exe retrieves the data.
20
To set up a serial capture
1. In the Input Type list, select Serial Capture. The serial capture
settings appear.
Figure 3.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.
Chapter 3
Configuring the RightFax Integration Module to Receive Data
21
OpenText RightFax 10.5 Integration Module Guide
4. Complete the entries in the dialog box, as described in the
following table. These settings correspond to Capture.exe
command line options.
Table 3c Add Input Device Settings for a Serial Capture
Input setting
Command
line option
End Sequence
-S sequence
Specify the sequence of
characters that will indicate the
end of each document that is
received via this serial port.
Handshaking
-H
Specify the handshaking method
for the serial port.
-x
Table 3c Add Input Device Settings for a Serial Capture (Continued)
Input setting
Command
line option
Right Brace
Char
-R character
Specify one or more characters
that form the right (closing)
delimiter in documents that are
received via this serial port.
Allow EOT or
ETB to end
input
-E
Select this check box to specify
that an end-of-text character
(ASCII 4 or CTRL+D) or an
embedded
end-of-transmission-block (ETB)
character (ASCII 23 or
CTRL+W) will mark the end of
each document that is received
via this serial port.
Stop Bits
-s stopbits
Specify the bit (0 or 1) that will
indicate the end of each
document that is received via this
serial port.
Parity
-e
Specify the parity for this serial
port.
Description
H = Hardware handshaking
x = XON\XOFF (software)
handshaking
Baud Rate
-b baud rate
The baud rate at which
Capture.exe will scan the serial
port.
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 to
carriage return-line feed pairs. In
other words, <CR> (carriage
return) will be converted to
<CR><LF> (carriage return and
line feed).
Left Brace Char -L character
Specify one or more characters
that form the left (opening)
delimiter in documents that are
received via this serial port.
Description
-o
-e establishes even parity.
-o establishes odd parity.
COM1 or
COM2
N/A
Execute on
-c “makedoc
Input (-c option) $$”
Specify the COM port. The
default is COM1.
The command to execute on files
received. Makedoc.exe begins
the process of converting data
from the host application into a
fax.
The variable $$ indicates that all
files should be processed with
Makedoc.exe.
22
Example capture -b 9600 -c “makedoc $$” com1
Setting Up a TCP/IP Port Capture
In this example, Capture.exe will read input from the COM1 serial
port and then execute the command “makedoc” on the data. The
variable $$ indicates that all files will be processed with
Makedoc.exe.
This procedure creates an input device that retrieves data via a
TCP/IP port. The program Portlstn.exe retrieves the data.
To test a serial connection
1. In the Input Type list, select TCP/IP Port. The TCP/IP port
1. Stop Buffer.exe using one of the following methods:
Stop it from the Process tab in Windows Task Manager.
z Enter signal HFBufferStop at the command prompt.
z Enter kill /f buffer.exe at the command prompt (not
recommended).
2. Verify that Buffer.exe is stopped by looking in Windows Task
Manager.
z
To set up a TCP/IP port capture
settings appear.
Figure 3.7 Settings for a TCP/IP Port Input Device
3. Send a test document from the host application to the serial
port specified in the Capture.exe command line.
4. In Windows Explorer, navigate to RightFax\Production\Makedoc
and verify that the test document was received.
5. In Enterprise Fax Manager, start Buffer.exe by stopping and
starting the RightFax Integration Module service.
2. Select the check box Enable this Input device.
3. In the Name box, enter a descriptive name for this input device.
Chapter 3
Configuring the RightFax Integration Module to Receive Data
23
OpenText RightFax 10.5 Integration Module Guide
4. Complete the entries in the dialog box, as described in the
following table. These settings correspond to Portlstn.exe
command line options.
Table 3d Add Input Device Settings for a TCP/IP Port Capture
Input setting
Command line
option
TCP/IP Port #
-p number
Enter the number of the port to
monitor.
Execute on
Input (-c
option)
-c “makedoc $$”
The command to execute on
files received. Makedoc.exe
begins the process of
converting data from the host
application into a fax.
Description
The variable $$ indicates that
all files should be processed
with Makedoc.exe.
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. The
variable $$ indicates that all files will be processed with
Makedoc.exe.
To test a TCP/IP port connection
1. Stop Buffer.exe using one of the following methods:
z
z
z
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 Task
Manager.
3. Send a test document from the host application to the TCP/IP
port specified in the Portlstn.exe command line.
4. In Windows Explorer, navigate to
RightFax\Production\Makedoc and verify that the test document
was received.
5. In Enterprise Fax Manager, start Buffer.exe by stopping and
starting the RightFax Integration Module service.
Setting Up an IBM WebSphere MQ Connection
This procedure describes the configuration needed to
communicate with an IBM WebSphere MQ remote queue
manager to retrieve messages (outgoing documents).
The program mqget.exe utilizes the IBM WebSphere MQ client to
connect to the remote queue manager and retrieve messages from
the 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 the
messages from.
24
To set up an IBM WebSphere MQ connection
Syntax
mqget -C channel -H hostname -M queuemanager
-Q queue [options]
1. In the Input Type list, select Custom. The custom settings
appear.
Table 3e Mqget.exe Command Line Options
Figure 3.8 Settings for a Custom Input Device
Option
Description
-C channel
Name to use for this connection channel.
-H hostname
Fully qualified domain name of the IBM
WebSphere MQ queue manager.
-M queue manager Queue manager for RightFax that is defined on
the IBM WebSphere MQ server.
-Q queue
Queue to retrieve messages from. The
RightFax Integration Module will monitor and
retrieve messages from this queue.
-c “makedoc $$”
The command to execute on files received.
Makedoc.exe begins the process of converting
data from the host application into a fax.
The variable $$ indicates that all files should be
processed with Makedoc.exe.
2. Select the check box Enable this Input device.
-d
Display debugging output. This is helpful if you
experience difficulty connecting to the server.
-p port
TCP/IP port number to use for remote
connection. The default is 1414.
-1
Selects Version 1 of the WebSphere MQ
Application Programming Reference.
3. In the Name box, enter a descriptive name for this input device.
This option must be used because MQGet.exe
is not designed to work with the WebSphere
MQ API Version 2.
4. In the Complete Command Line box, enter a command. The
Mqget.exe command line syntax and options are described in
the following section.
-tCCSID
Specifies the codeset name for a language. A
list of the codeset IDs (CCSIDs) supported by
WebSphere MQ is available from IBM.
Example mqget -C RF_Chan -H qmmaster2 -M RightFax
-Q RF_Queue -c ”makedoc $$” -p 1414 -1
Chapter 3
Configuring the RightFax Integration Module to Receive Data
25
OpenText RightFax 10.5 Integration Module Guide
In this example, Mqget.exe will monitor the IBM WebSphere MQ
channel RF_Chan in the domain named Qmmaster2. It will connect
to 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 $$ indicates
that all files will be processed with Makedoc.exe.
Setting the MQGet polling interval
1. Log on to the RightFax server as an administrator.
2. Open the Windows registry editor and browse to
HKLM\Software\RightFax\Production\MQSeries.
3. Create a new Dword entry called
MQ_Get_ConnectionTimeout
4. Set the data value to the interval for scanning the queue, in
seconds.
5. Close Windows registry editor.
To test the IBM WebSphere connection
1. Open a command prompt window.
2. At the command prompt, enter the command line that was
written to create the IBM WebSphere MQ input, and then press
ENTER.
If the connection is successful, then you should see text similar to
that shown in the following example. If the input connection is not
successful, then you will see error messages.
Figure 3.9 Successful Test of IBM WebSphere MQ Connection
26
Chapter 4
Creating Filter Templates
Understanding Filter Templates
The Integration Module processes documents from the host
application by interpreting facsimile command language (FCL) and
performing functions based on the commands. The Integration
Module can do this in one of two ways: native mode or filter mode.
z
z
With native mode, you include FCL commands in the document
data that is sent from the host application. This may require
custom programming to add FCL to documents or to templates
in the host application or to insert FCL in the data stream.
With filter mode, you create “filter templates” that add FCL to the
document data after it is sent to the Integration Module for
processing. A filter template is a map of the document data that
contains the FCL that is required to create and send the
document.
This chapter discusses the creation of filter templates that support
filter mode.
Filter templates provide the following features:
z
z
z
z
z
z
Data mapping provides sending information to the Integration
Module, such as the recipient name, fax number, and e-mail
address. It also provides information from the source document
for the fax cover sheet.
Data mapping provides information from the source document for
notification messages, such as the sender's name and e-mail
address. Combined with the Integration Module, notifications
provide the status of the sent document to the sender, to a
system administrator, or another recipient.
Background forms can provide visual interest to the filter
template, with the features of a pre-printed form such as a
purchase order or stationery. Background forms are included by
linking an image file to a filter template.
Graphics can be added. Graphics are included by linking an
image file to a filter template.
Data tables can be linked to the form so that information can be
added to a document before it is sent. This is useful for adding
data 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.
27
OpenText RightFax 10.5 Integration Module Guide
In the following example, the mapped data elements are the
company name and fax number.
1. An invoice document is sent from host application that does not
include FCL.
2. On the OpenText RightFax server, Filter.exe receives the
document data and it retrieves a filter template. The filter
template identifies data in the document that is needed for
addressing and sending the document. In this filter template,
the company name and fax number are mapped.
3. The filter software extracts the content of the company name
and fax number fields and creates the {{company}} and {{fax}}
FCL commands.
4. The document data now contains FCL. The {{company}} and
{{fax}} FCL commands are created by the mapped fields in the
filter template. The document can now be processed and sent
by the Integration Module.
Figure 4.1 Filter Mode Document Flow
28
Preparing to Create Filter Templates
Before you begin creating filter templates, prepare the following
information:
z
z
z
z
z
z
z
For each document that will be sent, obtain an ASCII text file that
includes the data that will be used to the send the document, to
send a notification message, or to be placed on cover sheets.
This data might include the fax number, printer, voice telephone
number, and the sender’s name and address. Save the text files
in the folder RightFax\Production\Include.
To capture a document from the host application data stream,
send the document via an input channel on the Integration
Module. The host data must be ASCII text with no extra
characters or encoding. This may mean that a customized script
must be written to prepare the data for the filter template. The file
format should not be PCL, PostScript, or Portable Document
Format (PDF).
Identify each background form that should be included with each
document, then create the forms and save them in the
appropriate folder on the OpenText RightFax server. See
”Creating and Linking Background Forms” on page 132.
Identify each cover sheet that should be included with each
document, then create the cover sheets and save them in the
appropriate folder on the RightFax server. See ”Creating and
Attaching Cover Sheets and Other Files” on page 49.
Identify each graphic element, such as logos or signatures, to
include in the filter template, then create the graphics and save
them in the appropriate folder on the RightFax server. See
”Defining Fax Page Appearance” on page 59.
Create include files, if needed. See ”Reusing FCL Commands
Across Many Documents” on page 45.
Create lookup tables, if needed using the {{lookup}} FCL
command. See ”FCL Commands” on page 165.
Create TCP/IP print queues in the Integration Module. This is
typically one print queue per filter.
Assigning filter templates to documents
You have two options for assigning a filter template to a document:
z
z
Assign a template ID to each filter template. Data in the
document from the host application is mapped to a field in the
filter template that identifies the template. See ”Understanding
the Field Types” on page 38.
Create up to 70 unique input channels (for the Integration
Module) or 2 input channels (for the RightFax Integration
Business Module) for the documents to process with filter
templates. One input channel can process documents for one
filter template. See ”Creating an Input Channel for Filter
Documents” on page 42.
Maintaining the filter template
Filter templates are designed to work with data that occurs in static
locations in the document data. If the document changes and a
data element is moved to a new location, then the filter template
must be revised to fit the change.
Creating a New Filter Template
Use the MapText program to create filter templates.
MapText includes a preview function, so that you can preview and
adjust each template as you create it.
To create a filter template, complete the following steps:
“Step 1: Overlay the sample data on a MapText document”
(page 30)
“Step 2: Map the document data to MapText fields” (page 32)
“Step 3: Establish page length, orientation, and background forms”
(page 35)
“Step 4: Insert FCL” (page 36)
“Step 5: Preview the filter” (page 37)
Chapter 4
Creating Filter Templates
29
OpenText RightFax 10.5 Integration Module Guide
The instructions in this chapter refer to sample files that are
installed with the Integration Module. The files are described in the
following table.
Table 4a Sample Files Installed with Filter for Production
Sample file
Location
Description
SampleData.txt RightFax\Production
\Include
An example of a document
that a host application
might create. It is
formatted as a single print
stream capture that
contains two documents:
a three-page purchase
order and a one-page
purchase order.
SampleForm.tif
An example of a form onto
which you might print a
purchase order. MapText
will merge SampleData.txt
with SampleForm.tif to
create an image of the
document printed on a
pre-printed form.
RightFax\Production
\Forms
Step 1: Overlay the sample data on a MapText document
1. On the RightFax server in Windows Explorer, navigate to
RightFax\Production\Bin and run MapText.exe. The MapText
window opens with a blank document called MapText1.
Figure 4.2 The MapText Window
2. On the Tools menu, click Overlay Data File.
30
3. Select your sample document or SampleData.txt, and then click
Figure 4.3 Host Data Merged with a Blank MapText Document
Open. The following example illustrates that SampleData.txt is
placed in the blank MapText document. This image shows the
data that forms Metropolitan Inc. purchase orders. In this case,
the purchase order will go to Universal Suppliers.
This is the “bill to” address
and contact information.
This is the “ship to” address
and contact information.
This is the recipient of the purchase order.
Universal Suppliers will bill to the first address and ship to the second address.
The horizontal and vertical rows of numbers at the left
and top borders are part of the sample file SampleData.txt. They are provided to illustrate that MapText filter
templates are grids on which you create fields at x- and
y-coordinates.
Chapter 4
Creating Filter Templates
31
OpenText RightFax 10.5 Integration Module Guide
Step 2: Map the document data to MapText fields
In this step, you identify pieces of data in the document that the
OpenText RightFax will use to process and send the documents.
You will:
z
z
z
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 map
three host data elements (company name, fax number, and
purchase order number) to three fields (company, fax, and
comment).
For a detailed description of each type of field, see “Understanding
the Field Types” on page 38.
1. Define the field in the document template that will contain the
name of the recipient company. Drag the mouse to select
Universal Suppliers. The New Field dialog box appears.
In the following figure, the name of the company that will receive
the document (Universal Suppliers) is selected. It will be
defined as a field. Note that the field is longer than the text it
contains. This provides space for long company names that
might appear in future documents.
Figure 4.4 Defining the Company Name as a Field
32
2. In the New Field dialog box, in the Description box, enter a
description for the field, such as “Company.”
Figure 4.5 Assigning Attributes to the Field
Enter a descriptive name
for the field you’re creatSelect a field type.
5. Define the field in the document template that will contain the
purchase 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 4.6 Defining the Purchase Order Number as a Field
(13,12) describes the xand y-coordinates for the
upper-left corner of the
field.
3. In the Field Type list, click Company.
4. Click OK.
6. In the Description box, enter a description for the field, such as
“PO Number.”
Chapter 4
Creating Filter Templates
33
OpenText RightFax 10.5 Integration Module Guide
7. In the Field Type list, click Comment.
One attribute of the Comment field type is that it starts a new
document when the data in the field changes. In this case, a
new purchase order document will be created with each new
purchase order number that is received. For detailed information
on the Comment field type, see “Understanding the Field Types”
on page 38.
9. Define the field in the document template that will contain the
fax number of the company that will receive this document. Drag
the mouse to select the fax number. The New Field dialog box
appears.
In the following figure, the fax number (520-555-3282) is
selected.
Figure 4.8 Defining the Recipient Fax Number as a Field
Figure 4.7 Mapping the Purchase Order Field
8. Click OK.
10. In the New Field dialog box, in the Description box, enter a
description for the field, such as “Fax Number.”
34
11. In the Field Type list, click Fax.
Figure 4.9 Mapping the Fax Field Type
When RightFax receives a document using this filter template, it will
extract data from the defined fields and use it to address and send
the fax. It will also begin a new document each time a new
purchase order number is encountered in the purchase order field.
Step 3: Establish page length, orientation, and
background forms
1. On the File menu, click Properties, or click the Properties
button on the toolbar. The Properties dialog box appears.
2. In the Form list, select SampleForm.tif, or select a background
form that you have created.
3. In the Page Length (lines) box, enter 56.
12. Click OK.
13. On the File menu, click Save.
14. Give the filter template a descriptive name. It will be saved as a
MapText document (.mtd) in the RightFax\Production\Include
folder.
In this example, you have:
z
z
z
z
Mapped the company name in purchase order documents to the
“Company Name” field of the template. This created the FCL
command {{company Universal Suppliers}} that RightFax will use
to address the fax.
Mapped the purchase order number in purchase order
documents to the “Purchase Order” field of the template. This
created the FCL command {{comment PO13579}}.
Mapped the fax number in purchase order documents to the “Fax
Number” field of the template. This created the FCL command
{{fax 520 555 3282}} that RightFax will use to send the fax.
Saved the purchase order template.
SampleData.txt includes an end-of-page symbol that indicates
the bottom of the second page. The page breaks at whichever
comes first: the number you enter in the Page Length (lines)
box or an end-of-page symbol. In SampleData.txt, the
end-of-page symbol is a form feed symbol (^L, or ASCII-12).
If the data from the host application does not include an
end-of-page symbol, you must specify the page length. To do
this in MapText, point the mouse at the last line on a page, and
then look at the status area in the lower-right corner of the
MapText window. The following figure shows that
SampleData.txt is 56 lines long.
Figure 4.10 The MapText Tray
The default page length for documents is 66 lines for portrait
orientation and 33 lines for landscape orientation. You can test
the validity of the count in “Step 5: Preview the filter” on
page 37.
4. Select Portrait.
Chapter 4
Creating Filter Templates
35
OpenText RightFax 10.5 Integration Module Guide
5. In the Print copies in absence of fax number box, click 1.
When no fax number appears in the document from the host
application, this function sends the specified number of copies
to the default printer specified for the Integration Module.
5. Select one of the following options:
z
z
Step 4: Insert FCL
You can extend the filter template by adding FCL commands to set
the proper syntax, and the placement of the commands within
documents. See ”FCL Commands” on page 165.
To insert FCL
z
z
To specify that the FCL should apply to every page of the
document, click Every page.
To specify that the FCL should apply to only the first page of
the document, click First page.
To specify that the FCL should apply to only the first page of
the document, click Last page.
To specify the page number for the FCL, click Page #, and
enter the page number.
6. Click OK to close the Custom FCL dialog box. Click OK again
to display the MapText window.
1. On the File menu, click Properties, or click the Properties
button on the toolbar. The Properties dialog box appears.
2. Click New. The Custom FCL dialog box appears.
Figure 4.11 The Custom FCL Dialog Box
7. On the File menu, click Save, or click the Save icon on the
toolbar. The following example illustrates how FCL appears in
the Properties dialog box after it is defined.
Figure 4.12 Custom FCL Added to the Filter
“01” indicates that this is the
first line of FCL code in this filter
template, and so on.
“BE” indicates that this line of
FCL will apply to the beginning
of every page of the document
that uses this filter template.
3. Enter the FCL using the proper syntax and delimiters.
4. To specify that the commands will be inserted at the beginning
of each document, select the Beginning of page check box.
“BF” indicates that this line of
FCL will apply to the beginning
of the first page of the document
that uses this filter template.
36
Step 5: Preview the filter
Figure 4.13 Your First Attempt Might Yield Alignment Errors
To preview the filter, use the Generate Image function. Generate
Image displays the background form merged with the sample
document data and therefore helps you fine-tune the alignment. It
does not test that the RightFax server can receive data from the
host application and process the data correctly with the filter.
To preview the filter
On the Tools menu, click Generate Image, or click the Generate
Image button on the toolbar. MapText generates the image, and
the default TIFF image viewer opens with the finished document.
Examine all the pages of the finished document. If you are using a
background form, verify that it aligns with the document data.
In the following example, the form is not aligned with the document
data. For help troubleshooting filter templates, see
“Troubleshooting” on page 41.
Chapter 4
Creating Filter Templates
37
OpenText RightFax 10.5 Integration Module Guide
Understanding the Field Types
Table 4b MapText Field Types (Continued)
The following table lists the field types and their uses.
Field
type
Table 4b MapText Field Types
Company
Field
type
Abort
Description
Cancels the creation of a
document when the
specified text appears in
the field.
Corresponds to the
{{abort}} FCL code.
Comment
Starts a new document
when text in this field
changes.
Map the field type to
this data element
Map this field to data that
is unique in each
document.
Example
The purchase order
number is unique in each
document. When the
purchase order number
changes, a new
document is started.
See also the Page field
type. The Page field type
overrides the Comment
field type.
Specifies the recipient
company name.
Corresponds to the
{{company}} FCL code.
This field type is
commonly used for
testing purposes.
Example
For testing, you might
create documents in a
large batch that contain
the word “test” in the
Abort field. The
documents would not be
sent.
Description
Map the field type to
this data element
Map this field to the name
of the company that
should receive the
document.
This information may be
placed on the cover sheet
or in a notification
message.
Contact
Specifies the recipient
name.
Corresponds to the
{{contact}} FCL code.
Cover
Specifies the cover sheet.
Corresponds to the
{{cover}} FCL code.
Map this field to the name
of the person who should
receive the document.
This information may be
placed on the cover sheet
or in a notification
message.
Map this field to the cover
sheet file name.
The cover sheet file must
be stored in the directory
RightFax\Production\Cov
ers. If the file is not found
in the directory when the
document is created, the
default cover sheet is
used.
38
Table 4b MapText Field Types (Continued)
Field
type
Email
Fax
Description
Table 4b MapText Field Types (Continued)
Map the field type to
this data element
Specifies the e-mail
address to send.
The e-mail address of the
person or company who
is sending this document
z Notifications about the
sent document to the host (used to send a
notification to the e-mail
application.
address).
z The document via e-mail
The e-mail address of the
using the InternetLink
person or company to
Module.
which you are sending
Corresponds to the
this document (requires
{{email}} FCL code.
InternetLink).
For more information, see
the InternetLink Module
Guide.
Specifies the fax number.
Corresponds to the {{fax}}
FCL code.
Field
type
Description
Graphic
File name of a graphic.
Map the field type to
this data element
Map this field to the
graphic file name. The file
name must match the text
in the mapped field. For
example, Mark Jones'
signature file must be
named MarkJones.tif.
The graphic file format
must be .tif. The file must
be stored in the directory
RightFax\Production\For
ms. If the file is not found
in the directory when the
document is created,
then the image will not
appear in the document.
Map this field to the fax
number where the
document should be sent.
Example
An image such as a
signature or a company
logo can be inserted.
Include
Specifies the file name of
an include file.
Map this field to the
include file name.
Corresponds to the
{{include}} FCL code.
The file must be stored in
the directory
RightFax\Production\Incl
ude. If the file is not found
in the directory when the
document is created,
then an error will occur
and the document will not
be processed.
An “include” file can
contain commands and
data that are common to
many documents.
Chapter 4
Creating Filter Templates
39
OpenText RightFax 10.5 Integration Module Guide
Table 4b MapText Field Types (Continued)
Field
type
Lookup
Lookup2 Lookup9
Description
Specifies the file name of a
lookup table.
Corresponds to the
{{lookup}} FCL code.
A lookup table can provide
information that is not
contained in the document
that is sent from the host
application, such as the
recipient company name
and fax number.
Table 4b MapText Field Types (Continued)
Map the field type to
this data element
Field
type
The text in the mapped
field of the document will
be compared to the first
column in the specified
lookup table. When a
match is found, the
associated data in the
row will be used to send
the document, included
on the cover sheet, or
included in a notification
message.
Owner
When you create a
Lookup field, the Edit
lookup file button
appears. Click this button
to create or edit a lookup
file.
SendFax
The lookup table must be
stored in the
RightFax\Production\Incl
ude directory.
Example
The mapped field may
contain a vendor ID. In
the lookup table, vendor
ID data includes the
company name and fax
number. The company
name will be printed on
the cover sheet, and the
fax number will be used
to send the document.
Page
Description
Map the field type to
this data element
Specifies the sender's
name.
Map this field to the
sender's name.
Corresponds to the
{{owner}} FCL code.
The name can appear on
the cover sheet or in
notification messages.
Starts a new document
when the number 1
appears in this field
Map this field to the page
number.
Use this field to print a
document rather than fax it.
Map this field to the fax
number.
The document will be
printed if N, a space, or null
characters are found in this
field.
This field type is used
when not all recipients
have a fax number or
other address for
transmission. Such
documents would be
printed so that they could
be mailed.
See also the Comment
field type. The Page field
type overrides the
Comment field type.
40
Troubleshooting
Table 4b MapText Field Types (Continued)
Field
type
TemplateI
D
Description
Specifies the filter template
to use to format the
document.
Map the field type to
this data element
Map this field to text that
describes the document
or indicates the
document type. For
example, the words
“Purchase Order” may
indicate that the
Purchase Order template
be used to format the
document.
When text in the mapped
field matches the text
specified, the specified
template will be used to
format the document.
User1
User 2
Specifies user-defined
information.
User3
Corresponds to the
user-defined {{user1}},
{{user2}}, and {{user3}}
FCL commands.
Voice
Specifies the telephone
number for the recipient.
Map this field to text that
you want to appear on
the cover sheet or in a
notification message.
Map this field to the
phone number of the
person who will be
receiving the document.
The number can appear
on the cover sheet or in
notification messages.
This section provides troubleshooting tips for building filter
templates.
The background form is not aligned with data
In previewing a document that combines a background form with
document data, the data does not align with the background form.
Table 4c Background Form Does Not Align with Data
Possible cause
Solution
The margins for the data are
not set correctly. This causes
the data to be too far from or
too close to the left or top of
the page.
Add or edit the FCL commands for
the left and top margins. For
instructions, see “Step 4: Insert
FCL” on page 36.
The fonts are not set correctly.
This causes the data to be
aligned correctly in some
places but not in others.
Add or edit the FCL commands for
the font. For instructions, see “Step
4: Insert FCL” on page 36.
The number of lines on each
page is not correct. This can
cause the first page to align
correctly, but the data on the
second page is one line too
low or high, the data on the
third page is two lines too low
or high, and so on.
Set the correct number of lines for
each page of the document. For
instructions, see “Step 3:
The sample data from your
host application may include
print control language (PCL) in
the first line. If so, the data on
the first page will appear one
line below the top margin, and
the other pages will be aligned
correctly.
Remove the PCL from the data
stream that is sent from the host
application. For instructions, see
Establish page length,
orientation, and background
forms” on page 35.
“Preparing to Create Filter
Templates” on page 29.
Chapter 4
Creating Filter Templates
41
OpenText RightFax 10.5 Integration Module Guide
Document data does not match the background form
After correctly formatting documents for a period of time, the filter
template unexpectedly does not match the document data. For
example the background form does not line up correctly with the
data.
Documents are not addressed or are not sent correctly
Documents are incompletely addressed, the destination fax
number is incomplete, or other information appears truncated in the
document.
Possible cause
Possible cause
The fields for the data elements are not long enough.
Data from the host application may have changed, and the filter
template must be updated. For example, a carriage return or a new
data element may be added.
Solution
Re-size the fields.
Solution
Review the data that is sent from the host application and the filter.
If the data has changed, then you must change the filter template to
accommodate it. For instructions, see “Step 1: Overlay the sample
data on a MapText document” on page 30.
Extra files are not included
A cover page, signature, background form, or other attached file is
missing or is incorrect.
Creating an Input Channel for Filter Documents
You can create up to 70 unique input channels for the documents
that must be processed with filter templates. One input channel
can process documents for one filter template. The most common
input channels are:
z
z
z
Possible cause
The file name or path name for the attachment is not correct.
Solution
Verify that the file name or path to the file is correct and that the file
is stored in the correct directory. For instructions, see “Preparing to
Create Filter Templates” on page 29.
z
Named pipe capture (page 17)
Directory scanning (page 19)
Serial capture (page 20)
TCP/IP port capture (page 23)
42
The command line for the input channel must specify the filter
template. The following table describes the command line options
to use.
Table 4d Add Input Device Settings for a Named Pipe
Command line
option
Description
-c “filter |
makedoc”
The option -c specifies one or more commands
to execute on files received via the channel.
Filter.exe extracts the document data using
the filter template.
z Makedoc.exe begins the process of
converting document data from the host
application into a fax.
The pipe symbol (|) separates the two
commands in the command line. The
commands must be enclosed in quotation
marks.
z
-i filename.mtd
The option -i specifies that the specified
MapText document (filename.mtd) should be
included with the incoming data.
-f
Identifies filename.mtd as a file.
Example nplisten.exe -c “filter -i invoice.mtd -f $$
| makedoc” -p hplpr
In this example, Nplisten.exe will run the “filter” command against
the data file (represented by $$) received on the named pipe. Filter
will add FCL commands as designated by the invoice.mtd template
and pipe the result to “makedoc” for processing.
Chapter 4
Creating Filter Templates
43
OpenText RightFax 10.5 Integration Module Guide
44
Chapter 5
Reusing FCL Commands Across Many Documents
With the RightFax Integration Module, you can create a list of
commands and/or text strings that can be used in many
documents. This list is called an include file. For example, an
include file can contain a list of fax numbers, so that the same
documents can be addressed and sent to multiple recipients. Or it
can contain a set of FCL commands that set the text size and font
of the documents in which it is included.
Example You can use a global include file to set the default font
for all documents to Arial 11-point. To send a batch of
documents using a different font, use a standard include
file to change the font to Times 12-point.
The following example shows how a standard include file is used to
create and send a document.
Figure 5.1 Host Data Merged With an Include File
Understanding Include Files
You have two options for creating and using include files:
z
z
Global include files are provided in the
RightFax\Production\Include folder when you install the RightFax
Integration Module software. The files are empty. By default,
global include files are linked to all documents but have no
function unless you put information into them. Typically, global
include files are used to establish default attributes for all
documents.
Standard include files. You can create standard include files and
link them to documents with the {{include}} FCL command.
Typically, standard include files are used to change an attribute in
a large batch of documents.
In this example, the include file specifies a top margin ({{tm}}), a left
margin ({{lm}}), and a font. It also specifies that the file Logo.tif be
placed at specific coordinates.
45
OpenText RightFax 10.5 Integration Module Guide
Understanding the content of include files
You can place FCL commands in include files to reduce the
programming necessary to place commands in documents. You
can use any FCL command.
Also, you can place sentences, paragraphs, entire letters, and even
multi-page documents in include files. Because include files are
plain text (ASCII) documents, you must format the text with FCL
commands. Any text will appear in the body of the finished
document at the point where the {{include}} command or global
include file appears.
Understanding the placement of global include files
If the global include files contain content, the content will be
inserted at default locations in all documents, as described in the
following table.
Table 5a Placement of Data from Global Include Files
File name
Default location in the FCL documents
Global.beg
Beginning of document.
Global.end
End of document.
Global.def
Immediately after every fax number.
Global.inc
Immediately before every fax number and at the
end (before global.end).
The following table illustrates the default placement of information
from these global include files.
Table 5b Example FCL Document with Global Include Files
FCL document
Placement of data
{{BEGIN}}
{{Company Test}}
{{FAX 968-9601}}
{{Contact Jay Doe}}
{{FAX 968-9602}}
{{Contact Sid Brea}}
Body of the
document to be sent.
{{END}}
{{BEGIN}}Global.beg
{{Company Test}}
{{FAX 968-9601}}Global.def
{{Contact Jay Doe}}
Global.inc{{FAX 968-9602}}Global.def
{{Contact Sid Brea}}
Body of the document to be sent.
Global.inc Global.end{{end}}
Global.beg and global.end are used for general FCL commands
that are used only once per FCL document. Usually, these are FCL
commands that are carried over from one document to the next
when broadcasting, such as {{winsecid}}. {{Winsecid}} is not reset
automatically in broadcast documents, so placing it in Global.beg
causes it to become a default, setting a RightFax mailbox to be
used by all production documents.
Global.def and Global.inc are more commonly used than
Global.beg and Global.end.
Because of its placement in the FCL (after every fax number),
Global.def can be overridden if there are conflicting FCL
commands in the data sent from the host.
Example If you insert {{priority low}} in Global.def, all documents
will be sent at that priority except when a different
{{priority}} command is included in the FCL coming from
the host for that particular recipient.
46
Because of its placement in the FCL (before every fax number and
at the end, before Global.end), Global.inc overrides any conflicting
FCL.
including the different effects of a given command depending on
where it appears in a document. These effects will dictate into
which global include file you should insert certain commands.
Example If you insert {{priority low}} in Global.inc, all documents
will use that priority, ignoring any conflicting {{priority}}
commands that are included in the FCL coming from the
host.
Creating Include Files
Creating standard include files
You can use any word processor that will produce plain text
(ASCII), such as Microsoft Notepad, to create an include file. Insert
any FCL or other text that you want to appear in multiple
documents. Save the include file with an .inc extension in the
RightFax\Production\Include folder.
Inserting content into global include files
To open any of the global include files in the
RightFax\Production\Include folder, double-click the file. In the
Open With dialog box, select Notepad.
Storing include files
Save include files with any descriptive name with an .inc extension
in the RightFax\Production\Include folder.
Linking Include Files
Linking standard include files with the {{include}}
command
Use the {{include}} command to link an include file (one that you
have created and saved with an .inc extension in the
RightFax\Production\Include folder) with a document.
{{begin}}
{{fax 503-555-9023}}
{{include OfficeClosed.inc}}
Host data.
{{end}}
Insert any FCL or other text that you want to appear in multiple
documents.
This example would replace the {{include}} command with the
content of the file called OfficeClosed.inc, which resides in the
RightFax\Production\Include folder.
Warning Putting incorrect FCL into a global include file can cause
system-wide errors. For example, if you put {{include file.inc}} in an
include file called File.inc, then the file will attempt to insert itself in the
FCL document. The resulting infinite loop will cause RightFax to stop
responding.
Note Though valid include files must be stored with the extenstion .inc,
you do not have to write the extension in the command itself. In the above
example, either {{include OfficeClosed.inc}} or {{include OfficeClosed}}
would call in the appropriate file.
Every document sent through the RightFax Integration Module will
use the information that you add to a global include file. You must
understand the function of any FCL you insert in these files,
For detailed information on the {{include}} command, including
syntax and examples, see Chapter 10, ”Creating FCL Documents”.
Chapter 5
Reusing FCL Commands Across Many Documents
47
OpenText RightFax 10.5 Integration Module Guide
Linking global include files
The global include files are linked by default to every document that
the RightFax Integration Module processes. You do not need to link
the global include files to documents.
Because every document is linked to all the global include files, you
must use caution when inserting commands and other text into a
global include file. Inserting incorrect FCL into a global include file
can cause system-wide errors.
48
Chapter 6
Creating and Attaching Cover Sheets and Other Files
A cover sheet is the first page of a faxed document. It usually
includes information about the fax, such as the recipient’s name
and fax number, the sender’s name and telephone number, and the
total number of pages in the fax.
The RightFax system supports two kinds of cover sheets:
z
You can also attach other files at any point within a faxed document
using FCL commands.
z
Understanding Cover Sheets
RightFax cover sheets are templates with placeholders for the
information. The placeholders are filled with data and attached to a
document when it is processed for faxing.
Production cover sheets can contain FCL codes, text, and
keywords. These cover sheets are attached to documents by
inserting the {{cover}} command in the documents. The files are
named with the extension .cov, and they are stored in the folder
RightFax\Production\Covers. The RightFax Integration Module
generates these cover sheets.
Enterprise cover sheets can contain embedded codes, text, and
keywords. These cover sheets are attached to documents by a
user when the fax is created or by default settings for the user or
the enterprise. The file format can be print control language (.pcl)
or Microsoft Word (.doc), and they are stored in the folder
RightFax\FCS. The RightFax server generates these cover
sheets. You can use .pcl and .doc cover sheets with FCL
documents. For details on .pcl and .doc cover sheets, see the
RightFax Administrator’s Guide.
The following example illustrates how the RightFax Integration
Module generates a simple cover sheet and then attaches it as the
first page of a fax.
49
OpenText RightFax 10.5 Integration Module Guide
Figure 6.1 Sample Production Cover Sheet
Creating Cover Sheet Templates
Using default cover sheet templates
The RightFax Integration Module includes a cover sheet called
Auto.cov. This file is the default cover sheet, unless you specify a
different one with the RightFax Integration Module Configuration
program. For information on establishing a default cover sheet, See
”Setting Defaults for FCL Documents” on page 126.
Auto.cov contains generic information such as the company,
contact, owner, fax number, and total pages in the fax. It is located
in the folder RightFax\Production\Covers.
In this example, the command {{cover GeneralUse.cov}} retrieves
the template file GeneralUse.cov from the
RightFax\Production\Covers folder. GeneralUse.cov contains text
and keywords, which the RightFax Integration Module populates
with information from the document data from the host application.
Notice that “To ^company” in GeneralUse.cov becomes “To Tigard
Outfitters” in the finished cover sheet. That is because the
^company keyword maps to the content of the {{company}} FCL
command.
If the {{cover}} command is included in the document data, but a
cover sheet name is not specified, then Auto.cov will be used.
Creating a basic cover sheet template
1. Open Microsoft Notepad or another word processing
application that will produce plain text.
2. Type text, FCL, or keywords in the template.
z
z
Using cover sheets with broadcasts
Production cover sheets cannot be used when broadcasting. See
”Using Cover Sheets in a Broadcast” on page 130.
z
See ”Adding blocks of text to a cover sheet from the
document data” on page 50.
See ”FCL for cover sheets” on page 53.
See ”Keywords for cover sheets” on page 51.
3. Type {{end}} in the last line of the cover sheet.
4. Save the file with the extension .cov in the folder
RightFax\Production\Covers.
Adding blocks of text to a cover sheet from the document
data
In addition to typing text in a cover sheet template, you can use text
from the document data to populate a cover sheet. This is useful
when a block of text on a cover sheet must be unique in each
document.
50
Use the {{covertext}} and {{endcovertext}} commands in the
document data and the ^covertext keyword in the cover sheet
template. The following figure shows the relationship between the
{{covertext}} command and the ^covertext keyword.
Note Coversheets provide a maximum of 75 characters, per line.
4. Close the Windows registry.
Keywords for cover sheets
The following table lists keywords you can use in production cover
sheets. Each keyword is populated with the content from the FCL
code that is included with the document data. In the cover sheet
template, each keyword must begin with the carat symbol (^).
See ”FCL Commands” on page 165.
Figure 6.2
Table 6a Cover Sheet Keywords and FCL Equivalents
Keyword
FCL equivalent Notes
^altfax
{{altfax}}
Includes whatever data is in the
{{altfax}} code.
^billing
{{billing}}
^billing2
{{billing2}}
Includes whatever data is in the
{{billing}}or {{billing}} code.
^comment
{{comment}}
Includes whatever data is in the
{{comment}} code.
^company
{{company}}
Includes whatever data is in the
{{company}} code.
^contact
{{contact}}
Includes whatever data is in the
{{contact}} code.
^covertext n
{{covertext}}
Text specified by the {{covertext}}
and {{endcovertext}} commands
in the document data.
See ”FCL Commands” on page 165.
Word-wrapping cover sheet note text
{{endcovertext}}
By default, text entered in the notes field of a cover sheet will wrap
at 70 characters. Use the steps below to customize this setting.
Multiple blocks of text can be
used on a single cover sheet.
Specify the index number of the
text block. Valid index numbers
are 0-9, and the index number is
not optional. If only a single text
block is to be used on a cover
sheet, use 0 as the index number.
1. On the RightFax server, open the Windows registry and browse
to HKLM\Software\RightFax\Production.
2. Create a new DWORD value called
CoverSheetWordWrapMax.
3. Edit this value to contain a decimal number that represents the
maximum number of characters per line. When finished, click
OK.
Chapter 6
Creating and Attaching Cover Sheets and Other Files
51
OpenText RightFax 10.5 Integration Module Guide
Table 6a Cover Sheet Keywords and FCL Equivalents (Continued)
Table 6a Cover Sheet Keywords and FCL Equivalents (Continued)
Keyword
FCL equivalent Notes
Keyword
FCL equivalent Notes
^csi
{{csi}}
^from
{{email}}
If no caller subscriber information
(csi) is specified, the ^csi
variable will use the default fax
number set in the RightFax
Integration Module
Configuration program. Changes
are global; you can change CSI
on a per-document basis, but not
on the banner line.
^date
{{date}}
If no {{date}} is specified, the
current date will be used.
^dept
{{dept}}
Includes whatever data is in the
{{dept}} code.
^docnum
N/A
The document number assigned
by the RightFax RightFax
Integration Module.
^email
^emailcc
^empid
^fax
^file
{{email}}
{{email}}
{{empid}}
{{fax}}
{{type file}}
This command can be used if you
have licensed the InternetLink
Module. The recipient’s e-mail
address.
{{from}}
^localfax
N/A
The {{from}} command can be
used if you have licensed the
InternetLink Module.
Replaced with the local fax
number set in the RightFax
Integration Module
Configuration program.
^oecopies
{{onerror print}}
When {{onerror}} action is set to
print, ^oecopies is replaced with
the number of copies to be
printed.
^onerror
{{onerror}}
Replaced with the {{onerror}}
action specified for this
document, or if none is specified,
the default set in the RightFax
Integration Module
Configuration program.
^onsuccess
{{onsuccess}}
This command can be used if you
have licensed the InternetLink
Module. The e-mail address for
an additional recipient.
The {{onsuccess}} action
specified for this document. If
none is specified, the default set
in the RightFax Integration
Module Configuration program
will be used.
^owner
{{owner}}
Includes whatever data is in the
{{empid}} code.
Includes whatever data is in the
{{owner}} code.
^pages
N/A
The number of attachments in the
fax.
Includes whatever data is in the
{{fax}} field. This uses the same
information as the ^phone
keyword.
The file name for {{type file}}
documents.
The number of pages in an
attached file are not counted.
^phone
{{fax}}
Includes whatever data is in the
{{fax}} code. This uses the same
information as the ^fax keyword.
52
Table 6a Cover Sheet Keywords and FCL Equivalents (Continued)
Keyword
FCL equivalent Notes
^quality
{{quality}}
^rti
{{rti}}
^subject
{{comment}}
{{subject}}
^termid
{{termid}}
^time
{{time}}
^tranid
{{tranid}}
^type
{{type}}
^unique_id
{{unique_id}}
^user1
{{user1}}
^user2
{{user2}}
^user3
{{user3}}
^voice
{{voice}}
^winsecid
{{winsecid}}
If no {{rti}} string is specified, the
^rti variable will use the default
set in the RightFax Integration
Module Configuration program.
The {{subject}} command can be
used if you have licensed the
InternetLink Module.
If no {{time}} is specified, the
current time will be used.
See ”FCL Commands” on page 165.
Table 6b Cover Sheet FCL Commands
Command
Description
{{comment}}
Stores any user-defined message specific to the
document.
This command is sometimes also used to populate
variables in notifications.
{{company}}
This command is sometimes also used to populate
variables in notifications.
{{contact}}
Maps to the unique_id field in the
RightFax database.
The following table lists the commands and gives a brief
explanation. For a comparison of the commands listed here and the
keywords that you can use in cover sheets, see “Table 6a: Cover
Sheet Keywords and FCL Equivalents”.
Associates called-subscriber information (CSI) with
the document. This is usually the general fax
number for the enterprise.
You can set a default CSI in the RightFax
Integration Module Configuration program. See
”Setting Defaults for FCL Documents” on
page 126.
{{email}}
Stores the return sender’s return e-mail address of
the document. This command is sometimes also
used to populate variables in notifications.
{{empid}}
Specifies the employee ID of the fax owner.
This command is most often used to populated
variables in notifications, but is sometimes also
used with cover sheets.
FCL for cover sheets
Several informational FCL commands are designed specifically for
cover sheets.
Stores the contact name for the current document.
This command is sometimes also used to populate
variables in notifications.
{{CSI}}
The RightFax user ID of the
originator of the fax.
Stores a company name for the current document.
{{owner}}
Specifies the document owner’s name.
This command is sometimes also used to populate
variables in notifications.
Chapter 6
Creating and Attaching Cover Sheets and Other Files
53
OpenText RightFax 10.5 Integration Module Guide
Table 6b Cover Sheet FCL Commands (Continued)
Table 6b Cover Sheet FCL Commands (Continued)
Command
Description
Command
Description
{{replyto}}
Specifies a recipient for a notification. You can
request that an HTTP post be sent back to the host
as a notification when you use the RightFax XML
Interface. ReplyTo is the field in the submit post that
the XML Interface populates to determine where to
send the notification.
{{user1}},
{{user2}},
{{user3}}
Include one or more of these commands in the host
document so that the originator (person, group,
etc.) of the document can be identified and
correctly sent the notification.
{{userID}}
Identifies the creator of this document.
{{RTI}}
Specifies the remote terminal identification from
which the document originated. This is typically the
sending company’s name.
You can set a default name for the sending
company in the RightFax Integration Module
Configuration program. See ”Setting Defaults for
FCL Documents” on page 126.
{{termID}}
Sets the identification of the transaction that
produced the document.
This command is most often used to populated
variables in notifications, but is sometimes also
used with cover sheets.
{{uniqueID}}
{{voice}}
Sets the voice number to be associated with the
document.
This command is most often used to populated
variables in notifications, but is sometimes also
used with cover sheets.
Specifies the terminal identification from which the
document originated.
This command is most often used to populated
variables in notifications, but is sometimes also
used with cover sheets.
{{tranID}}
This command is most often used to populated
variables in notifications, but is sometimes also
used with cover sheets.
Sets an identification number for each destination
(fax number) within the document.
This command is used most often for tracking. The
RightFax Integration Module will generate a
UniqueID unless you specify one in your FCL. Then,
you can track the document in FaxUtil based on the
UniqueID.
Secondarily, this command is sometimes used in
cover sheets and with notifications.
Attaching a Cover Sheet to a Document with FCL
Use the {{cover}} command to attach a production cover sheet to a
document.
{{begin}}
{{fax 503-555-9023}}
{{cover FaxCoverPage.cov}}
Host data.
{{end}}
In this example, the RightFax Integration Module would retrieve the
file called FaxCoverPage.cov from the RightFax\Production\Covers
folder and attach it as the first page of the document.
Note In this example, the {{cover FaxCoverPage.cov}} command could
also be {{cover FaxCoverPage}} (without the .cov extension). The .cov
extension is assumed when a cover sheet is identified as part of a
{{cover}} command. Thus, you can insert it or omit it. Accordingly, if you
create and attempt to attach a production cover sheet that is not saved
with a .cov extension, then errors will occur.
54
RightFax Cover Sheet Logic
See ”FCL Commands” on page 165.
Because you can set a default cover sheet in the RightFax
Integration Module Configuration program, set a default cover
sheet for a RightFax user, and specify a cover sheet with the
{{cover}} FCL command, the following table will help clarify which
cover sheet will be used in different scenarios.
Table 6c Cover Sheet Logic
With these configuration settings
This cover sheet will be used
RightFax Integration
RightFax user default Module default cover
sheet
cover sheet
FCL in document
None set
“none”
“cover” (.pcl, .doc, or .cov)
None set
“none”
“none”
X
None set
“none”
“rfdefault”
X
None set
“none”
No command
X
None set
Cover.cov
“cover” (.pcl, .doc, or .cov)
None set
Cover.cov
“none”
X
None set
Cover.cov
“rfdefault”
X
None set
Cover.cov
No command
Cover.pcl
“none”
“cover” (.pcl, .doc, or .cov)
Cover.pcl
“none”
“none”
Cover.pcl
“none”
“rfdefault”
Cover.pcl
“none”
No command
Cover.pcl
Cover.cov
“cover” (.pcl, .doc, or .cov)
Cover.pcl
Cover.cov
“none”
Cover.pcl
Cover.cov
“rfdefault”
Cover.pcl
Cover.cov
No command
Cover.pcl
“rfdefault”
“cover” (.pcl, .doc, or .cov)
The specified file
name
The user default
The Integ.
Module default
No cover
sheet
X
X
X
X
X
X
X
X
X
X
X
X
Chapter 6
Creating and Attaching Cover Sheets and Other Files
55
OpenText RightFax 10.5 Integration Module Guide
Table 6c Cover Sheet Logic (Continued)
With these configuration settings
This cover sheet will be used
RightFax Integration
RightFax user default Module default cover
sheet
cover sheet
FCL in document
Cover.pcl
“rfdefault”
“none”
Cover.pcl
“rfdefault”
“rfdefault”
X
Cover.pcl
“rfdefault”
No command
X
Example Cover Sheet and Document
Cover sheet FCL and text
{{place logo.tif 5 1}}{{lm 0.5}}{{moveto .5 1.5}}Palatine Hill
Association
0615 S.W. Palatine Hill Road
Portland, Oregon 97219
{{lm 1.0}}{{moveto 1 3.5}}FAX TRANSMISSION
Date:
Page:
^date
1 of ^pages
To:
Company:
Date:
^contact
^company
^date
From:
Company:
Fax:
^owner
Palatine Hill Association
^csi
Subject:
^comment
Notes:
^covertext 0
{{end}}
The specified file
name
The user default
The Integ.
Module default
No cover
sheet
X
Host document data that contains FCL
{{begin}}{{cover faxcover.cov}}{{owner Adam Guenther}}
{{comment Purchase Order}}{{covertext 0}}
Let me know if you have questions!{{endcovertext}}
{{moveto 0 .5}}
Purchase Order
{{linewidth 4}}{{lineto 8.5,y}}{{lm 1.0}}
ITEM PRICE QUANTITY
11023 $21.00
2
TOTAL
$42.00
======
$42.00
{{company Troutdale Imports}}{{contact Jack Dundee}}
{{fax 555-465-0987}}
{{end}}
56
Finished cover sheet and document
Figure 6.3 The Cover Sheet is Attached as the First Page of the Document
Attaching Other Types of Files
The options described here are for files that are converted to fax
format (TIF images) before being attached and sent. If you want to
attach files in their native format, use the RightFax InternetLink
Module, described in Chapter 12, ”Creating FCL Documents with
InternetLink Commands”.
To attach a file to a document, use the {{attach}} command. You
can attach multiple documents by inserting multiple {{attach}}
commands. The {{attach}} command ends the page, so the
attachment always begins on its own page. The {{attach}}
command cannot be used in {{type email}} documents.
To attach a library document, use the {{libdoc}} command.
{{Libdoc}} has the same functionality as {{attach}}. For information
on library documents, see the RightFax Administrator’s Guide.
Converting attached files
Attached files are converted to fax format (.tif) in one of two ways:
server-side application (SSA) file conversions and INSO
conversions.
To convert a file to fax format with SSA, the source application that
created the attachment must be SSA-compatible (see the RightFax
Administrator’s Guide for a list of SSA-compatible applications)
and the source application must be installed on the RightFax server
computer.
INSO conversions are used for files that cannot be converted with
SSA. The RightFax software attempts SSA conversions for all
attachments. If the attachment’s file type is not SSA-compatible, or
if the attachment’s source application is not installed on the
RightFax server computer, then an INSO conversion is used.
For more information on file conversions, see the RightFax
Administrator’s Guide.
Chapter 6
Creating and Attaching Cover Sheets and Other Files
57
OpenText RightFax 10.5 Integration Module Guide
Storing attachments
Figure 6.4 Attaching the File Named AugustInvoice.doc
For every attached file, you must either provide a path to the file in
the {{attach}} command, or save the file in the
RightFax\Production\Forms folder. If you provide a path, it should
be a full path. If you provide a path that is not a full path, then it
must be relative to RightFax\Production\Forms.
{{begin}}
{{fax 503-555-0016}}
Body of the main documen
{{attach AugustInvoice.doc
More of the main documen
{{end}}
Example The following example shows an FCL document that
would attach a file called AugustInvoice.doc. The
attachment would be converted to fax format, attached
to the body of the main document at the start of a new
page, and sent to (503) 555-0016.
For this example document to function properly,
Microsoft Word must be installed on the RightFax server
computer (to use SSA to convert AugustInvoice.doc)
and AugustInvoice.doc must already be saved in the
RightFax\Production\Forms folder.
See ”FCL Commands” on page 165..
58
Chapter 7
Defining Fax Page Appearance
A series of FCL commands can be used to change the way a
document looks. You can draw shapes, embed existing graphics,
embed signatures, change margins and tabs, select specific fonts,
or define page orientation.
Table 7a FCL Commands that Create Shapes (Continued)
Command
Description
{{FillBox}}
Same as the {{box}} command. The box can be filled
with white or black. This is frequently used to hide
information that cannot be removed easily from the
data stream coming from host application. You
cannot place text inside the box.
{{Line}}
Draws a line whose starting and ending points are
specified by coordinates that you supply.
{{LineTo}}
Draws a line whose starting point is the current
cursor location and whose ending point is specified
by coordinates that you supply.
{{LineWidth}}
Lets you specify the width, in points, of the lines that
you draw with other commands.
{{RBox}}
Same as {{box}}, but the coordinates for size and
location are established relative to the current cursor
location. In contrast, the coordinates for the {{box}}
command are measured from the upper-left corner
of the document.
{{RFillBox}}
Same as {{fillbox}}, but the coordinates for size and
location are established relative to the current cursor
location. In contrast, the coordinates for {{fillbox}}
are measured from the upper-left corner of the
document.
Creating and configuring these shapes can supplement or replace
background forms or graphics.
You can also change the appearance of a document with
background forms. See ”Creating and Linking Background Forms”
on page 132.
Drawing Shapes
The following table lists the FCL commands for drawing shapes
and provides a brief description. See ”FCL Commands” on
page 165.
Table 7a FCL Commands that Create Shapes
Command
Description
{{Box}}
Draws a box whose size and location at specified
coordinates. You can also place text inside the box.
{{EndPoly}}
Ends a polygon that is started with the {{startpoly}}
command.
59
OpenText RightFax 10.5 Integration Module Guide
Table 7a FCL Commands that Create Shapes (Continued)
Command
Description
{{RLine}}
Same as {{line}}, but the coordinates that you supply
to determine length and location are established
relative to the current cursor location. In contrast,
the coordinates you give with {{line}} are measured
from the upper-left corner of the document.
{{RLineTo}}
Same as {{lineto}}, but the coordinates that you
supply to determine length and location are
established relative to the current cursor location. In
contrast, the coordinates you give with {{line}} are
measured from the upper-left corner of the
document.
Box
The box command creates a box at specified coordinates and
places text in it. You supply coordinates for the upper-left and
lower-right corners. In the following example, (2, 2) is the
coordinate for the upper-left corner of the box, and (4, 4) is the
coordinate for the lower-right corner of the box.
Figure 7.1 Box Command
{{begin}}
{{fax 503-555-1234}}
This is a test document.
{{box (2, 2) (4, 4) “Example”}}
{{end}}
{{RStartPoly}} Same as {{startpoly}}, but the coordinates that you
supply to determine the starting point are
established relative to the current cursor location. In
contrast, the coordinates you give with {{startpoly}}
are measured from the upper-left corner of the
document.
{{StartPoly}}
Starts a polygon at a point that you specify by
supplying coordinates. The polygon is completed
with a series of {{lineto}} commands and finished
with the {{endpoly}} command.
Using the Most Common Commands That Create Shapes
This section lists the most common commands and provides
examples for creating shapes, such as a line or a box, with FCL.
Example FCL code and finished documents are provided. The
sample documents have horizontal and vertical numbers at the top
and left margins to indicate the grid for the x- and y-coordinates for
the placement of the shapes. The numbers will not appear in the
finished document.
Fillbox
The fillbox command is the same as {{box}}, except that you can fill
it with black or white. You might use a white-filled box to cover part
of a document that should not appear in the finished document.
60
Figure 7.2 Fillbox Command
Figure 7.3 Line Command
{{begin}}
{{fax 503-555-1234}}
This is a test document.
{{line (1, 1) (5, 1)}}
{{line (3, 1) (3, 3)}}
{{line (2.5, 3) (8, 3)}}
{{end}}
{{begin}}
{{fax 503-555-1234}}
This is a test document.
{{fillbox (2, 2) (4, 4) black}}
{{end}}
Line
The line command draws a line between specified coordinates. The
following example shows three {{line}} commands. In the first, (1, 1)
are the x- and y-coordinates for the beginning of the line, and (5, 1)
are the coordinates for the end of the line.
Lineto
The lineto command draws a line between the current cursor
location and specified coordinates. The current cursor location is
often where the FCL command appears in a document but not
always. The two examples in this section show different options for
this command.
The first example begins the line at the current location when the
RightFax Integration Module finds the {{lineto}} command. In this
case, the location is immediately after “This is a”. The line ends at
the coordinates (4, 4). Then, the remainder of the text appears.
Chapter 7
Defining Fax Page Appearance
61
OpenText RightFax 10.5 Integration Module Guide
Figure 7.4 Lineto Command
Figure 7.5 Lineto Command
{{begin}}
{{fax 503-555-1234}}
This is a {{lineto (4, 4)}}test document
{{end}}
The second example starts the line at the current location when the
RightFax Integration Module finds the {{lineto}} command. In this
case, the location is immediately after “This is a”. The line ends at
the coordinates (4, y), which is 4 units to the right of the starting
point, and n units below the starting point (where n is the current
position; thus, the position does not move down). Then, the
remainder of the text appears.
{{begin}}
{{fax 503-555-1234}}
This is a {{lineto (4, n)}}test
document.
{{end}}
Rbox
The rbox command draws a box with a starting point that is relative
to the current cursor location. In contrast, the coordinates you
specify with the {{box}} command are measured from the upper-left
corner of the document.
The current cursor location is often where the FCL command
appears in a document but not always. The two examples in this
section show different options for this command.
The first example starts the box at (2, 2) from the current location
when the RightFax Integration Module finds the {{rbox}} command.
In this case, the location is immediately after “This is a”. The box
ends at the coordinates (3, 3) from the current location. Then, the
remainder of the text appears.
62
The following example does not show grid numbers, because the
position of the box is relative to a point that can move from
document to document. The arrows in the example document
indicate that the box starts (2, 2) from the current cursor location.
These arrows would not appear in the finished document.
Figure 7.7 Rbox Command
Figure 7.6 Rbox Command
{{begin}}
{{fax 503-555-1234}}
This is a test document.
{{moveto (1,8)}}
{{rbox (2,2) (3,3)}}
{{end}}
{{begin}}
{{fax 503-555-1234}}
This is a {{rbox (2,2) (3,3)}}test
document.
{{end}}
Embedding Signatures with FCL
Creating signatures
The next example starts the box at (2, 2) from the current location
when the RightFax Integration Module finds the {{rbox}} command.
In this case, the location has been changed with the {{moveto}}
command to (1, 8). Thus, the box starts (2, 2) from (1, 8), or (3, 10).
The box ends at (3, 3) from (1, 8), or (4, 11).
You must create any signature files and save them as Class F TIF
images. The Integration Module does not provide a method for
creating these files. The most common method is to scan a
signature. Regardless of method, the signature must be saved as a
Class F TIF file.
This example shows grid numbers for the (1, 8) position. The
arrows in the example document indicate that the box starts (2, 2)
from the current cursor location. These arrows would not appear in
the finished document.
Chapter 7
Defining Fax Page Appearance
63
OpenText RightFax 10.5 Integration Module Guide
Storing signatures
For every embedded signature file, you must either provide a path
to the file in the {{signature}} command, or save the file in the
RightFax\Production\Forms folder. If you provide a path, it should
be a full path. If you provide a path that is not a full path, then it
must be relative to RightFax\Production\Forms.
Embedding a signature
1. Insert the {{signature}} command into the FCL to define the
signature file.
2. Insert {{sign}}, {{signed}}, or {{@}} (they are identical) at the
Example One-hundred sales people need to send a letter to
10,000 customers—each sales person must send the
letter to 100 customers. The {{signature}} command can
identify each sales person’s signature that will appear at
the bottom of his or her letters.
See ”FCL Commands” on page 165.
When you are able to manipulate the body of an FCL document,
embedding a signature file might be easier when you use one of
the {{place}} commands, which requires only one FCL command
instead of two and offers more exact placement options. For more
information, see “Embedding Graphics with FCL” on page 64.
point where you want the signature to appear.
Example In the following example, the {{signature}} command
establishes that DoctorRobertCribbs.tif will be the
signature used in this document. The {{@}} command
places this signature below the text that forms the body
of the document, at the current cursor location.
Embedding Graphics with FCL
To embed graphics in the body of a document, use one or more of
the {{place}} commands.
z
For this example document to function properly,
DoctorRobertCribbs.tif must already be saved as a
Class F TIF in the RightFax\Production\Forms folder.
{{begin}}{{signature DoctorRobertCribbs.tif}}
{{fax 503-555-0016}}
Body of the document to be sent.
Sincerely,
{{@}}
{{end}}
Because it identifies, rather than places, a signature file,
the {{signature}} command is often useful in situations
where you can manipulate the header of an FCL
document, but not the body.
z
z
z
{{place}} positions the specified Class F TIF image. You can
specify a full path to the graphic file. If you do not specify a path,
then the default is RightFax\Production\Forms. The upper-left
corner of the graphic is placed at the current cursor location,
unless you specify x- and y-coordinates.
{{placeall}} places the image on the current and all subsequent
FCL pages (but not on file attachments).
{{placelast}} places the image on the last page only. You can use
multiple {{placelast}} commands to embed multiple images on
the last page (such as multiple signatures, something you cannot
do with the signature commands).
{{placexy}} specifies the location on the page of the images
defined in subsequent {{place}} commands. You can specify
horizontal values of left, center, and right, and vertical values of
top, center, and bottom. For example, {{placexy center center}}
would align the horizontal and vertical centers of the image at the
location specified in a subsequent {{place}} command.
64
Embedding a signature file (page 63) is essentially the same as
embedding any other graphic. The signature commands have no
functional differences from the place commands—both let you
embed a graphic file in the body of a document. However, the
{{place}} commands require less programming and let you locate
the embedded graphic more precisely in the document.
Setting Margins
You can set margins for individual documents or default margins
that apply to all documents. Three FCL commands control margins:
z
z
z
{{bm}} bottom margin
{{lm}} left margin
{{tm}} top margin
To set margins for a single document, insert one or more of the
margin commands into the FCL document.
To set default margins for all documents, insert one or more of the
margin commands into a global include file. See ”Reusing FCL
Commands Across Many Documents” on page 45. Any document
that contains a margin command will not use the defaults
established in the global include file.
Example You use a global include file to establish one-inch
margins for all documents. Later, you need to send a
batch of 100 documents with two-inch margins. To
accomplish this, you include the relevant margin
commands in the FCL for those 100 documents. The
100 documents are processed with two-inch margins
and all others use the default margins.
Setting margins for individual documents
To set margins for a document, insert the relevant margin
commands into the FCL document.
The following example shows an FCL document with left, top, and
bottom margins that are all one unit.
{{begin}}
{{lm 1.0}}
{{tm 1.0}}
{{bm 1.0}}
{{fax 503-555-4489}}
Body of the document to be sent.
{{end}}
The number you insert in the margin command reflects current
units, so 1.0 could mean one inch, one centimeter, one point, or
one pixel. This depends on the default units you have established.
You establish defaults, including default units, with the Integration
Module Configuration program or by inserting certain FCL
commands into a global include file. See ”Setting Defaults for FCL
Documents” on page 126.
See ”FCL Commands” on page 165.
Setting default margins for all documents
To set default margins for all documents, insert the relevant margin
commands into the global include file called Global.beg.
The following example shows default margin information. By
inserting these commands into the Global.beg include file, every
document that the Integration Module processes will have one-inch
margins.
{{lm 1.0}}
{{tm 1.0}}
{{bm 1.0}}
Default margins are zero until you establish a different default value.
See ”Reusing FCL Commands Across Many Documents” on
page 45.
See ”FCL Commands” on page 165.
Chapter 7
Defining Fax Page Appearance
65
OpenText RightFax 10.5 Integration Module Guide
Starting a New Page With the Same Margins as the
Previous Page
Use the {{ff}} (form feed) command to begin a new page with the
same left and top margins as the previous page. Use this command
in individual documents only, not in a global include file to create a
default setting.
To start a new page, insert the {{ff}} command into the FCL.
Example The following example shows that a new page will start
between the words “document” and “to.” The new page
will retain the existing one-unit margins and not revert to
the default margins.
{{begin}}
{{lm 1.0}}
{{tm 1.0}}
{{bm 1.0}}
{{fax 503-555-4489}}
Body of the document {{ff}} to be sent.
{{end}}
Setting Tabs with FCL
You can set tabs for individual documents or as defaults that will
govern all documents. Three FCL commands control tabs:
z
z
z
{{cleartabs}} removes all tab stops from a document.
{{settab}} creates a tab stop that functions globally throughout a
document.
{{tab}} creates a single tab stop; can be generic (based on a
preset tab stop) or can identify one of the tab stops created with
the {{settab}} command.
To set tabs for a single document requires that you insert one or
more of the three tab commands into the FCL.
To set default tabs for all documents, insert one or more instance of
the {{settab}} command into a global include file. See ”Reusing
FCL Commands Across Many Documents” on page 45. Any
document that contains a tab command will not use the defaults
established in the global include file.
Example You use a global include file to establish tab stops at
one inch, two inches, and three inches for all of the
documents. Later, you need to send a batch of 100
documents with a half-inch tab stop. To accomplish this,
you include the relevant tab commands in the FCL for
those 100 documents. The 100 documents include a
half-inch tab stop, and all others revert back to the
default.
Setting tabs for individual documents
To set tabs for a document, insert the relevant commands into the
FCL.
Example The following example shows an FCL document with the
{{settab}} command creating two different tab stops.
The first is labelled 0 and sets a tab stop 1.5 units from
the left margin. The second is labelled 1 and sets a tab
stop 2.5 units from the left margin. The two {{tab}}
commands identify tab stops 0 and 1, and move the
enclosed text accordingly.
66
Selecting and Configuring Fonts
Figure 7.8 Settab Command
{{begin}}
{{fax 503-555-4489}}
{{settab 0 1.5 L}}
{{settab 1 2.5 L}}
Paragraph 1 of the document
body.
{{tab 0 Paragraph 2 of the
document body.}}
{{tab 1 Paragraph 3 of the
document body.}}
{{end}}
All of the installed fonts are bitmap display format (BDF) fonts.
BDF fonts are not easily resized or manipulated. However, the
RightFax Integration Module supports for vector fonts (such as
TrueType fonts), which can be manipulated.
Fonts can be either proportional or non-proportional. In a
proportional font family, the characters vary in width. For example,
the letter I is narrower than the letter W. In a non-proportional font
family, all the letters are the same width. This is apparent when text
must align in vertical columns.
When it is necessary for letter alignment, use a non-proportional
font. The following installed fonts are non-proportional:
z
z
z
z
Block
Courier
Computer Modern Teletype
Lucida Typewriter
The default font is Courier bold 12-point (courb12).
Setting default tabs for all documents
1. Insert any {{settab}} command into the into the global include
file called Global.beg.
2. Insert corresponding {{tab}} commands into the FCL for any
host document.
The host document will use the tab stops described in the
corresponding {{settab}} command.
See ”Reusing FCL Commands Across Many Documents” on
page 45. See ”FCL Commands” on page 165.
TrueType Fonts
The RightFax Integration Module can use any TrueType font that is
supported by Microsoft Windows. TrueType font support provides
flexible, customized manipulation of characters. This includes:
z
z
z
z
z
z
Font size
Leading (vertical space)
Pitch (horizontal space)
Weight
Strikethrough
Italics
See ”FCL Commands” on page 165.
Chapter 7
Defining Fax Page Appearance
67
OpenText RightFax 10.5 Integration Module Guide
Support for Other Fonts
The RightFax Integration Module also supports any fonts that are
supported by Microsoft Windows.
The RightFax Integration Module software renders Windows fonts
differently than the installed or TrueType fonts, and the clarity of
these fonts might suffer, depending on the font. Use the installed
fonts or TrueType fonts for better font legibility.
The RightFax Integration Module does not support double-byte
fonts (such as fonts used for Chinese and Japanese).
Selecting Fonts
You can establish a font for an individual document or a default font
for all documents.
To set the font for a single document:
z
z
Use the {{font}} FCL command in the FCL document.
Use the {{font}} command in a standard include file. See
”Reusing FCL Commands Across Many Documents” on
page 45.
To change the default font for all documents, use the {{font}}
command in a global include file. See ”Reusing FCL Commands
Across Many Documents” on page 45.
Documents that contains a font command will not use the defaults
established in the global include file. The default font for the
RightFax Integration Module is Courier bold 12-point (courb12).
Selecting fonts for individual documents
To set the font for a document, use the {{font}} FCL command in
the FCL document.
See ”FCL Commands” on page 165.
Example The following example shows an FCL document with the
font Times New Roman, 24-point, extra-bold, and italic.
The {{font}} command controls all text until another
{{font}} command or the end of the document.
{{begin}}
{{font “times new roman” size=24 extrabold italic}}
{{fax 503-555-4489}}
Body of the document to be sent.
{{end}}
Selecting a default font for all documents
To change the default font for all documents, use the {{font}}
command in the global include file called Global.beg.
Example The following example shows an FCL command that will
establish a default font. By inserting this command into
the Global.beg include file, every document that the
RightFax Integration Module processes will use the font
Times New Roman, 12-point.
{{font “times new roman” size=12}}
See ”Reusing FCL Commands Across Many Documents” on
page 45. See ”FCL Commands” on page 165.
Changing the Appearance of Fonts
You can change the appearance of fonts, such as the weight or
pitch for TrueType and Windows fonts with the {{font}} command.
For the installed BDF fonts, you can configure only the pitch and
leading.
You can underline any font with the {{underline}} command or draw
a line through any text with using the strikeout option within the
{{font}} command.
68
See ”FCL Commands” on page 165.
Example The following example shows the FCL commands that
would change the appearance of the same font and
what the finished document would look like.
Figure 7.9 Changing the Look of Fonts with FCL
Body text, paragraph 1.
Body text, paragraph 2.
Body text, paragraph 3.
Body text in Lucida Sans,
12-point, italic. This is an
installed font.
{{begin}}
{{fax 503-555-8823}}
{{font “times new roman” size=12
pitch=15 extrabold italic strikeout}}
Body text, paragraph 1.
{{underline on}}
Body text, paragraph 2.
{{underline off}}
{{font “times new roman” size=12
regular}}
Body text, paragraph 3.
{{font luis12}}
Body text in Lucida Sans, 12-point,
italic. This is an installed font.
{{end}}
Setting Page Orientation
To determine the page orientation for individual documents or the
default for all documents, use the {{orient}} FCL command.
To set the default orientation for all documents, insert the {{orient}}
command in a global include file. See ”Reusing FCL Commands
Across Many Documents” on page 45.
Individual documents that contain the {{orient}} command will
override the default in the global include file.
Example You use a global include file to establish landscape
orientation for all documents (overriding the Integration
Module default of portrait orientation). Later, you need to
send a batch of 100 documents that must have portrait
orientation. To accomplish this, you include the {{orient
portrait}} command in the FCL for those 100
documents. The 100 documents are processed with
portrait orientation, and all others revert back to the
default.
You can change orientation multiple times in a document, so that,
for example, the odd pages are portrait and the even pages
landscape. You can do this with a new {{orient}} command at the
beginning of each page (you can start a new page with the {{ff}}
command.) See ”FCL Commands” on page 165.
Setting page orientation for individual documents
To set orientation for a document, insert either {{orient portrait}} or
{{orient landscape}} into the FCL document.
The following example shows an FCL document with portrait
orientation.
{{begin}}
{{orient portrait}}
{{fax 503-555-4489}}
Body of the document to be sent.
{{end}}
See ”FCL Commands” on page 165.
Setting default orientation for all documents
The default page orientation for all documents is portrait. To
change this default, insert the {{orient landscape}} command into
the global include file called Global.beg.
Chapter 7
Defining Fax Page Appearance
69
OpenText RightFax 10.5 Integration Module Guide
See ”Reusing FCL Commands Across Many Documents” on
page 45. See ”FCL Commands” on page 165.
Setting Fax Image Quality
You can set the resolution of the fax image to fine or standard.
z
z
Standard resolution is 204 x 98 dots per inch (dpi).
Fine resolution is 204 x 196 dpi.
You can set image quality for individual documents or as defaults
that will govern all documents.
To set image quality for a single document, insert the {{quality}}
command into the FCL document.
See ”Reusing FCL Commands Across Many Documents” on
page 45.
Any document that contains the {{quality}} command will override
the default established with the Integration Module Configuration
program.
Example You use the Integration Module Configuration program
to establish standard image quality for all documents.
Later, you need to send a batch of 100 documents that
must have fine quality. To accomplish this, you include
the {{quality fine}} command in the FCL for those 100
documents. The 100 documents are processed with fine
quality, and all others use the default.
Setting image quality for individual documents
To set image quality for a document, insert either {{quality fine}} or
{{quality standard}} into the FCL.
The following example shows an FCL document with fine quality.
{{begin}}
{{quality fine}}
{{fax 503-555-4489}}
Body of the document to be sent.
{{end}}
See ”Reusing FCL Commands Across Many Documents” on
page 45.
70
Chapter 8
Document Transmission and Notifications
Scheduling Document Transmission
You can use FCL commands to schedule when the RightFax
Integration Module sends documents. Unless you specify
otherwise with one of these commands, the RightFax Integration
Module sends documents when it receives them from the host
application.
The following table lists the scheduling commands and gives a brief
description.
See ”FCL Commands” on page 165.
Table 8a The Scheduling Commands
Command
Description
{{approval}}
Holds a document in the FaxUtil mailbox until it is
approved.
{{batch}}
Holds a document so that it can be sent with other
documents in a batch.
{{date}}
Specifies a future date to send a document.
Combine this command with {{time}}.
{{delay}}
Delays sending by a specified number of minutes..
{{preview}}
Holds the document for preview in the FaxUtil
mailbox.
Table 8a The Scheduling Commands (Continued)
Command
Description
{{priority}}
Specifies a sending status of high, medium , or low
priority for a document. When high priority
documents exist, low and medium priority
documents are held so that the high priority
document can be sent. The default is low priority.
Priority only has an effect on sending time when
certain variables, such as document traffic or
processing time (for complex documents with
many graphics, attachments, etc.), are sufficiently
high. “Sufficiently high” depends on multiple
variables also, such as the number of RightFax
servers or channels in the system.
The {{batch}} command is a common variable that
affects the sequence in which documents are sent,
as does the priority that you establish for {{batch}}
documents.
For example, if you batch several documents and
assign them all high priority, they will not be sent
until the batch is complete. In this instance, low
priority documents may be sent before the high
priority batch documents are sent.
71
OpenText RightFax 10.5 Integration Module Guide
Table 8a The Scheduling Commands (Continued)
Command
Description
{{time}}
Specifies a future time to send a document.
Combine this command with {{date}} to send a
document at a particular time on a future day.
The {{time}} command only considers the time
remaining in the same day. Thus, a document is
sent immediately if the time specified in the
{{time}} command is in the past.
For example, if you send a document to the
RightFax Integration Module at 21:00 (9:00 p.m.)
and you insert the command {{time 20:45}}, the
document will be sent immediately because 20:45
(8:45 p.m.) of the current day is in the past.
{{UTC}}
Specifies a future date and time to send a
document in universal coordinated time.
Creating Notification Messages with FCL
You have multiple options for configuring notification
messages—their content, how the Integration Module sends them,
and how they are received.
Notification messages can describe whether or not a document
was transmitted, any transmission errors, the date and time of
transmission, the owner of the document, and more. Another form
of notification is to print or fax a copy of the document to another
recipient such as a system administrator. See ”Setting Up Actions
on Document Transmission” on page 94. To send notification
messages, the FCL command {{notifyhost}} must be included in
documents sent from the host application or added to the include
file that is linked to the documents.
When a document is received, generated, and transmitted from the
RightFax server, notification messages are generated by the
program Notify.exe in the Integration Module. The notification
messages are sent to the host application via “notification
channels” that you set up in the Integration Module.
Notification messages are not generated by the Integration Module
for incomplete faxes. Usually, these are faxes that are missing
information that is required for sending (such as the fax number).
You have the following options to set up notifications of faxes with
incomplete information:
z
z
Use Enterprise Fax Manager and FaxUtil to set up notifications
and to monitor the system for faxes with incomplete information
(described in the RightFax Administrator’s Guide).
Use the RightFax COM Module or the RightFax API to create
custom notifications. Refer to the RightFax COM Module Guide
for more information.
“Figure 8.1: The Notification Process” on page 73 illustrates the
FCL notification process using the following notification channel
command line:
FAX2MAPI -t $o -u “MS Exchange Settings” -f $$
72
Figure 8.1 The Notification Process
Creating notifications for FCL documents requires these basic
steps:
1. Create a template for the notification message (described on
page 73). Notification templates determine the format and
content of the notification message.
2. Create a notification channel (described on page 79). Use the
Integration Module Configuration program to create notification
channels, which include command lines that determine how the
Integration Module will send notifications.
3. Include the {{notifyhost}} FCL command in the document that is
sent from the host application to the Integration Module
(described on page 89). The {{notifyhost}} command specifies
the notification template for the message and the notification
channel to use.
Creating Notification Templates
The content and format of the notification message is defined in
text-based template file that you create. The template is a collection
of text and keyword variables which are replaced with data about
the sent document in the notification message.
Template file keywords are surrounded by carat symbols (^) and
contain an identifier and an optional field length. For example, the
keyword ^company^ would be replaced with the entire name of
the company to which the document was sent, regardless of the
number of characters. The keyword ^company 12^ would be
replaced with the first 12 characters only of the company name.
Chapter 8
Document Transmission and Notifications
73
OpenText RightFax 10.5 Integration Module Guide
For an example, refer to “Figure 8.1: The Notification Process” on
page 73. The template file in this example is a simple text
document that contains three keywords:
z
z
z
^docnum^ is replaced with the document number assigned by
the Integration Module.
^fax^ is replaced by the fax number of the person or company
receiving the document.
^retcode^ is replaced with the text of the code returned from the
fax board after transmission. This will either be the word
“success” or a specific error code.
To create and save a notification template
For example, ^altfax^ is replaced by the information included in the
{{altfax}} FCL command in the sent document. If an FCL document
contains {{altfax 503-555-3287}}, then 503-555-3287 will appear
where the ^altfax^ keyword appears in the notification template.
Table 8b Notification Keywords and FCL Equivalents
Keyword
FCL equivalent Description
^altfax^
{{altfax}}
The alternate fax number.
^billing^
{{billing}}
Billing code 1.
^billinfo2^
{{billing2}}
Billing code 2.
^comment^
{{comment}}
{{subject}}
The {{subject}} command can be
used if you have licensed the
InternetLink Module. The subject
appears in the subject field of the
e-mail message. If no subject
appears in the document, the default
subject is “Success Notification” or
“Error Notification.”
^company^
{{company}}
The destination company name.
^contact^
{{contact}}
The recipient name.
^csi^
{{csi}}
If no CSID (call subscriber ID) is
specified, the default set in the
RightFax Integration Module
Configuration program will be used.
^date^
{{date}}
If no date is specified, the default is
the date the fax was submitted.
^dept^
{{dept}}
The string defined as department.
^docnum^
N/A
The document number assigned by
the Integration Module.
^duration^
N/A
The duration of the fax call in
seconds.
1. Open Notepad or another text editing application that will
produce ASCII text files.
2. Enter the text and keywords of the notification message you
want to receive. For a description of all of the available
keywords for notification templates, see “Template file
keywords” on page 74.
3. Save the file with the extension .inc in the
RightFax\Production\Include folder. Make note of the file name
as you will need it later when you include the {{notifyhost}}
command in FCL documents from the host application.
Caution Do not save the template file with a .txt extension or any
extension other than .inc. The Integration Module will only recognize
files with this extension as notification templates.
Template file keywords
The following table lists the keywords you can add to notification
template files. The keywords are shown with FCL equivalents. FCL
commands in the sent document will populate the corresponding
keyword in the notification message.
74
Table 8b Notification Keywords and FCL Equivalents (Continued)
Table 8b Notification Keywords and FCL Equivalents (Continued)
Keyword
FCL equivalent Description
Keyword
^email^ or
^emailto^
{{email}}
{{to}}
^humantranstime^ N/A
The date and time the fax was
transmitted in human-readable
format.
^numretry^
N/A
The total number of fax attempts.
^owner^
{{owner}}
If no {{owner}} command appears in
the sent document, the default is the
RightFax user name of the owner of
the fax.
^ownerid^
{{owner}}
The RightFax use ID of the owner of
the fax
^pages^
N/A
Total pages of the document, not
including the cover sheet.
^pagessent^
N/A
Total pages that were successfully
transmitted.
^printer^
N/A
The name of the currently selected
printer.
^quality^
{{quality}}
The fax resolution.
^replyto^ or
^reply_to^
{{replyto}}
The reply-to name.
^retcode^
N/A
The text of the code returned from
the fax board after transmission. Will
be either “success” or a specific
error message.
^rti^
{{rti}}
If no RTI string appears in the sent
document, the default is the RTI set
in the Integration Module
Configuration program.
^statusstring^
N/A
Fax status as listed in FaxUtil (see the
RightFax Administrator’s Guide).
^emailfrom^
^emailcc^
^emailsubject^
{{from}}
{{cc}}
{{subject}}
These commands can be used if you
have licensed the RightFax
InternetLink Module. The keyword
^email^ is the recipient address.
With other notifications, ^email^ is
typically the e-mail address of the
originator of the document.
The e-mail address of the originator
of the document. If no e-mail address
appears in the document, the default
is [email protected] This
command can be used if you have
licensed the InternetLink Module.
The e-mail address where a copy of
the message should be sent. This
command can be used if you have
licensed the InternetLink Module.
The e-mail subject. This command
can be used if you have licensed the
InternetLink Module.
^empid^
{{empid}}
The recipient employee ID.
^fax^
{{fax}}
The recipient fax number. Same as
^phone^.
^phone^
{{fax}}
Same as ^fax^.
^faxcard^
N/A
The number of the fax board used for
transmission.
^faxstatus^
N/A
Numeric status code; see “The
^faxstatus^ and ^statustype^
keywords” on page 76.
FCL equivalent Description
Chapter 8
Document Transmission and Notifications
75
OpenText RightFax 10.5 Integration Module Guide
Table 8b Notification Keywords and FCL Equivalents (Continued)
Table 8b Notification Keywords and FCL Equivalents (Continued)
Keyword
FCL equivalent Description
Keyword
FCL equivalent Description
^statustype^
N/A
Numeric return code;
^voice^
{{voice}}
The recipient’s phone number.
“^Statustype^ Codes” on
page 77.
^winsecid^
{{winsecid}}
The RightFax user ID of the originator
of the fax.
^termid^
{{termid}}
The termination code.
^time^
{{time}}
If no time is specified, the default is
the time the fax was submitted.
^tranid^
{{tranid}}
The transmission ID generated by
the RightFax server.
^transtime^
N/A
The date and time that the fax was
transmitted. To specify the format for
the date and time, see “The
^transtime^ keyword” on page 77.
^type^
{{type}}
The ^faxstatus^ and ^statustype^ keywords
The ^faxstatus^ and ^statustype^ keywords describe the status
of the sent document in the notification message. The following
numeric codes will appear in the notification message.
Table 8c ^Faxstatus^ Codes
Code
Notes
0
Fax is not yet created.
The document transmission type (fax,
e-mail, certified, etc.). This keyword is
the method through which you can
be notified when a document that
should have been sent as a fax failed
and was sent as an e-mail or certified
e-mail instead. These options require
the InternetLink Module (for e-mail or
mime documents) or the
SecureDocs module (for certified
e-mail documents).
1
Fax needs cover sheet.
2
Fax needs conversion.
3
Fax needs to be sent.
4
Fax is in conversion.
5
Fax needs to be sent.
6
Fax is done sending or receiving.
7
Fax uses a manual fax cover sheet.
8
Fax is scheduled to be sent.
^unique_id^
{{unique_id}}
The unique ID for the fax assigned by
the RightFax server.
9
Fax is done sending or receiving. Errors were encountered.
Will not be retried.
^user1^
{{user1}}
User-defined data code 1.
10
Fax is a duplicate of another fax.
^user2^
{{user2}}
User-defined data code 2.
11
Error encountered. Fax will be retried.
^user3^
{{user3}}
User-defined data code 3.
12
^userid^
{{userid}}
RightFax user ID.
Sent or received fax needs user’s attention. Required data
may be missing.
13
Fax needs attachment.
76
Table 8c ^Faxstatus^ Codes
Code
Notes
The following table lists the variables that can be used with the
^transtime^ keyword.
14
Fax is held for preview.
Table 8f ^Transtime^ Variables
15
Fax is in OCR conversion.
Variable
Description
16
Fax is printing.
%a
Abbreviated weekday name.
17
Fax is queued for printing.
%A
Full weekday name.
18
Fax is queued for OCR conversion.
%b
Abbreviated month name.
19
Fax is being validated.
%B
Full month name.
20
Fax is held for approval.
%c
Date and time representation appropriate for
locale.
%d
Day of month as a digit (01-31).
%H
Hour in 24-hour format (00-23).
%I
Hour in 12-hour format (01-12).
%j
Day of year as a digit (001-366).
%m
Month as a digit (01-12).
%M
Minute as a digit (00-59)
%p
You can specify the format of the date and time. The following table
shows some possible formats for the transmit time 2:23 P.M. on
November 6, 2001.
Current locale’s A.M./P.M. indicator for 12-hour
clock.
%S
Second as a digit (00-59).
%T
Local TZD.
Table 8e Example ^Transtime^ Variables with Results
%U
Week of year as a digit, with Sunday as first day of
week (00-51). If ^transtime^ begins with %U, the
time displayed is UTC rather than local.
%w
Weekday as a digit (0-6; Sunday is 0).
%W
Week of year as decimal number, with Monday as
first day of week (00-51)
%x
Date representation for current locale
%X
Time representation for current locale.
Table 8d ^Statustype^ Codes
Code
Status
0
Fail
2
OK
The ^transtime^ keyword
The ^transtime^ keyword and variables provide the date and time
that the document was transmitted in the notification message.
Command and variable
Result
^transtime %m/%d/%y^
11/06/01
^transtime %H:%M^
14:23
^transtime %H%M%m%d%Y^
14:2311062001
^transtime %B %d, %Y^
November 6, 2001
Chapter 8
Document Transmission and Notifications
77
OpenText RightFax 10.5 Integration Module Guide
Table 8f ^Transtime^ Variables (Continued)
Variable
Description
%y
Year without century, as a digit (00-99).
%Y
Year with century, as a digit.
%z
Time-zone name or abbreviation; no characters if
time zone is unknown.
%Z
Time-zone name or abbreviation; no characters if
time zone is unknown.
%%
Percent.
#
Prefixes formatting code to modify as follows:
%#c — long date and time
%#x — long date
%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U,
%#w, %#W, %#y, %#Y — remove any leading
zeros.
Sample notification templates
“Table 8g: Example Notification Templates” shows some typical
notification template files and the resulting notification messages.
The following FCL document includes the {{notifyhost}} command:
{{begin}}
{{fax 503-555-1234}}
{{notifyhost notifysuccess.inc notifyfail.inc 1}}
{{company Acme Steel Company}}
{{contact John Smith}}
{{comment Inv. # 12345}}
{{user1 JB1234KU-6789DJJS}}
{{owner William Murray}}
Body of the document to be sent.
{{end}}
Table 8g Example Notification Templates
Template file with keywords
Resulting notification
message
Duration ^duration 4^
Duration 34
Date ^transtime %m/%d/%y^
Date 05/22/2001
Comment ^comment 40^
Comment Inv. #12345
Time ^transtime %H:%M^
Time 08:37
Fax ^phone 40^
Fax 503-555-1234
Page ^pagessent 02^/^pages 02^
Page 02/02
Return Code ^retcode 20^
Return code success
78
Table 8g Example Notification Templates
This command line defines how the notification will be sent. In this
case, the program fax2mapi.exe will send the notification message
to a MAPI-compliant e-mail box. The switches -t, -u, and -f are
unique to Fax2mapi.exe. Each executable has its own switches.
Template file with keywords
Resulting notification
message
Date ^transtime %B %d, %Y^
Date May 22, 2001
Sent to this number: ^fax 40^ at
^transtime %H:%M^
Sent to this number:
503-555-1234 at 8:37
Regarding ^comment 40^
Regarding Inv. # 12345
z
Sent to ^contact 40^
Sent to John Smith
z
Sending confirmation: ^retcode 20^
Sending confirmation:
success
Success/error code: ^retcode^
Success/error code:
Sent to ^contact 40^ at ^company 60 ^ invalid phone number
Sent to John Smith at
Subject: ^comment 40^
Acme Steel Company
Day/time: ^transtime %B %d,
Subject: Inv. # 12345
%Y^/^transtime %H:%M^
Day/time: May 22,
2001/8:37
To configure the notification command line in the Integration
Module Configuration program, you use:
Switches that the individual executable will recognize.
Variables that will supply information about the sent document for
the notification message.
To create a new notification channel
1. On the RightFax server, select Start > Programs > RightFax >
Enterprise Fax Manager.
2. In Enterprise Fax Manager, 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-click RightFax Integration
Module. The Integration Module Configuration window
appears.
Creating Notification Channels
Notifications are sent to the host application via channels. The
notification channel is specified in the command line that defines
how the notification will be sent to the host application. The
Integration Module supports 128 notification channels.
Warning Notification channel 16 is a default that the Integration
Module uses when no {{notifyhost}} command is specified. Do not
change the settings for channel 16.
“Figure 8.1: The Notification Process” on page 73 uses the
following notification command line:
fax2mapi -t $o -u “MS Exchange Settings” -f $$
Chapter 8
Document Transmission and Notifications
79
OpenText RightFax 10.5 Integration Module Guide
4. Right-click Notification Channels, and select Add Output
Device from the shortcut menu. The available settings for the
notification channel appear in the Integration Module
Configuration window.
Figure 8.2 The Notification Channels settings
6. In the in Command line box, enter the case-sensitive command
line for the channel. For information on the command line to use
for each type of notification, refer to the appropriate section in
this chapter:
z
z
z
z
z
z
z
z
“Sending notifications via SMTP” on page 82
“Sending notifications to a database” on page 83
“Sending notifications to an SMS-enabled device” on
page 84
“Sending notifications via 3270 emulation” on page 85
“Sending notifications via FTP” on page 86
“Sending notifications via IBM WebSphere MQ” on page 87
“Sending notifications to Lotus Notes” on page 88
“Sending notifications to Microsoft Exchange” on page 88
7. Select the Keep files check box if you want to save a copy of
each notification that is sent to the host application.
Notifications are saved in the Windows Temp folder.
8. Click OK to save the new notification channel.
Methods used for notification messages
The following table lists the common methods you can use for
connecting to and sending notification messages to a device or
host application. Contact OpenText for information on other
available notification methods.
5. In the Name box, enter a descriptive name for the channel. The
channel number is assigned as you add channels.
80
Notify.exe on the RightFax Integration Module sends the notification
message to the host application via the method listed in the first
column using the executable listed in the second column.
Table 8h Notification Methods and Executable Program Files
Connection
method
Program that
sends the
notification
SMTP
Mailsend.exe
Sends messages via SMTP to an
SMTP-compliant mail server.
ODBC
database
Dbnotify.exe
Sends notifications to an ODBC
data source.
SMS
Rfsms.exe
Sends notifications to an
SMS-enabled device via the
Push-Proxy Gateway (PPG) server.
Description
3270
emulation
Hlpisend.exe
Sends notifications back through
3270; uses high-level-language
application-programming interface
(HLLAPI). This requires third-party
3270 emulation software.
FTP
Ftpit.bat
Is a Perl script used to log on to an
FTP server and transfer files.
IBM
WebSphere
MQ
Mqput.exe
Sends a message to the specified
remote queue by the specified
remote queue manager. This
requires IBM WebSphere MQ
software.
Notes
Fax2note.exe
Sends messages to a Lotus Notes
system using Notes API.
Exchange
Fax2mapi.exe
Sends messages to Microsoft
Exchange using MAPI. This
requires a Microsoft Exchange
client on the fax server.
Each of these executable files including their command line
parameters are defined in the sections that follow. For each
executable, one or more command line parameters support
variables that let you pull information directly from the FCL in the
document that was sent.
The following table lists the command line variables that can be
used with all notification executables. The FCL equivalents are
FCL-based information that populates the corresponding variable.
For example, $^ is replaced by the information included in the
{{termid}} FCL command in a sent document. So, if an FCL
document contains {{termid A3}}, then A3 will be used in the
command when it executes.
Table 8i Notification Channel Variables
Variable FCL equivalent
Notes
$$
N/A
File name of the notification created
by Notify.exe. This file contains the
text of the notification to be sent and
is formatted using the notification
template specified with the
{{notifyhost}} FCL command.
$^
{{termid}}
The termination code of the sent fax.
$B
{{billing}}
{{billing2}}
Billing codes 1 and 2
$C
{{comment}}
Comment text.
$c
{{emailcc}}
The e-mail address where a copy of
the message should be sent. This
command can be used if you have
licensed the InternetLink Module.
$d
N/A
The document number assigned by
the Integration Module.
$D
{{dept}}
The string defined as department.
$E
{{empid}}
The employee ID.
Chapter 8
Document Transmission and Notifications
81
OpenText RightFax 10.5 Integration Module Guide
Table 8i Notification Channel Variables (Continued)
Variable FCL equivalent
Notes
$f
The e-mail address of the originator
of the document. This command
can be used if you have licensed the
InternetLink Module.
{{from}}
$o
{{owner}}
The RightFax ID of the originator of
the fax.
$p
N/A
The name of the currently selected
printer.
$P
N/A
The number of pages sent, not
including the cover sheet.
Sending notifications via SMTP
To create a notification channel that sends messages to an SMTP
mail server, use Mailsend.exe.
Syntax
mailsend [options] input filename
Table 8j Mailsend.exe Command Line Options
Option
Description
-a
Abort if connect fails.
-c address
E-mail address where a copy of the message will
be sent. The e-mail address can appear in the
following formats:
Ashutosh Apte <[email protected]>
$r
N/A
The return code.
<[email protected]>
$R
{{replyto}}
The reply to name.
[email protected]
$s
{{subject}}
The e-mail subject. This command
can be used if you have licensed the
InternetLink Module.
Mailsend.exe will convert these formats to
<[email protected]>.
$t
{{to}}
The e-mail address of the recipient
of the message. This command can
be used if you have licensed the
InternetLink Module.
$T
N/A
The TIF file name of the document.
$w
{{winsecid}}
The RightFax user ID of the
originator of the fax.
$1
{{user1}}
User-defined data code 1.
$2
{{user2}}
User-defined data code 2.
$3
{{user3}}
User-defined data code 3.
-f address
E-mail address of the sender of the document.
-h
Displays online help for Mailsend.exe.
-H
Input file contains mail headers.
-m “mailhost”
The name of the mail host where messages will be
sent. The name must be surrounded by quotation
marks.
-o
Obtain the recipient e-mail address from the first
line of the file, and obtain the subject of the e-mail
message from the second line.
-s subject
Subject of the e-mail message.
82
Table 8j Mailsend.exe Command Line Options (Continued)
Table 8k Description of the Example Command Line
Option
Description
Element3
Description
-t address
The e-mail address of the recipient of the
notification message. The e-mail address can
appear in the following formats:
-s “Notification of Fax”
The text that will appear in the
subject line of the e-mail
message.
Ashutosh Apte <[email protected]>
$$
The file name of the document.
<[email protected]>
[email protected]
-v
Sending notifications to a database
Mailsend.exe will convert these formats to
<[email protected]>.
To create a notification channel that sends SQL messages to a
database, follow these steps:
Display verbose messages.
1. Set up a new Data Source Name (DSN) by selecting Start >
Example mailsend -m “smtpserver.yourhost.com” -t "$o" -f
[email protected] -s "Notification of Fax"
$$
Table 8k Description of the Example Command Line
Element3
Description
mailsend
The name of the executable file
that will process the
notification.
-m “smtpserver.yourhost.com”
The name of the mail host.
-t “$o”
The recipient’s name, who is
also the sender of the
document. The recipient will be
obtained from the {{owner}}
FCL command in the document
received from the host
application.
-f [email protected]
The e-mail system’s address
and the sender’s SMTP
address, which is required in
order to receive the notification.
Settings > Control Panel > Data Sources (ODBC). This
opens the ODBC Data Source Administrator dialog box. Click
Add and complete the options to create the new DSN. Make a
note of the DSN name as you will need it later.
2. Create notification templates for both success and failure
notifications. These are text files that contain the SQL
commands that define where and how the notifications will be
written to the database.
Example Insert SampleTable(ID,Status)
Values(^DocNum^, ‘^RetCode^’)
Chapter 8
Document Transmission and Notifications
83
OpenText RightFax 10.5 Integration Module Guide
3. Configure a new notification channel (described on page 79)
using the Dbnotify.exe program in the Command Line box.
Syntax
dbnotify {-fFileName|-sSQL} [-uUserID]
[-pPassword] DSN
Table 8l Dbnotify.exe Command Line Options
Option
Description
-fFileName
Fully qualified file name of a file containing the SQL
script for the notification. You must use -f or -s, but
not both.
-sSQL
SQL script to execute containing the notification
script. You must use -f or -s, but not both.
-uUserID
User ID. This is only required if your ODBC data
source was not configured with a user name.
-pPassword
Password. This is only required is your ODBC data
source was not configured with a password.
DSN
Data Source Name that you created in step 1.
Example dbnotify -f$$ DSN
Sending notifications to an SMS-enabled device
To send notifications to an SMS-enabled device via the Push-Proxy
Gateway (PPG) server, follow these steps:
1. Install and configure the Push-Proxy Gateway server. Refer to
the documentation for this product for instructions.
2. Create a Pager/SMS service in Enterprise Fax Manager with
SMS as the Service Type. This service is required for
communication between the RightFax server and the
Push-Proxy Gateway server that sends the SMS messages. For
information on creating SMS/Pager services in Enterprise Fax
Manager, refer to the RightFax Administrator’s Guide.
3. Create notification templates for both success and failure
notifications (described on page 73). The total length of the
notification message, including the text substituted for keyword
variables may not exceed 160 characters (the maximum allowed
length for SMS messages).
4. Configure a new notification channel (described on page 79)
using the Rfsms.exe program in the Command Line box.
Syntax
Table 8m Description of the Example Command Line Above
Element3
Description
dbnotify
The name of the executable file that will
process the notification.
-f $$
Tells Dbnotify to use the SQL script in the
template that was specified in the
{{notifyhost}} command in the data stream.
DSN
This is the name of the DSN you created in
step 1.
rfsms -sSMSService -dSMSNumber
[{-mFile|”MessageText”}] [-v] [-fRFServer]
[-uUserID] [-pPassword]
Caution Rfsms.exe does not perform error checking on the
parameters you enter on the command line. Make sure that all
command line parameters are correct and that the accounts specified
exist on the server.
Table 8n Rfsms.exe Command Line Options
Option
Description
-sSMSService
The Service ID of the SMS/Pager service you
created in Enterprise Fax Manager.
-dSMSNumber
The phone number of the SMS device you will
be contacting.
84
Table 8n Rfsms.exe Command Line Options (Continued)
Table 8o Description of the Example Command Line Above (Continued)
Option
Description
Element3
Description
{-mFile|
”MessageText”}
Specify a file name containing the alert text, or
enter the alert text between quotes. If you
specify the message text in quotes, do not use
the -m switch.
-d$1
Maps to the {{SMS}} FCL code.
-m$$
The file containing the alert text to send.
-v
Enables verbose event logging.
[-fRFServer]
The name of the RightFax server on which the
SMS service specified with the -s option
resides. This is only required if the SMS
service is not on the current server.
[-uUserID]
[-pPassword]
The RightFax user ID required to log on to the
RightFax server. This is only required if you are
not using a trusted account.
The password for the RightFax user ID
specified with the -u option.
Example rfsms -fRFServer -uAdministrator -pPassword
-sRFPPG -d$1 -m$$
Table 8o Description of the Example Command Line Above
Element3
Description
rfsms
The name of the executable file that will process
the notification.
-fRFServer
The name of the RightFax server on which the
specified Pager/SMS service resides.
-uAdministrator
The RightFax user ID used to log on to the
server.
Sending notifications via 3270 emulation
To create a notification channel that sends messages via 3270
using high level language application programming interface
(HLLAPI), use Hlpisend.exe.
Syntax
hlpisend [options] filename
Table 8p Hlpisend.exe Command Line Options
Option
Description
-c
Do not clear screen before notifying.
-e character
Set escape character.
-E
Do not send enter after sending file.
-h
Displays online help for Hlpisend.exe.
-H number
HLLAPI emulation package
1=Attachmate (default)
2=WRQ
3=Rumba
4=IBM Personal Com
5=NetSoft Elite (not supported)
-i
Interact with host (filename is a script).
-l script
Specify login script.
-p delay
Set host power-up delay.
-pPassword
The password for the specified user ID.
-S
SSCP invalid for input.
-sRFPPG
The service ID of the Pager/SMS service in
RightFax that sends SMS messages.
-s number
Set session number.
-t
Use file transfer.
Chapter 8
Document Transmission and Notifications
85
OpenText RightFax 10.5 Integration Module Guide
Table 8p Hlpisend.exe Command Line Options (Continued)
Option
Description
-v
Display verbose messages.
-w seconds
Specify wait after input.
This program uses a Perl script used to log on to an FTP server and
transfer files. In the command line, you must supply a host name,
user name, and password. Ftpit.bat creates a remote file name
called jcl###, or you can specify the file name in the command
line.
Syntax
ftpit [options] hostname username password localfile
Example hlpisend -s A -H 2 -l login.inc $$
Table 8r Ftpit.bat Command Line Options
Table 8q Description of the Example Command Line
Element
Description
hlpisend
The name of the executable file that will process
the notification.
-s A
The HLLAPI shortname of the session. A is the A
session. B is the B session, etc.
-H 2
The number for the HLLAPI emulation package. In
this case, 2 = WRQ.
-l login.inc
The file name of the login script for the session.
Login.inc is created custom for every install.
$$
The file name of the document.
Sending notifications via FTP
To create a notification channel that sends messages via FTP, use
Ftpit.bat.
Option
Description
-h
Display online help for Ftpit.bat.
-A account
Account name.
-a file name
Remote file to append to.
-c command
Quote command (such as LRECL (80)).
-r directory
Remote destination directory.
Example ftpit yourhost.com franklins qwerty $$
Table 8s Description of the Example Command Line
Element
Description
ftpit
The name of the executable file that will
process the notification.
yourhost.com
The name of the FTP host to which the
notification will be sent.
franklins
The name of the user to whom the notification
will be sent.
qwerty
The password for the user and host.
$$
The file name of the document.
86
Sending notifications via IBM WebSphere MQ
To create a notification channel that sends messages via IBM
WebSphere MQ, use Mqput.exe.
Table 8t Mqput.exe Command Line Options (Continued)
Option
Description
-s
Make messages persistent. If the server is
restarted, the IBM WebSphere MQ server will
store messages so that they can be accessed after
the server is restarted.
-v
Display version information.
-1
Selects Version 1 of the WebSphere MQ
Application Programming Reference.
This program submits a message to a specified remote queue.
Mqput.exe receives the body of the message from standard input
(STDIN) or from a file that you specify in the command line.
Syntax
mqput -C channel -H hostname -M queue manager -Q
queue [options]
Table 8t Mqput.exe Command Line Options
Option
Description
-C channel
Name of the IBM WebSphere MQ channel to use
for connection.
-H hostname
Fully qualified domain name of the IBM
WebSphere MQ queue manager.
-M queue
manager
IBM WebSphere MQ queue manager to connect
to.
-Q queue
IBM WebSphere MQ queue to retrieve messages
from.
-d
Display debugging output. This is helpful if you
experience difficulty connecting to the server.
This option must be used because MQPut.exe is
not designed to work with the WebSphere MQ API
Version 2.
-tCCSID
Specifies the codeset name for a language. A list of
the codeset IDs (CCSIDs) supported by
WebSphere MQ is available from IBM.
Example mqput -C RF_Chan -H qmmaster2 -M RightFax -Q
RF_Notify -i $$ -p 1414 -1
Table 8u Description of the Example Command Line
Element
Description
-e days
Days until message expires. Default is no
expiration.
mqput
The name of the executable file that will
process the notification.
-f
If the message fails in delivery to the destination
queue, cancel it rather than put it in the dead-letter
queue. This is helpful during testing or initial setup.
-C RF_Chan
The IBM WebSphere MQ channel name.
-H qmmaster2
Source of data to send to the queue. Input can be
a file or standard input (STDIN). If no file is
specified, STDIN is the default.
Indicates that the fully qualified domain name of
the IBM WebSphere MQ queue manager will
come next.
-M RightFax
The IBM WebSphere MQ queue manager.
-p port
TCP/IP port number to use for remote connection.
The default is 1414.
-Q RF_Notify
The IBM WebSphere MQ queue name.
-i $$
The file name of the document.
-r priority
Message priority. The default is 0.
-p 1414
The TCP/IP port number.
-i input
Chapter 8
Document Transmission and Notifications
87
OpenText RightFax 10.5 Integration Module Guide
Sending notifications to Lotus Notes
To create a notification channel that sends messages to a Lotus
Notes system using the Notes API, use Fax2note.exe.
Syntax
fax2note [options] recipient
Table 8v Fax2note.exe Command Line Options
Sending notifications to Microsoft Exchange
To create a notification channel that sends messages to an
Exchange system using MAPI, use Fax2mapi.exe.
Syntax
fax2mapi [options]
Table 8x Fax2mapi.exe Command Line Options
Option
Description
Option
Description
-t e-mail
address
Recipient(s). Multiple recipients must be separated
by a semicolon (;) and enclosed in quotation marks
(“). Recipients must not be ambiguous in default
address book.
-a file name
Attach the specified file.
-f file name
Name of an ASCII text file to use as the message
body.
-s
The subject line of the e-mail message.
-i file name
Name of an ASCII text file to use as the message
body.
-a
Identifies a file to attach to the e-mail message.
-k
Keep sent mail.
-f
Identifies an ASCII text to use as the body of the
e-mail message.
-p password
Profile password.
-o
Identifies the owner of the e-mail message.
-q CSID
CSID associated with the FAX address type of
recipient. This option overrides any address
specified with -t.
-r DID
DID associated with the FAX address type of
recipient. This option overrides any address
specified with -t.
-s subject
Subject line of the e-mail message.
-t e-mail
address
E-mail address for recipient(s). Multiple recipients
must be separated by a semicolon (;) and enclosed
in quotation marks (“). Recipients must not be
ambiguous in default address book.
Example fax2note -t “$o” -s “Fax Notification” -f $$
Table 8w Description of the Example Command Line
Element
Description
fax2note
The name of the executable file that will
process the notification.
-t “$0”
The recipient of the notification. The recipient
will be obtained from the {{owner}} FCL
command in the document received from the
host application.
-s “Fax
Notification”
The subject line of the notification message.
-f $$
The file to be used as the message body. The
content of the notification template file will
replace the $$ variable.
The -q and -r options override the -t option.
-u profile
Mail profile name.
-z
File (in RTF format) to be used as a message body.
Example fax2mapi -t “$o” -s “Fax Notification” -f $$ -u “MS
Exchange Settings”
88
Table 8y Description of the Example Command Line
Element
Description
fax2mapi
The name of the executable file that will
process the notification.
-t “$0”
The recipient of the notification. The recipient
will be obtained from the {{owner}} FCL
command in the document received from the
host application.
-s “Fax
Notification”
The subject line of the notification message.
-f $$
The file to be used as the message body. The
content of the notification template file will
replace the $$ variable.
-u “MS Exchange
Settings”
The mail profile name.
Including the {{Notifyhost}} Command in
Documents
The third step in creating notifications is to include the
{{notifyhost}} FCL command in the document from the host
application. This command specifies the notification template. It
also specifies the notification channel, as created in the RightFax
Integration Module Configuration program.
In the syntax shown below, the template files (Success.inc for
successful documents and Failure.inc for failed documents) are
specified. If the template name is not specified, then no notification
is sent. The channel keyword specifies the channel. The channel
can either be a channel number (from 1 to 128) or name. If no
channel is specified, the default channel will be used, number 16.
Syntax
{{notifyhost success.inc failure.inc channel}}
Examples {{notifyhost mysucc myfail mynotify}}
{{notifyhost none myfail mynotify}}
The first example shows that if the document is sent successfully,
the Integration Module will create a notification based on a
template called “mysucc.” The “.inc” extension is the default, as is
the path to the Include folder. If the document fails to send properly,
the “myfail” template is used.
In either case, the notification is sent via the channel that is named
“mynotify.”
The second example sends a notification (based on the template
Myfail.inc) if the document fails to send. Because “none” is entered
instead of the success template name, no message will be sent if
the document is transmitted successfully.
The {{notifyhost}} command can be included in the document from
the host application to the Integration Module, or you can insert it in
an include file. See ”Reusing FCL Commands Across Many
Documents” on page 45.
Creating the {{Notifyhost}} command
The {{notifyhost}} command must contain:
z
z
z
The name of the success template, as described in ““Creating
Notification Templates” on page 73.
The name of the failure template, as described in ““Creating
Notification Templates” on page 73.
The notification channel number or name, as described in
““Creating Notification Channels” on page 79.
The following example shows an FCL document that includes a
{{notifyhost}} command.
Chapter 8
Document Transmission and Notifications
89
OpenText RightFax 10.5 Integration Module Guide
{{begin}}
{{fax 503-555-1234}}
{{notifyhost notifysuccess.inc notifyfail.inc 1}}
{{company Acme Steel Company}}
{{contact John Smith}}
{{comment Inv. # 12345}}
{{user1 JB1234KU-6789DJJS}}
{{owner William Murray}}
{{end}}
Table 8z Notification FCL Commands (Continued)
Command
Description
{{Comment}}
Any user-defined message specific to the
document.
This command is most often used to populate
variables in cover sheets but is sometimes used
with notifications.
{{Company}}
This command is most often used to populate
variables in cover sheets but is sometimes used
with notifications.
Other FCL used in notifications
A number of informational FCL commands can be used for
notifications. These commands store information about the sender
of the document so that notification messages can be sent
specifically to that person, department, terminal, or another
destination.
The following table lists these commands and gives a brief
explanation. More detailed information on each of the commands is
also contained at the end of this document. See ”FCL
Commands” on page 165. For a comparison of the commands
listed here and the keywords that you can use in notification
templates, see “Table 8b: Notification Keywords and FCL
Equivalents”.
{{Contact}}
Description
{{Billing}}
The billing code of the document owner.
This command is sometimes used to populate
variables in cover sheets.
{{Billing2}}
A secondary billing code of the document owner.
This command is sometimes used to populate
variables in cover sheets.
The contact name for the document.
This command is most often used to populate
variables in cover sheets but is sometimes used
with notifications.
{{CSI}}
The CSID. This is usually the general fax number
for the enterprise.
You can set a default CSID in the Integration
Module Configuration program. See ”Setting
Defaults for FCL Documents” on page 126.
{{Dept}}
The string defined as department.
{{Email}}
The e-mail address for the recipient of the
notification message.
{{EmpID}}
The employee ID of the fax owner.
Table 8z Notification FCL Commands
Command
The company name for the document.
This command is sometimes used to populate
variables in cover sheets.
{{Owner}}
The document owner’s name.
This command is most often used to populate
variables in cover sheets but is sometimes used
with notifications.
90
Table 8z Notification FCL Commands (Continued)
Table 8z Notification FCL Commands (Continued)
Command
Description
Command
Description
{{ReplyTo}}
The recipient for the notification. You can request
that an HTTP post be sent back to the host as a
notification when you use the RightFax XML
Interface. ReplyTo is the field in the submit post
that the RightFax XML Interface populates to
determine where to send the notification.
{{UserID}}
The RightFax user ID of the creator of this
document.
{{TermID}}
The ID of the terminal from which the document
originated.
This command is sometimes used to populate
variables in cover sheets.
{{TranID}}
The ID of the transaction that produced the
document.
This command is sometimes used to populate
variables in cover sheets.
{{UniqueID}}
An identification number for each destination (fax
number) within the document.
This command is used most often for tracking. The
Integration Module will generate a UniqueID unless
you specify one in the FCL. Then, you can track the
document in FaxUtil based on the UniqueID.
Secondarily, this command is sometimes used in
cover sheets and with notifications.
{{User1}}
{{User2}}
{{User3}}
User-defined data, such as the originator of the
document (person, group, or other information).
This command is sometimes used to populate
variables in cover sheets.
{{Voice}}
A voice telephone number.
This command is sometimes used to populate
variables in cover sheets.
Testing That the Host Application Is Correctly
Receiving Notifications
The simplest way to test that notifications are being received
properly is to send a test document. If the correct notification is
received using the correct channel, then the channel is configured
correctly. If not, then you can use this chapter to troubleshoot the
problem.
Note that notification messages are not generated by the
Integration Module for incomplete faxes. Usually, such faxes are
missing information that is required for sending. For more
information, See ”Creating Notification Messages with FCL” on
page 72.
The following procedure requires that you have already created a
notification channel, created a notification template, and created
the {{notifyhost}} command that will identify the channel and
template.
The information presented here is not specific to the various
notification methods you might have already created. Rather, this
procedure is presented in general terms that can be applied to any
notification type. If you are unable to successfully troubleshoot
failed notifications, you can contact OpenText Customer Support.
Chapter 8
Document Transmission and Notifications
91
OpenText RightFax 10.5 Integration Module Guide
1. Send a test document from the host to the Integration Module.
You might use the {{fax}} command to have the Integration
Module send the document. Besides {{fax}}, the test document
must at least include {{begin}}, {{end}}, the correct
{{notifyhost}} command, and some sample text.
2. Verify that you receive a notification from the Integration Module
in the location that you specified when you created the
notification channel.
3. Verify that you receive a notification that contains the correct
information (it should be the same as the notification template
that you created).
If you do not receive a notification, or if the notification does not
contain the correct information, then see “Troubleshooting
Notification Messages”on page 92.
To test the Integration Module-to-Host connection for IBM
WebSphere MQ
1. Open a command prompt window.
2. Enter the command you entered in the Command line box in
the Add Output Device dialog box when you created the
notification channel.
Warning Command line options are case-sensitive. If you do not
enter the command here exactly as you did in the Add Output
Device dialog box, errors will occur.
3. Press ENTER.
Figure 8.3 Testing IBM WebSphere MQ Notifications
Testing IBM WebSphere MQ connections
This procedure applies to IBM WebSphere MQ connections. It
verifies that data is flowing from the Integration Module to the host
(as opposed to verifying that the host received a notification).
This procedure requires that you have correctly configured:
z
z
The host to receive data from the Integration Module
The Mqput.exe notification channel on the Integration Module
(See ”Sending notifications via IBM WebSphere MQ” on
page 87.).
If the notification channel connection is successful, then you should
see messages similar to those shown in “Figure 8.3: Testing IBM
WebSphere MQ Notifications”. If the output connection is not
successful, then you will see error messages.
Troubleshooting Notification Messages
Use the following flowchart and the corresponding numbered
paragraphs on the next page to identify the source of the error.
92
Figure 8.1 Troubleshooting Notifications
3. When you do not receive a notification after sending a
document, the first step should be to verify that the RightFax
server is sending data. Open FaxUtil and verify that faxes are
being sent. If no faxes are being sent, then no notifications can
be sent.
4. If you verified in FaxUtil that faxes are being sent, then run
Notify.exe in debug mode to proceed.
z
z
z
z
Stop Notify.exe from the Process tab in Windows Task
Manager.
Open a command prompt window.
Change Directory to “C:/Program Files
(x86)\Rightfax\Production\bin.
Type notify.exe, and then press ENTER.
The information that appears will indicate the status of
Notify.exe.
5. When Notify.exe is attempting to send a notification, you will see
information in the command prompt window that describes the
error (see the next steps for more information). If Notify.exe
returns a message such as “Checking no record,” then it is not
receiving a signal that a document has arrived at the Integration
Module. In this case, you must check the connection (see ,
Chapter 3, ”Configuring the RightFax Integration Module to
Receive Data”).
6. One reason that Notify.exe would not appear to be attempting
1. If you have created several templates with similar names, a
minor typographical error can identify the wrong template,
resulting in a notification that contains errors and nonpopulated
keywords. If you specify a template that does not exist, then no
notification can be created or sent.
2. The template must contain valid (and correctly spelled)
keywords. For a list of valid keywords, See ”Notification
Keywords and FCL Equivalents” on page 74..
notifications is that the {{notifyhost}} command is absent from
the host data stream. The error in this case is commonly that the
command exists but is misspelled, is missing one or more of its
braces, or contains another syntax error that causes Notify.exe
to not identify it. When this is the case, Notify.exe will return a
message such as “Check Notify <ID number>” with no more
text after it. This message means that Notify.exe is checking its
queues; when no more text comes after this message, then
Notify.exe found no queued notifications.
Chapter 8
Document Transmission and Notifications
93
OpenText RightFax 10.5 Integration Module Guide
7. If Notify.exe appears to be attempting a notification, examine the
9. If you have not yet found an explanation for the problem, it is
{{notifyhost}} command in the FCL document. Common
problems include:
z
z
A template that does not exist (Notify.exe will return a
message such as “Unable to include file: <path>.inc”).
A notification ID that does not exist (Notify.exe will return a
message such as “Cannot find notify channel [#], defaulting
to [#]” or “Executing Copy C:\temp\<document
number>.NT1 NUL”). In the case of the second message, the
file is being copied to NUL (being deleted). This happens
because Notify.exe uses the default ID (16) when no ID
exists. The default action for ID 16 is to copy to NUL; thus, if
you leave ID 16 unchanged, then files that are being copied
to NUL probably have no ID associated with them. If you
have changed the action for ID 16, then nonexistent IDs will
result in the action that you specified for ID 16.
8. Check the command line you created for the notification
channel (See ”Creating Notification Channels” on page 79.).
Common problems include:
z
z
z
A misspelled or invalid executable file, or (if you specified a
path to the executable) the wrong path. (You will see a
message such as “The name specified is not recognized as
an internal or external command, operable program, or batch
file”).
Omitted or wrong variables or switches; incorrect syntax
(Notify.exe will return a message specific to the executable or
command that you used).
In some cases, depending on the command, executable, or
other command line elements, Notify.exe will not return an
error message even though the command line contains an
error.
likely that the Integration Module is processing and sending the
notification correctly. The error is probably somewhere else,
such as the network, host computer, or host application. Further
evidence would be Notify.exe returning a message such as “1
file(s) copied. Function returned 0: success” or a similar
message indicating a successful action.
Setting Up Actions on Document Transmission
You can configure the RightFax Integration Module to notify you
when a document has been sent or has errors in transmission.
Notifications can be in several formats, such as sending the
notification to a printer or sending a copy of the fax to a specified
user. These actions are similar to notification messages. See
”Creating Notification Messages with FCL” on page 72.
Notification messages contain information such as whether or not a
document was transmitted, transmission errors, and other
information such as the date and time of transmission and the
owner of the document.
Printing or Faxing a Copy of a Document That Was
Transmitted
You have two options for establishing actions that occur when
documents are transmitted successfully:
z
z
Set defaults in the RightFax Integration Module Configuration
program.
Use the {{onsuccess}} FCL command in a document to override
the default.
Setting the default “success” action
When a document is successfully transmitted, a copy of the
document can be sent to another recipient as a notification of the
transmission.
94
To set the success action
1. From the Start menu, select Programs > RightFax >
Enterprise Fax Manager. The Enterprise Fax Manager
window appears.
2. In the Fax Servers list, click the name of the server on which the
RightFax Integration Module is running.
3. In the Service Name list, double-click RightFax Integration
Module. The RightFax Integration Module Configuration
window appears.
5. Under Fax Options, select Fax on Success or Fax on Error to
send the fax to a new recipient on these events. If you select
either of these options, you must also enter a destination fax
number in the To Number field.
6. Under Delete Options, select the option corresponding to
when you want the fax images deleted from the server.
Never
Fax images will never be automatically deleted
from the server.
On Success
Fax images will be automatically deleted from
the server only when they have been sent
successfully.
Always
Fax images will be automatically deleted from
the server on both successful and failed
transmission attempts.
4. In the left pane, click General continued.
Figure 8.4 The General Continued Settings
7. Click OK.
Using the {{onsuccess}} command to set “success” actions
for a document
To set “success” actions for a document and override the default,
add the {{onsuccess}} command to the FCL. In the following
example, a copy of the document will be faxed to another recipient
if it is successfully transmitted.
{{begin}}
{{onsuccess fax 503-555-1234}}
{{fax 503-555-4489}}
Body of the document to be sent.
{{end}}
You can specify destinations of delete, certified, fax, email, mime,
or nothing with the {{onsuccess}} FCL command. See ”FCL
Commands” on page 165.
Chapter 8
Document Transmission and Notifications
95
OpenText RightFax 10.5 Integration Module Guide
Printing or Faxing a Document That Cannot Be
Transmitted
You have two options for establishing actions that occur when
documents are not sent:
z
z
4. In the left pane, click General continued.
Figure 8.5 The General Continued Settings
Set defaults in the RightFax Integration Module Configuration
program.
Use the {{onerror}} FCL command in a document to override the
default.
Setting the default “error” action
When a document cannot be successfully transmitted, a copy of
the document can be sent to another recipient as a notification of
the failure.
To set the error action
1. On the Start menu, select Programs > RightFax > Enterprise
Fax Manager. The Enterprise Fax Manager window appears.
2. In the Fax Servers list, click the name of the server on which the
RightFax Integration Module is running.
3. In the Service Name list, double-click RightFax Integration
Module. The RightFax Integration Module Configuration
window appears.
5. Under On error, select one of the following options.
Table 8aa On error Options
Option
Description
Nothing
No action will be taken.
Delete
The fax image will be deleted from the fax server.
Fax
Fax the document to another recipient.
Enter a fax number in the To number: box.
Select Delete when finished to delete the fax
image from the fax server.
6. Click OK.
96
Using the {{onerror}} command to set “error” actions for a
document
To set “error” actions for a document and override the default, add
the {{onerror}} command to the FCL. In the following example, a
copy of the document will be faxed to another recipient if it is not
successfully transmitted.
4. In the left pane, click FCL Processor.
Figure 8.6 The FCL Processor Settings
{{begin}}
{{onerror fax 503-555-1234}}
{{fax 503-555-4489}}
Body of the document to be sent.
{{end}}
You can specify destinations of delete, certified, fax, email, mime,
or nothing with the {{onerror}} command. See ”FCL Commands”
on page 165.
Performing Actions on Documents With FCL Errors
When the RightFax Integration Module processes a document, it
extracts data from the FCL commands, then creates and sends the
document. You can specify which actions the system should take If
there is an error that prevents the document from transmitting.
To set default actions
1. From the Start menu, select Programs > RightFax >
Enterprise Fax Manager. The Enterprise Fax Manager
window appears.
5. To print the document, select Print FCL to printer, and then
enter the name of the printer as defined in the Enterprise Fax
Manager.
6. To fax the document, select Fax FCL to number, and enter the
fax number.
2. In the Fax Servers list, click the name of the server on which the
RightFax Integration Module is running.
3. In the Service Name list, double-click RightFax Integration
Module. The RightFax Integration Module Configuration
window appears.
Chapter 8
Document Transmission and Notifications
97
OpenText RightFax 10.5 Integration Module Guide
7. To send the document using a notification channel, select
Execute command line, and then enter an appropriate
command line. To do so, refer to the instructions for writing
notification command lines in “Creating Notification Messages
with FCL” on page 72.
Example The document can be sent to Microsoft Exchange as an
e-mail message. Therefore, in the Execute command
line box, you enter:
fax2mapi -t [email protected] -f $$ -u “MS
Exchange Settings”
When a document fails because of any FCL error, the
RightFax Integration Module will send it to the e-mail
address [email protected]
98
Chapter 9
Programming for the RightFax XML Interface
The RightFax XML Interface converts XML to FCL. When the
RightFax Integration Module receives an XML-based document, the
RightFax XML Interface converts it to an FCL-encoded document.
The availability of XML Interface functions depends on the method
of transport.
Table 9a XML Interface Transport Methods and Functions
Action
HTTP or
HTTPS
File
IBM
WebSphere
MQ
Action
Yes
Yes
Yes
Action Reply
Yes
Yes
No
Notification
Yes
Yes
Yes
Query
Yes
Yes
No
Query Reply
Yes
Yes
No
Submit
Yes
Yes
Yes
Submit Reply
Yes
Yes
No
Introduction to the RightFax XML Interface
The XML Interface software performs four functions (submit, query,
action, and notification) via three methods of transport (HTTP or
HTTPS, FTP, and IBM WebSphere MQ). XML Interface
functionality is achieved by creating XML documents that adhere to
RightFax schemas (page 106).
The RightFax API for Java is for Java programmers. It provides an
alternate method of creating and sending XML to the RightFax
server. The API for Java allows access to XML Interface
functionality without requiring that a customer know XML or the
RightFax XML Interface schemas. See ”Programming for the
RightFax API for Java” on page 137.
Installing the XML Interface
Note RightFax provides programming interfaces for both XML and Java.
These interfaces are both installed when you run the XML installation.
99
OpenText RightFax 10.5 Integration Module Guide
Minimum System Requirements
In addition to the minimum system requirements for the RightFax
server and RightFax Integration Module, Microsoft Internet
Information Server (IIS) version 6.0 or later must be installed on the
RightFax server.
If you are installing the XML interface on a server running IIS
version 6.0, Active Server Pages and ISAPI Extensions must be
enabled. Parent Paths must also be enabled, either for the Default
Web Site as a whole, or for the RFXML virtual directory which
appears after the installation of the Java/XML API.
If you are installing the XML interface on a server running IIS
version 7.0, you must enable CGI modules and ISAPI modules.
Parent Paths must also be enabled, either for the Default Web Site
as a whole, or for the RFXML virtual directory which appears after
the installation of the Java/XML API.
Installing the XML Interface
Follow the instructions for installing the RightFax server in the
RightFax Installation Guide and use the following specific steps:
On the Setup Type screen, select Custom and then click Next.
z On the Setup Features screen, expand the RightFax Server
heading in the components tree and select the Java/XML API
component to install. Click Next.
After the RightFax server and Java/XML API component is installed
and activated, you must configure an SMTP host and an IIS user
account for the rfxml website.
z
SMTP Host. Open the RightFax Server Module and click the
e-transport tab. Enter the name of the SMTP server on your
network that will transport all SMTP alerts and notifications
regarding the RightFax server. If you will not be using SMTP to
deliver RightFax alerts and notifications, you can leave this option
blank.
IIS User Account. In IIS, configure the rfxml website with an IIS
user account that RightFax will use to access the IIS server. This
account is required for Java development.
By default, the CGI-exe and ISAPI-dll Handler Mappings are
disabled by default. To enable the Module mapping for
rfwebcon.dll:
1. In IIS manager, select the rfxml virtual directory.
2. In the Features View under IIS, double-click Handler
Mappings.
3. Right-Click under Enabled and select Add Module Mapping.
4. Enter the following information in the Add Module Mapping
window:
Request path: rfwebcon.dll
z Module: IsapiModule
z Executable: <path to rfwebcon.dll>
z Name: rfwebcon
5. Click OK.
z
6. A warning will appear asking if you want to make this change.
Click Yes. An IIS reset should not be required.
Additional XML development tools are located in the
\Program Files\RightFax\Production\XML folder.
XML Interface Functions
Note that not every function is available for each transport method.
For more information, see “Table 9a: XML Interface Transport
Methods and Functions”.
Submit
To send an outgoing document, use the submit function. This
function is governed by the schema XML_FAX_SUBMIT, which
defines the optional and required XML tags needed to submit a
100
document to be sent by the RightFax server. The submit schema
includes information such as fax number, contact name, owner, and
attachments.
When you submit a document, you have the option of creating a
unique document ID for each recipient’s document or letting the
RightFax server assign a unique ID for you. For unique IDs that the
software creates, the format is:
z
z
The first seven characters are the name of the RightFax server
The last eight characters are a number unique to a document
Note If you create your own unique ID, it must be 15 characters or less.
When creating an XML document, it must match the RightFax XML
schema (see “The Schemas” on page 106). If the document does
not match the applicable schema—out of preference, convenience,
or any for other reason—then you must create an XSLT to convert
the document to the RightFax schema. Or, you can create an XSLT
to convert the document directly to FCL.
The companion to XML_FAX_SUBMIT is
XML_FAX_SUBMIT_REPLY, which informs you of each unique
document ID (if you did not create your own). The reply includes a
message such as “Document has been submitted for sending,”
indicating that the first step has been completed successfully. If
you configured RightFax to return a notification when the document
transmission is completed, then you will also receive an
XML_FAX_NOTIFICATION report on the status of the transaction
that is more detailed than XML_FAX_SUBMIT_REPLY.
Query
To determine the status of any document in the RightFax system,
including those not originating from XML, use the query function.
This function is governed by the schema XML_FAX_QUERY, which
defines the optional and required XML tags needed to submit a
query to the RightFax server. The query schema includes search
criteria such as date, time, and unique ID.
The companion to XML_FAX_QUERY is
XML_FAX_QUERY_REPLY, which is a report informing you of the
query results.
Action
To perform an action on a sent or received document, use the
action function. This function is governed by the schema
XML_FAX_ACTION, which defines the optional and required XML
tags needed to perform the action. You must specify the relevant
document with its unique ID, and then include instructions to
delete, forward, or create a library document.
The companion to XML_FAX_ACTION is
XML_FAX_ACTION_REPLY, which is a report informing you of the
status of the action you requested.
Notification
To receive a notification that a document was or was not sent
successfully from the RightFax server, create a notification that
uses the XML_FAX_NOTIFICATION.INC template. This function is
governed by the schema XML_FAX_NOTIFICATION, which
defines the XML tags used to create a notification. Notifications are
a one-way transaction. That is, the client cannot “notify” the server.
Rather, the user includes a notification request when using the
submit function, and the server sends a notification when the
submitted document is either sent successfully or not sent
successfully.
The notification function is different from the submit-reply function.
The message returned with submit-reply states that the server has
received the document from the client. The message returned with
notification states that the server has sent (or not sent) the
document to its destination.
For information on creating notifications, see Chapter 8,
”Document Transmission and Notifications”.
Chapter 9
Programming for the RightFax XML Interface
101
OpenText RightFax 10.5 Integration Module Guide
Transports
Note that some transport methods do not support all of the
RightFax XML Interface functions. For more information, see “Table
9a: XML Interface Transport Methods and Functions”.
You can provide transport and access list security using standard
mechanisms. Use HTTPS instead of HTTP to achieve transport
encryption. The Web server providing the RFWebCon.dll resource
can also generate user, IP address, and domain restrictions.
The XML Interface software supports three transport methods:
HTTP or HTTPS, FTP, and IBM WebSphere MQ. You can also use
the RightFax API for Java to create and send XML via HTTP. See
”Programming for the RightFax API for Java” on page 137.
HTTP or HTTPS transport
The HTTP/S transport sends XML to and from the client/server by
executing a series of HTTP/S post methods (RFC 2616 [1]). You
can perform three posts (submit, query, and action) and receive a
success or failure notification from the RightFax server. All XML
Interface functions are supported.
Each HTTP/S post is formatted with the library name of the
connector (RFWebCon.dll) and the method to be executed stored
in the X-Captaris-Method field. Valid methods are submit, query,
and action. The format of the post line includes standard HTTP
headers as well as XML data.
Figure 9.1 HTTP/HTTPS Transfer Protocol for XML Documents
102
Example HTTP/S Post
Table 9b Example HTTP/S Post
Call
Response
POST /RFWebCon.DLL
HTTP/1.1
HTTP/1.1 200 OK
Host: www.opentext.com
Content-Length: nnnn
Content-Type: text/xml
X-Captaris-Method: submit_reply
Content-Type: text/xml
Content-Length: nnnn
X-Captaris-Method: submit
<XML_FAX_SUBMIT_REPLY>...
</XML_FAX_SUBMIT_REPLY>
<XML_FAX_SUBMIT>...
</XML_FAX_SUBMIT>
text/XML media type listed for its content type is considered the
XML_FAX_SUBMIT document. All other documents within the
MIME message are considered attachments to be included with
the message.
Replies (XML_FAX_REPLY) are never returned as multipart MIME
messages. The data contained within a reply is minimal and does
not include binary attachments.
HTTP or HTTPS notifications
To receive notifications in this manner, you must provide an HTTP
listener. The application Postfile.exe can be used to send
messages from the RightFax server, but it needs the path to the
HTTP listener for you to actually receive the message.
File transport
HTTP/S Attachments
Attachments are valid only for the submit function.
Inline
XML does not support binary data. To be included inline with the
XML, binary attachments must be encoded using BASE64.
BASE64 represents binary data using a 64-character subset of
International Alphabet IA5. For information on implementation
details of BASE64, see RFC 1421 [2].
File transport for XML allows an XML document to be processed
using a command line executable (Parsexml.exe). When combined
with existing RightFax technology, this can be used for printer input,
directory scanning, and various other input methods.
Some methods, such as printer input, do not contain a mechanism
to receive a reply.
Multipart MIME
When attachments are included inline, they significantly increase
the size of the XML message. Some XML parser implementations
load the entire XML message into memory, which causes
performance degradation when large messages are processed.
An alternative to inline attachments is to encapsulate the XML
message and attachment using multipart MIME. Specifically,
multipart or mixed content type is used to separate the XML
document from each attachment. The first attachment with the
Chapter 9
Programming for the RightFax XML Interface
103
OpenText RightFax 10.5 Integration Module Guide
Figure 9.2 File Transfer Protocol for XML Documents
File transport attachments
Attachments are valid only for the submit function.
Inline
XML does not support binary data. To be included inline with the
XML, binary attachments must be encoded using BASE64.
BASE64 represents binary data using a 64-character subset of
International Alphabet IA5. For information on implementation
details of BASE64, see RFC 1421 [2].
File attachments
When attachments are included inline, they significantly increase
the size of the XML message. Some XML parser implementations
load the entire XML message into memory, which causes
performance degradation when large messages are processed. An
alternative to inline attachments is to include them as separate files.
Command line syntax
In the following example command line, po.doc and list.pdf are
attached files:
parseXML [options] <xmlfile> [attachments]
parseXML submit.xml po.doc list.pdf
Example
parseXML submit.xml po.doc list.pdf
Command line options
z
z
z
-q—XML input is Query document. Default is Submit document.
-a—XML input is Action document. Default is Submit document.
-f—<filename> Output reply XML to this file.
IBM WebSphere MQ transport
IBM WebSphere MQ acts as an intermediary in connecting the
host application to the RightFax server software. It offers multiple
connection options and requires some advanced configuration. For
more information, see the IBM’s WebSphere MQ documentation.
104
Figure 9.3 IBM WebSphere MQ Transfer Protocol for XML Documents
Using plain text data
If the data is in plain text (such as .txt) format, then copy the data
straight into the XML nodes, with no additional attributes needed.
Using formatted text data
If the data is formatted text format such as Rich Text Format, then:
1. Use the type attribute, setting it to the extension associated
with that document type.
2. Copy the data into the XML node.
Example: The following example is for a cover sheet in RTF:
IBM WebSphere MQ attachments
Attachments are valid only for the submit function.
<ATTACHMENT>
<COVER_TEXT type=”RTF”>
{\rtf1\ansi\ansicpg1252\deff0\deflang1033{\fonttbl{\f0\fswiss\fch
arset0 Arial;}}
{\*\generator Msftedit 5.41.21.2500;}
\viewkind4\uc1\pard\f0\fs20 The is the text that is printed on the
cover. \par}}
</COVER_TEXT>
</ATTACHMENT>
Inline
XML does not support binary data. To be included inline with the
XML, binary attachments must be encoded using BASE64.
BASE64 represents binary data using a 64-character subset of
International Alphabet IA5. For information on implementation
details of BASE64, see RFC 1421 [2].
Using binary data
If the data is binary, such as Word documents (.doc), Acrobat files
(.pdf), or graphic images (.jpg, .bmp, etc.), then:
1. Encode the data using BASE64 encoding.
2. Use the type attribute, setting it to the extension associated
with that document type.
Understanding Body and Cover Text
Body and cover text is relevant only for the submit function. The
data for the body and cover_text nodes can be any file format. Plain
text (ASCII) allows for the simplest transition to XML, but you can
also use formatted text such as Rich Text Format (.rtf) or binary files
such as Microsoft Word (.doc) documents.
3. Use the encoding attribute, setting it BASE64.
4. Copy the encoded data into the XML node.
Example In the following example, the body text is in Microsoft
Word (.doc) format and the ellipses (...) represent the
many pages that would be contained in an actual Word
file:
Chapter 9
Programming for the RightFax XML Interface
105
OpenText RightFax 10.5 Integration Module Guide
<ATTACHMENT>
<BODY type="DOC" encoding="BASE64">
0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAG
AAAAAAAAAAAAAAABAAAAVgAAAAAAAAAA
EAAAWAAAAAEAAAD+////AAAAAFUAAAD...
aW9uIG9mIGhvdyB0byBkbyB0aGlzLiBOb3RlIHRoYXQgdGhpcy
BpcyBqdXN0IHRoZSBiYXNpY3Mu
DUNyZWF0ZSBhbiBSRmF4U3VibWl0IG9iamVjdC4NU2V0IHRo
...
...
The Schemas
The schemas listed in this section define the structure and type of
content that the RightFax server can accept in XML documents.
When creating an XML document, it must match the applicable
schema described in this section. If the document does not match
the applicable schema, then you must create an XSLT to convert
the document to the RightFax schema. Or, you can create an XSLT
to convert the document directly to FCL. For sample documents,
“Sample Documents Based on the Schemas” on page 117.
...
UmlnaHRGQVggc2VydmVyLCB1c2luZyBzZXRUYXJnZXRVUkwg
bWV0aG9kLiBUaGlzIHRha2VzIGEg
</DATA>
</ATTACHMENT>
XML_FAX_SUBMIT_schema
For a sample document based on this schema, see “XML_FAX_SUBMIT” on page 117.
<?xml version="1.0" encoding="UTF-8" ?>
- <!-rfxml version="2.0.1"
-->
- <Schema name="XML_FAX_SUBMIT" xmlns="urn:schemas-microsoft-com:xml-data" xmlns:dt="urn:schemas-microsoft-com:datatypes">
<ElementType name="SEND_DATE_TIME" model="closed" content="textOnly" dt:type="dateTime.tz" />
<ElementType name="INCLUDE_BEG" model="closed" content="textOnly" dt:type="string" />
<ElementType name="ADD_LIBDOC" model="closed" content="textOnly" dt:type="string" />
<ElementType name="INCLUDE_END" model="closed" content="textOnly" dt:type="string" />
- <!-SENDER element
-->
<ElementType name="FROM_NAME" model="closed" content="textOnly" dt:type="string" />
<ElementType name="EMP_ID" model="closed" content="textOnly" dt:type="string" />
<ElementType name="FROM_COMPANY" model="closed" content="textOnly" dt:type="string" />
<ElementType name="FROM_DEPARTMENT" model="closed" content="textOnly" dt:type="string" />
<ElementType name="FROM_PHONE" model="closed" content="textOnly" dt:type="string" />
106
<ElementType name="RETURN_EMAIL" model="closed" content="textOnly" dt:type="string" />
<ElementType name="BILLINFO1" model="closed" content="textOnly" dt:type="string" />
<ElementType name="BILLINFO2" model="closed" content="textOnly" dt:type="string" />
<ElementType name="REPLY_TO" model="closed" content="textOnly" dt:type="uri" />
<ElementType name="RF_USER" model="closed" content="textOnly" dt:type="string" />
- <ElementType name="SENDER" model="closed" content="eltOnly" order="seq">
<element type="FROM_NAME" minOccurs="0" maxOccurs="1" />
<element type="EMP_ID" minOccurs="0" maxOccurs="1" />
<element type="FROM_COMPANY" minOccurs="0" maxOccurs="1" />
<element type="FROM_DEPARTMENT" minOccurs="0" maxOccurs="1" />
<element type="FROM_PHONE" minOccurs="0" maxOccurs="1" />
<element type="RETURN_EMAIL" minOccurs="0" maxOccurs="1" />
<element type="BILLINFO1" minOccurs="0" maxOccurs="1" />
<element type="BILLINFO2" minOccurs="0" maxOccurs="1" />
<element type="REPLY_TO" minOccurs="0" maxOccurs="1" />
<element type="RF_USER" minOccurs="1" maxOccurs="1" />
</ElementType>
- <!-DESTINATION STUFF
-->
- <!-Common Recipient elements and attributes
-->
<AttributeType name="unique_id" dt:type="string" />
<ElementType name="INCLUDE_INC" model="closed" content="textOnly" dt:type="string" />
<ElementType name="TO_NAME" model="closed" content="textOnly" dt:type="string" />
<ElementType name="INCLUDE_DEF" model="closed" content="textOnly" dt:type="string" />
<ElementType name="TO_COMPANY" model="closed" content="textOnly" dt:type="string" />
<ElementType name="TO_CONTACTNUM" model="closed" content="textOnly" dt:type="string" />
- <ElementType name="NOTIFY_HOST" model="closed" content="empty">
<AttributeType name="SuccessTemplate" dt:type="string" required="yes" />
<AttributeType name="FailureTemplate" dt:type="string" />
<AttributeType name="Name" dt:type="string" required="yes" />
<attribute type="SuccessTemplate" />
<attribute type="FailureTemplate" />
<attribute type="Name" />
</ElementType>
Chapter 9
Programming for the RightFax XML Interface
107
OpenText RightFax 10.5 Integration Module Guide
<ElementType name="COVERSHEET" model="closed" content="textOnly" dt:type="string" />
- <!-FAX element
-->
<ElementType name="ALT_FAX_NUM" model="closed" content="textOnly" dt:type="string" />
<ElementType name="TO_FAXNUM" model="closed" content="textOnly" dt:type="string" />
- <ElementType name="FAX" model="closed" content="eltOnly">
<attribute type="unique_id" />
<element type="TO_FAXNUM" minOccurs="1" maxOccurs="1" />
<element type="INCLUDE_INC" minOccurs="0" maxOccurs="1" />
<element type="TO_NAME" minOccurs="0" maxOccurs="1" />
<element type="TO_COMPANY" minOccurs="0" maxOccurs="1" />
<element type="ALT_FAX_NUM" minOccurs="0" maxOccurs="1" />
<element type="TO_CONTACTNUM" minOccurs="0" maxOccurs="1" />
<element type="NOTIFY_HOST" minOccurs="0" maxOccurs="1" />
<element type="COVERSHEET" minOccurs="0" maxOccurs="1" />
<element type="INCLUDE_DEF" minOccurs="0" maxOccurs="1" />
</ElementType>
- <!-EMAIL element
-->
<ElementType name="SUBJECT" model="closed" content="textOnly" dt:type="string" />
<ElementType name="CC_EMAIL" model="closed" content="textOnly" dt:type="string" />
<ElementType name="BCC_EMAIL" model="closed" content="textOnly" dt:type="string" />
<ElementType name="TO_EMAIL" model="closed" content="textOnly" dt:type="string" />
- <ElementType name="EMAIL" model="closed" content="eltOnly">
<attribute type="unique_id" />
<element type="TO_EMAIL" minOccurs="1" maxOccurs="1" />
<element type="CC_EMAIL" minOccurs="0" maxOccurs="1" />
<element type="SUBJECT" minOccurs="0" maxOccurs="1" />
<element type="TO_NAME" minOccurs="0" maxOccurs="1" />
<element type="TO_COMPANY" minOccurs="0" maxOccurs="1" />
<element type="TO_CONTACTNUM" minOccurs="0" maxOccurs="1" />
<element type="NOTIFY_HOST" minOccurs="0" maxOccurs="1" />
<element type="COVERSHEET" minOccurs="0" maxOccurs="1" />
<element type="INCLUDE_DEF" minOccurs="0" maxOccurs="1" />
<element type="BCC_EMAIL" minOccurs="0" maxOccurs="1" />
108
<element type="INCLUDE_INC" minOccurs="0" maxOccurs="1" />
</ElementType>
- <!-PRINT element
-->
<ElementType name="COPIES" model="closed" content="textOnly" dt:type="i1" />
<ElementType name="PRINTER_NAME" model="closed" content="textOnly" dt:type="string" />
- <ElementType name="PRINT" model="closed" content="eltOnly">
<attribute type="unique_id" />
<element type="PRINTER_NAME" minOccurs="0" maxOccurs="1" />
<element type="COPIES" minOccurs="0" maxOccurs="1" />
<element type="INCLUDE_INC" minOccurs="0" maxOccurs="1" />
<element type="TO_NAME" minOccurs="0" maxOccurs="1" />
<element type="TO_COMPANY" minOccurs="0" maxOccurs="1" />
<element type="TO_CONTACTNUM" minOccurs="0" maxOccurs="1" />
<element type="COVERSHEET" minOccurs="0" maxOccurs="1" />
<element type="INCLUDE_DEF" minOccurs="0" maxOccurs="1" />
</ElementType>
- <ElementType name="DESTINATIONS" model="closed" content="eltOnly">
<element type="FAX" minOccurs="0" maxOccurs="*" />
<element type="EMAIL" minOccurs="0" maxOccurs="*" />
<element type="PRINT" minOccurs="0" maxOccurs="*" />
</ElementType>
- <!-END DESTINATION STUFF
-->
- <!-FORM element
-->
- <ElementType name="FORM" model="closed" content="textOnly" dt:type="string">
<AttributeType name="xcoord" dt:type="number" />
<AttributeType name="ycoord" dt:type="number" />
<attribute type="xcoord" />
<attribute type="ycoord" />
</ElementType>
- <!-ADD_IMAGE element
Chapter 9
Programming for the RightFax XML Interface
109
OpenText RightFax 10.5 Integration Module Guide
-->
- <ElementType name="ADD_IMAGE" model="closed" content="textOnly" dt:type="string">
<AttributeType name="page" dt:type="enumeration" dt:values="CURRENT ALL LAST" />
<AttributeType name="xoffset" dt:type="i1" />
<AttributeType name="yoffset" dt:type="i1" />
<attribute type="page" default="CURRENT" />
<attribute type="xoffset" />
<attribute type="yoffset" />
</ElementType>
- <!-BODY and COVER_TEXT common attributes
-->
<AttributeType name="type" dt:type="string" />
<AttributeType name="encoding" dt:type="enumeration" dt:values="NONE BASE64 QUOTEDPRINTABLE" />
- <!-COVER_TEXT element
-->
- <ElementType name="COVER_TEXT" model="closed" content="textOnly" dt:type="string">
<attribute type="type" default="TXT" />
<attribute type="encoding" />
</ElementType>
- <!-BODY element
-->
- <ElementType name="BODY" model="closed" content="mixed">
<element type="FONT" minOccurs="0" maxOccurs="1" />
<AttributeType name="tm" dt:type="r4" />
<AttributeType name="lm" dt:type="r4" />
<AttributeType name="bm" dt:type="r4" />
<AttributeType name="font_name" dt:type="string" />
<AttributeType name="font_size" dt:type="i1" />
<AttributeType name="font_leading" dt:type="i1" />
<AttributeType name="font_pitch" dt:type="i1" />
<attribute type="type" default="TXT" />
<attribute type="encoding" />
<attribute type="tm" />
<attribute type="lm" />
110
<attribute type="bm" />
<attribute type="font_name" />
<attribute type="font_size" />
<attribute type="font_leading" />
<attribute type="font_pitch" />
</ElementType>
- <ElementType name="FONT" content="empty">
<AttributeType name="name" dt:type="string" required="yes" />
<AttributeType name="size" dt:type="i1" />
<AttributeType name="leading" dt:type="i1" />
<AttributeType name="pitch" dt:type="i1" />
<attribute type="name" />
<attribute type="size" />
<attribute type="leading" />
<attribute type="pitch" />
</ElementType>
- <!-ATTACHMENT element
-->
- <ElementType name="ATTACHMENT" model="closed" content="eltOnly" order="one">
<element type="DATA" />
<element type="FILE" />
</ElementType>
- <ElementType name="DATA" model="closed" content="textOnly" dt:type="string">
<attribute type="type" default="TXT" />
<attribute type="encoding" default="NONE" />
</ElementType>
- <ElementType name="FILE" model="closed" content="empty">
<AttributeType name="path" dt:type="string" required="yes" />
<AttributeType name="delete" dt:type="string" required="no" />
<attribute type="path" />
<attribute type="delete" />
</ElementType>
- <!-Root element
-->
- <ElementType name="XML_FAX_SUBMIT" model="closed" content="eltOnly" order="seq">
Chapter 9
Programming for the RightFax XML Interface
111
OpenText RightFax 10.5 Integration Module Guide
<AttributeType name="java" dt:type="boolean" />
<AttributeType name="stylesheet" dt:type="string" />
<attribute type="java" default="0" />
<attribute type="stylesheet" default="XML_FAX_SUBMIT.XSL" />
<element type="SEND_DATE_TIME" minOccurs="0" maxOccurs="1" />
<element type="INCLUDE_BEG" minOccurs="0" maxOccurs="1" />
<element type="SENDER" minOccurs="0" maxOccurs="1" />
<element type="DESTINATIONS" minOccurs="1" maxOccurs="1" />
<element type="FORM" minOccurs="0" maxOccurs="1" />
<element type="ADD_IMAGE" minOccurs="0" maxOccurs="1" />
<element type="COVER_TEXT" minOccurs="0" maxOccurs="1" />
<element type="BODY" minOccurs="0" maxOccurs="1" />
<element type="ATTACHMENT" minOccurs="0" maxOccurs="*" />
<element type="ADD_LIBDOC" minOccurs="0" maxOccurs="1" />
<element type="INCLUDE_END" minOccurs="0" maxOccurs="1" />
</ElementType>
</Schema>
XML_FAX_SUBMIT_REPLY.dtd
For an example document based on this dtd, see “XML_FAX_SUBMIT_REPLY” on page 120.
<!ELEMENT XML_FAX_SUBMIT_REPLY (FAX+)>
<!ATTLIST FAX unique_id CDATA #REQUIRED>
<!ELEMENT FAX (RETURN_CODE, MESSAGE)>
<!ELEMENT RETURN_CODE (#PCDATA)>
<!ELEMENT MESSAGE (#PCDATA)>
XML_FAX_QUERY_schema
For an example document based on this schema, see “XML_FAX_QUERY” on page 120.
<?xml version=”1.0”?>
<Schema xmlns=”urn:schemas-microsoft-com:xml-data” xmlns:dt=”urn:schemas-microsoft-com:datatypes”>
<ElementType name=”UNIQUE_ID” content=”textOnly”/>
<AttributeType name =”start” dt:type=”datetime.tz” required=”yes”/>
<AttributeType name =”end” dt:type=”datetime.tz” required=”yes”/>
<ElementType name=”DATE_RANGE” content=”textOnly”>
<attribute type=”start”/>
112
<attribute type=”end”/>
</ElementType>
<AttributeType name=”faxtype” dt:type=”enumeration” dt:values=”OUTBOUND INBOUND BOTH”/>
<ElementType name=”TO_FAXNUM” content=”textOnly”/>
<ElementType name=”RF_USER” content=”textOnly”/>
<ElementType name=”STATUS” content=”textOnly”/>
<ElementType name=”QUERY” content=”eltOnly”>
<attribute type=”faxtype” default=”OUTBOUND”/>
<element type=”UNIQUE_ID” minOccurs='0' maxOccurs='1'/>
<element type=”DATE_RANGE” minOccurs='0' maxOccurs='1'/>
<element type=”TO_FAXNUM” minOccurs='0' maxOccurs='1'/>
<element type=”RF_USER” minOccurs='0' maxOccurs='1'/>
<element type=”STATUS” minOccurs='0' maxOccurs='1'/>
</ElementType>
<ElementType name=”QUERIES” content=”eltOnly”>
<element type=”QUERY” minOccurs='1' maxOccurs='*'/>
</ElementType>
<ElementType name=”XML_FAX_QUERY” content=”eltOnly”>
<element type=”QUERIES”/>
</ElementType>
</Schema>
XML_FAX_QUERY_REPLY.dtd
For an example document based on this dtd, see “XML_FAX_QUERY_REPLY” on page 121.
<!ELEMENT XML_FAX_QUERY_REPLY (MESSAGE?, FAXSTATUS*)>
<!ELEMENT MESSAGE (#PCDATA)>
<!ELEMENT FAXSTATUS (STATUS_CODE, STATUS_MSG, ERROR_CODE, DISPOSITION, TERMSTAT, OWNER_ID, TO_FAXNUM,
TO_CONTACTNUM, TO_NAME, TO_COMPANY, TO_CITYSTATE, FROM_NAME, FROM_PHONENUM, BILLINFO1, BILLINFO2,
CREATE_DATETIME, SENDTIME, REMOTEID, SEND_DATETIME, SEND_CHANNEL, CUSTOM1)>
<!ATTLIST FAXSTATUS unique_id CDATA #REQUIRED>
<!ATTLIST FAXSTATUS query_id CDATA #IMPLIED>
<!ELEMENT STATUS_CODE (#PCDATA)>
<!ELEMENT STATUS_MSG (#PCDATA)>
<!ELEMENT ERROR_CODE (#PCDATA)>
<!ELEMENT DISPOSITION (#PCDATA)>
<!ELEMENT TERMSTAT (#PCDATA)>
Chapter 9
Programming for the RightFax XML Interface
113
OpenText RightFax 10.5 Integration Module Guide
<!ELEMENT OWNER_ID (#PCDATA)>
<!ELEMENT TO_FAXNUM (#PCDATA)>
<!ELEMENT TO_CONTACTNUM (#PCDATA)>
<!ELEMENT TO_NAME (#PCDATA)>
<!ELEMENT TO_COMPANY (#PCDATA)>
<!ELEMENT TO_CITYSTATE (#PCDATA)>
<!ELEMENT FROM_NAME (#PCDATA)>
<!ELEMENT FROM_PHONENUM (#PCDATA)>
<!ELEMENT BILLINFO1 (#PCDATA)>
<!ELEMENT BILLINFO2 (#PCDATA)>
<!ELEMENT CREATE_DATETIME (#PCDATA)>
<!ELEMENT SENDTIME (#PCDATA)>
<!ELEMENT REMOTEID (#PCDATA)>
<!ELEMENT SEND_DATETIME (#PCDATA)>
<!ELEMENT SEND_CHANNEL (#PCDATA)>
<!ELEMENT CUSTOM1 (#PCDATA)>
XML_FAX_ACTION_schema
For an example document based on this schema, see “XML_FAX_ACTION” on page 122.
<?xml version=”1.0”?>
<Schema xmlns=”urn:schemas-microsoft-com:xml-data” xmlns:dt=”urn:schemas-microsoft-com:datatypes”>
<ElementType name=”TO_NAME” content=”textOnly”/>
<ElementType name=”TO_COMPANY” content=”textOnly”/>
<ElementType name=”ALT_FAX_NUM” content=”textOnly”/>
<ElementType name=”TO_CONTACTNUM” content=”textOnly”/>
<ElementType name=”COVERSHEET” content=”textOnly”/>
<ElementType name=”TO_FAXNUM” content=”textOnly”/>
<ElementType name=”FAX_RECIPIENT” content=”eltOnly”>
<element type=”TO_NAME” minOccurs='0' maxOccurs='1'/>
<element type=”TO_COMPANY” minOccurs='0' maxOccurs='1'/>
<element type=”ALT_FAX_NUM” minOccurs='0' maxOccurs='1'/>
<element type=”TO_CONTACTNUM” minOccurs='0' maxOccurs='1'/>
<element type=”COVERSHEET” minOccurs='0' maxOccurs='1'/>
<element type=”TO_FAXNUM” />
</ElementType>
<ElementType name=”ID” content=”textOnly”/>
114
<ElementType name=”DESCRIPTION” content=”textOnly”/>
<ElementType name=”DELETE” content=”empty”/>
<ElementType name=”FORWARD” content=”eltOnly”>
<element type=”FAX_RECIPIENT” minOccurs='1' maxOccurs='*'/>
</ElementType>
<ElementType name=”CREATE_LIB_DOC” content=”eltOnly”>
<element type=”ID” minOccurs='1' maxOccurs='1'/>
<element type=”DESCRIPTION” minOccurs='1' maxOccurs='1'/>
</ElementType>
<AttributeType name =”unique_id” dt:type=”string” required=”yes”/>
<!--Had to make this ”closed” and set order to ”one” so that only one or the other of child elements can occur-->
<ElementType name=”FAX” model=”closed” content=”eltOnly” order=”one”>
<attribute type=”unique_id”/>
<element type=”DELETE”/>
<element type=”FORWARD”/>
<element type=”CREATE_LIB_DOC”/>
</ElementType>
<AttributeType name =”docid” dt:type=”string”/>
<ElementType name=”XML_FAX_ACTION” content=”eltOnly”>
<element type=”FAX” minOccurs='1' maxOccurs='*'/>
</ElementType>
</Schema>
XML_FAX_ACTION_REPLY.dtd
For an example document based on this dtd, see “XML_FAX_ACTION_REPLY” on page 122.
<!ELEMENT XML_FAX_ACTION (FAX+)>
<!ELEMENT FAX (DELETE | FORWARD)>
<!ATTLIST FAX unique_id CDATA #REQUIRED>
<!ELEMENT DELETE EMPTY>
<!ELEMENT FORWARD FAX_RECIPIENT+>
<!ELEMENT FAX_RECIPIENT (TO_NAME?, TO_COMPANY?, ALT_FAX_NUM?, TO_CONTACTNUM?, COVERSHEET?, TO_FAXNUM)>
<!ELEMENT TO_NAME (#PCDATA)>
<!ELEMENT TO_COMPANY (#PCDATA)>
<!ELEMENT ALT_FAX_NUM (#PCDATA)>
Chapter 9
Programming for the RightFax XML Interface
115
OpenText RightFax 10.5 Integration Module Guide
<!ELEMENT TO_CONTACTNUM (#PCDATA)>
<!ELEMENT COVERSHEET (#PCDATA)>
<!ELEMENT TO_FAXNUM (#PCDATA)>
XML_FAX_NOTIFICATION.dtd
For an example document based on this dtd, see “XML_FAX_NOTIFICATION” on page 123.
<!ELEMENT XML_FAX_NOTIFICATION (FAXSTATUS*)>
<!ELEMENT FAXSTATUS (STATUS_CODE, STATUS_MSG, ERROR_CODE, DISPOSITION, TERMSTAT, OWNER_ID, TO_FAXNUM,
TO_CONTACTNUM, TO_NAME, TO_COMPANY, TO_CITYSTATE, FROM_NAME, FROM_PHONENUM, BILLINFO1, BILLINFO2,
CREATE_DATETIME, SENDTIME, REMOTEID, SEND_DATETIME, SEND_CHANNEL, CUSTOM1)>
<!ATTLIST FAXSTATUS unique_id CDATA #REQUIRED>
<!ELEMENT STATUS_CODE (#PCDATA)>
<!ELEMENT STATUS_MSG (#PCDATA)>
<!ELEMENT ERROR_CODE (#PCDATA)>
<!ELEMENT DISPOSITION (#PCDATA)>
<!ELEMENT TERMSTAT (#PCDATA)>
<!ELEMENT OWNER_ID (#PCDATA)>
<!ELEMENT TO_FAXNUM (#PCDATA)>
<!ELEMENT TO_CONTACTNUM (#PCDATA)>
<!ELEMENT TO_NAME (#PCDATA)>
<!ELEMENT TO_COMPANY (#PCDATA)>
<!ELEMENT TO_CITYSTATE (#PCDATA)>
<!ELEMENT FROM_NAME (#PCDATA)>
<!ELEMENT FROM_PHONENUM (#PCDATA)>
<!ELEMENT BILLINFO1 (#PCDATA)>
<!ELEMENT BILLINFO2 (#PCDATA)>
<!ELEMENT CREATE_DATETIME (#PCDATA)>
<!ELEMENT SENDTIME (#PCDATA)>
<!ELEMENT REMOTEID (#PCDATA)>
<!ELEMENT SEND_DATETIME (#PCDATA)>
<!ELEMENT SEND_CHANNEL (#PCDATA)>
<!ELEMENT CUSTOM1 (#PCDATA)>
116
Sample Documents Based on the Schemas
This section lists sample documents based on the XML Interface
schemas and corresponding DTDs. For the schemas and DTDs,
see “The Schemas” on page 106.
Warning For example documents that require a name space (e.g.,
<XML_FAX_SUBMIT stylesheet=”XML_FAX_SUBMIT.XSL”
xmlns=”namespace”>), the name space you write must exactly match the
corresponding name space in the XSLT file. If it does not, the FCL
documents that appear in the inbox will be empty.
XML_FAX_SUBMIT
<?xml version="1.0"?>
<!--rfxml version="2.0.1" -->
<XML_FAX_SUBMIT stylesheet="XML_FAX_SUBMIT.XSL" xmlns="x-schema:../schemas/XML_FAX_SUBMIT_schema.xml">
<SEND_DATE_TIME>2000-01-24T15:20:00-08:00</SEND_DATE_TIME>
<INCLUDE_BEG>xml.beg</INCLUDE_BEG>
<SENDER>
<FROM_NAME>Bob McKenzie</FROM_NAME>
<EMP_ID>555-66-7777</EMP_ID>
<FROM_COMPANY>Company, ltd.</FROM_COMPANY>
<FROM_DEPARTMENT>Store</FROM_DEPARTMENT>
<FROM_PHONE>555-9876</FROM_PHONE>
<RETURN_EMAIL>[email protected]</RETURN_EMAIL>
<BILLINFO1>12345</BILLINFO1>
<BILLINFO2>678dk</BILLINFO2>
<REPLY_TO>http://www.company.com/faxreply</REPLY_TO>
<RF_USER>bobm</RF_USER>
</SENDER>
<DESTINATIONS>
<FAX unique_id="PRODXML:0001">
<TO_FAXNUM>555-1111</TO_FAXNUM>
<INCLUDE_INC>xml.inc</INCLUDE_INC>
<TO_NAME>Fred Flintstone</TO_NAME>
<TO_COMPANY>Acme, Inc.</TO_COMPANY>
<ALT_FAX_NUM>555-1112</ALT_FAX_NUM>
Chapter 9
Programming for the RightFax XML Interface
117
OpenText RightFax 10.5 Integration Module Guide
<TO_CONTACTNUM>555-6543</TO_CONTACTNUM>
<NOTIFY_HOST SuccessTemplate="XML_FAX_NOTIFICATION.inc" FailureTemplate="XML_FAX_NOTIFICATION.inc" Name="XMLNotify"/>
<COVERSHEET>auto.cov</COVERSHEET>
<INCLUDE_DEF>xml.def</INCLUDE_DEF>
</FAX>
<FAX unique_id="PRODXML:0002">
<TO_FAXNUM>555-1234</TO_FAXNUM>
<TO_NAME>Bill Smith</TO_NAME>
</FAX>
<EMAIL unique_id="PRODXML:0003">
<TO_EMAIL>[email protected]</TO_EMAIL>
<CC_EMAIL>[email protected]</CC_EMAIL>
<BCC_EMAIL>[email protected]</BCC_EMAIL>
</EMAIL>
<PRINT unique_id="PRODXML:0003">
<PRINTER_NAME>Dev1</PRINTER_NAME>
<COPIES>2</COPIES>
<INCLUDE_INC>xml.inc</INCLUDE_INC>
<TO_NAME>Bill Smith</TO_NAME>
<TO_COMPANY>Acme, Inc.</TO_COMPANY>
<TO_CONTACTNUM>555-6545</TO_CONTACTNUM>
<COVERSHEET>auto.cov</COVERSHEET>
<INCLUDE_DEF>xml.def</INCLUDE_DEF>
</PRINT>
</DESTINATIONS>
<FORM xcoord="0.5" ycoord="1.0">form.inc</FORM>
<ADD_IMAGE page="CURRENT" xoffset="2" yoffset="4">simpsons2.tif</ADD_IMAGE>
<COVER_TEXT type="TXT" encoding="NONE">
This is a line of text for the cover sheet.
Here is another line of cover text.
</COVER_TEXT>
<BODY type="TXT" encoding="NONE" tm="1" lm="1" bm="1" font_name="Arial" font_size="10" font_leading="12" font_pitch="12">
Info for body of the fax
&lt; &gt;
More More More
</BODY>
<ATTACHMENT>
118
<DATA type="RTF" encoding="NONE">
\rtf1\ansi\ansicpg1252\deff0\deflang1033{\fonttbl{\f0\fswiss\fcharset0 Arial;}}
{\*\generator Msftedit 5.41.21.2500;}\viewkind4\uc1\pard\f0\fs20 Put this text into the document as an attachment.\par}
</DATA>
</ATTACHMENT>
<!-- ( this attachment is commented out )
Doc files are done the same way except that they must be BASE64 encoded using Encode64.exe first.
<ATTACHMENT>
<DATA type="DOC" encoding="BASE64">
0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAGAAAAAAAAAAAAAAABAAAAVgAAAAAAAAAA
EAAAWAAAAAEAAAD+////AAAAAFUAAAD/////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////s
pcEATSAJBAAA8BK/AAAAAAAAEAAAAAAABAAAUTIAAA4AYmpiauI94j0AAAAAAAAAAAAAAAAAAAAA
AAAJBBYALloAAIBXAACAVwAAUS4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD//w8AAAAA
( ... Cut many pages of BASE64 encoded data ... )
aW9uIG9mIGhvdyB0byBkbyB0aGlzLiBOb3RlIHRoYXQgdGhpcyBpcyBqdXN0IHRoZSBiYXNpY3Mu
DUNyZWF0ZSBhbiBSRmF4U3VibWl0IG9iamVjdC4NU2V0IHRoZSB0YXJnZXQgVVJMIGZvciB0aGUg
UmlnaHRGQVggc2VydmVyLCB1c2luZyBzZXRUYXJnZXRVUkwgbWV0aG9kLiBUaGlzIHRha2VzIGEg
</DATA>
</ATTACHMENT>
( comment ends ) -->
<ATTACHMENT>
<FILE path="eagle.tif" delete="yes"/>
</ATTACHMENT>
Chapter 9
Programming for the RightFax XML Interface
119
OpenText RightFax 10.5 Integration Module Guide
<ATTACHMENT>
<FILE path="eagle2.tif"/>
</ATTACHMENT>
<ADD_LIBDOC>TANDC1</ADD_LIBDOC>
<INCLUDE_END>xml.end</INCLUDE_END>
</XML_FAX_SUBMIT>
XML_FAX_SUBMIT_REPLY
<?xml version=”1.0” ?>
<XML_FAX_SUBMIT_REPLY>
<FAX unique_id=”PRODXML:2055”>
<RETURN_CODE>1</RETURN_CODE>
<MESSAGE>Document has been successfully submitted for sending.</MESSAGE>
</FAX>
</XML_FAX_SUBMIT_REPLY>
XML_FAX_QUERY
<?xml version=”1.0” ?>
<XML_FAX_QUERY xmlns=”x-schema:../schemas/XML_FAX_QUERY_schema.xml”>
<QUERIES>
<QUERY faxtype=”INBOUND”>
<UNIQUE_ID>PRODXML:0001</UNIQUE_ID>
<DATE_RANGE start=”2000-03-08T18:39:09-08:00” end=”2000-03-10T18:39:09-08:00”/>
<TO_FAXNUM>555-1111</TO_FAXNUM>
<RF_USER>bobm</RF_USER>
<STATUS>0</STATUS>
</QUERY>
<QUERY faxtype=”OUTBOUND”>
<UNIQUE_ID>PRODXML:0002</UNIQUE_ID>
<DATE_RANGE start=”2000-03-08T18:39:09-08:00” end=”2000-03-10T18:39:09-08:00”/>
<TO_FAXNUM>555-1112</TO_FAXNUM>
<RF_USER>dougm</RF_USER>
<STATUS>0</STATUS>
</QUERY>
<QUERY faxtype=”BOTH”>
<UNIQUE_ID>PRODXML:0003</UNIQUE_ID>
120
<DATE_RANGE start=”2000-03-08T18:39:09-08:00”
end=”2000-03-10T18:39:09-08:00”/>
<TO_FAXNUM>555-1113</TO_FAXNUM>
<RF_USER>dougm</RF_USER>
<STATUS>0</STATUS>
</QUERY>
</QUERIES>
</XML_FAX_QUERY>
XML_FAX_QUERY_REPLY
<?xml version=”1.0” ?>
<XML_FAX_QUERY_REPLY>
<FAXSTATUS unique_id=”PRODXML:2055” query_id=”1”>
<STATUS_CODE>6</STATUS_CODE>
<STATUS_MSG>OK</STATUS_MSG>
<ERROR_CODE>0</ERROR_CODE>
<DISPOSITION>0</DISPOSITION>
<TERMSTAT>32</TERMSTAT>
<OWNER_ID>XMLACCOUNT</OWNER_ID>
<TO_FAXNUM>5039689601</TO_FAXNUM>
<TO_CONTACTNUM />
<TO_NAME>Unknown</TO_NAME>
<TO_COMPANY />
<TO_CITYSTATE />
<FROM_NAME />
<FROM_PHONENUM>(999) 999-9999</FROM_PHONENUM>
<BILLINFO1 />
<BILLINFO2 />
<CREATE_DATETIME>957444538</CREATE_DATETIME>
<SENDTIME>30</SENDTIME>
<REMOTEID>TEST computer</REMOTEID>
<SEND_DATETIME>957444538</SEND_DATETIME>
<SEND_CHANNEL>0</SEND_CHANNEL>
<CUSTOM1>0</CUSTOM1>
</FAXSTATUS>
</XML_FAX_QUERY_REPLY>
Chapter 9
Programming for the RightFax XML Interface
121
OpenText RightFax 10.5 Integration Module Guide
XML_FAX_ACTION
<?xml version=”1.0” ?>
<XML_FAX_ACTION xmlns=”x-schema:../schemas/XML_FAX_ACTION_schema.xml”>
<FAX unique_id=”PRODXML:0001”>
<DELETE/>
</FAX>
<FAX unique_id=”PRODXML:0002”>
<FORWARD>
<FAX_RECIPIENT>
<TO_NAME>Fred Flintstone</TO_NAME>
<TO_COMPANY>Acme, Inc.</TO_COMPANY>
<ALT_FAX_NUM>555-1112</ALT_FAX_NUM>
<TO_CONTACTNUM>555-6543</TO_CONTACTNUM>
<COVERSHEET>auto.cov</COVERSHEET>
<TO_FAXNUM>555-1111</TO_FAXNUM>
</FAX_RECIPIENT>
</FORWARD>
</FAX>
<FAX unique_id=”PRODXML:0003”>
<CREATE_LIB_DOC>
<ID>TANDC</ID>
<DESCRIPTION>This is a terms and conditions document.</DESCRIPTION>
</CREATE_LIB_DOC>
</FAX>
</XML_FAX_ACTION>
XML_FAX_ACTION_REPLY
<?xml version=”1.0” ?>
<XML_FAX_ACTION_REPLY>
<ACTION_STATUS faxid=”PRODXML:2055”>
<RETURN_CODE>1</RETURN_CODE>
<STATUS>Fax (PRODXML:2055) had been submitted for forwarding to: Acme Chemicals</STATUS>
</ACTION_STATUS>
</XML_FAX_ACTION_REPLY>
122
XML_FAX_NOTIFICATION
<?xml version=”1.0” ?>
<!DOCTYPE XML_FAX_NOTIFICATION SYSTEM ”dtds/XML_FAX_NOTIFICATION.dtd”>
<XML_FAX_NOTIFICATION>
<FAXSTATUS unique_id=”PRODXML:0001” query_id=”1”>
<STATUS_CODE>0</STATUS_CODE>
<STATUS_MSG>It is fine</STATUS_MSG>
<ERROR_CODE></ERROR_CODE>
<DISPOSITION></DISPOSITION>
<TERMSTAT></TERMSTAT>
<OWNER_ID></OWNER_ID>
<TO_FAXNUM></TO_FAXNUM>
<TO_CONTACTNUM></TO_CONTACTNUM>
<TO_NAME></TO_NAME>
<TO_COMPANY></TO_COMPANY>
<TO_CITYSTATE></TO_CITYSTATE>
<FROM_NAME></FROM_NAME>
<FROM_PHONENUM></FROM_PHONENUM>
<BILLINFO1></BILLINFO1>
<BILLINFO2></BILLINFO2>
<CREATE_DATETIME></CREATE_DATETIME>
<SENDTIME></SENDTIME>
<REMOTEID></REMOTEID>
<SEND_DATETIME></SEND_DATETIME>
<SEND_CHANNEL></SEND_CHANNEL>
<CUSTOM1></CUSTOM1>
</FAXSTATUS>
</XML_FAX_NOTIFICATION>
Chapter 9
Programming for the RightFax XML Interface
123
OpenText RightFax 10.5 Integration Module Guide
To test using the sample files:
1. In Enterprise Fax Manager stop the Integration Module service.
2. Open a command prompt.
3. Navigate to ..\RightFax\Production\bin.
4. At the prompt type: “parseXML “.
5. Paste the path and file name of the
XML_FAX_SUBMIT_minimum.xml file after “parseXML.” You
can do this by opening Windows Explorer onto the folder
containing that file, then dragging and dropping the file onto the
command line. The file’s default location is
..\RightFax\Production\xml\examples\
6. Hit Enter
If the test is successful you can go to ..\RightFax\Production\Inbox
and find an .fcl file there. Inspect this file, and you’ll see that the xml
input has been transformed into fcl output. You may also do this
with the XML_FAX_SUBMIT.xml sample file. If there is no file in the
Inbox, double check that the Integration Module is stopped. If it
isn’t, it will have picked up, processed, and deleted the .fcl file.
If the test is not successful there will be an error.fcl file in the Inbox.
This will give you some good clues as to what went wrong.
124
Chapter 10
Creating FCL Documents
To create documents with FCL, insert FCL commands into the data
stream that comes from the host application. When the Integration
Module receives this data stream, it uses the FCL commands in
combination with the configured RightFax Integration Module
defaults to format and send the document.
Because of the range of host-based applications, system
environments, and document formats, specific instructions for
accessing and manipulating document data is beyond the scope of
this guide.
Understanding the Format of FCL Commands
All FCL commands begin with two left braces ({{) and end with two
right braces (}}). Many of them also include arguments and
variables, such as a delivery type or a fax number, within the braces.
Each FCL document must have at least one {{begin}} and one
{{end}} command. The Integration Module will process all the data
that appears between a {{begin}} and an {{end}} command as a
discreet document. FCL documents may contain multiple {{begin}}
and {{end}} commands, where the FCL between each set of
commands will be rendered as a separate page. Data that does not
appear between {{begin}} and {{end}} commands is ignored.
For each document, you must also specify how the document will
be processed. You can do this with either the {{fax}} command or
the {{type}} command. The {{fax}} command must include either
the fax number or, if you have licensed the InternetLink Module, an
email address.
The FCL must also comply with any other RightFax requirements as
defined in your implementation of RightFax. For example, if you
require a billing code before sending a fax, the FCL must also
include a billing code with either the {{billing}} or {{billing2}}
commands.
You can list several FCL commands in a sequence. Do not type
spaces between the commands in a line.
For example:
{{begin}}{{fax 503-555-1234}}
{{attach ptc6mos.xls}}{{onerror fax 555-6892}}
{{end}}
This example converts the spreadsheet ptc6mos.xls to a TIFF, then
faxes it to 503-555-1234. If this fax does not go through
successfully, the entire fax will be sent to 555-6892. All other
functionality, such as margins, image quality, and notifications, will
use the values as set in the RightFax EFM Integration Module
Configuration window.
For a detailed list of available FCL commands, see Appendix B,
“FCL Commands”.
125
OpenText RightFax 10.5 Integration Module Guide
Setting Defaults for FCL Documents
Use the Integration Module Configuration program to set most
default values. In many cases, you can override the default in
specific documents by including FCL commands in the document
data from the host application.
Setting General Defaults
1. In the left pane, click General. The General settings appear in
the right pane.
Figure 10.1 General settings
You can also set defaults for things like margins and fonts by
inserting relevant FCL commands in a global include file. For
information on include files, see Chapter 5, ”Reusing FCL
Commands Across Many Documents”.
Opening the Integration Module Configuration Program
1. On the Start menu, select Programs > RightFax > Enterprise
Fax 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-click Integration Module. The
Integration Module Configuration window appears.
2. In the Company name box, enter a name to appear on the
cover sheet of each sent fax. Usually this is the company name.
This setting can be overridden for a document with the {{rti}}
command. For more information on this command, see
Appendix B, “FCL Commands”.
3. In the CSID box, enter a voice telephone number to appear on
the cover sheet of each sent fax. This is usually the telephone
number for the company.
This setting can be overridden for a document with the {{csi}}
command. For more information on this command, see
Appendix B, “FCL Commands”.
126
4. In the Default cover page box, enter the file name for a cover
sheet. Enter none for no cover sheet. For more information on
cover sheets, see Chapter 6, ”Creating and Attaching Cover
Sheets and Other Files”.
5. In the Default Printer box, specify the printer to use for printing
Setting Defaults for FCL Processing
1. In the left pane, click FCL Processor. The FCL Processor
settings appear in the right pane.
Figure 10.2 The FCL Processor Settings
documents when an error is encountered or when printing a
document with the {{type print}} FCL command. Enter a printer
that 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 for
faxes.
z
z
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. See ”Setting Fax Image Quality” on
page 70.
7. In the Event Log Level box, select the level of reporting to the
Windows Event Log.
z
z
z
z
None - records no errors
Terse - records critical errors only
Normal - records the most significant events only and is the
correct setting for normal use
Verbose - records all significant events and is the most useful
for tracking and resolving problems
Caution If this value is set to verbose indefinitely, the event log can
become 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 the
2. In the Units of measure box, specify the unit of measurement
that will be used for indentation, page length, and for FCL
commands. With FCL commands, this setting is used to specify
the x- and y-coordinates for placing data on a page. This setting
can be overridden for a document with the {{units}} command.
For more information on this command, see Appendix B, “FCL
Commands”.
3. In the Indentation box, specify the indentation of the fax image
on the left side of the page. The unit of measurement is
determined by the Units of measure setting.
RightFax server.
Chapter 10
Creating FCL Documents
127
OpenText RightFax 10.5 Integration Module Guide
4. In the Page length box, enter the maximum page length for a
fax. 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 of
measure setting.
5. In the Maximum attached pages box, specify the maximum
number of attached pages for each fax. The Integration Module
can attach up to 1024 pages to a fax.
6. By default, attached documents that are 300 dots-per-inch will
be faxed as two pages. To reduce the image size and send the
image as one page, select the check box Shrink 300 DPI files
to fit page.
7. In the Minimum page length box, specify the minimum page
length for faxes. This setting ensures that a fax with very little
data is printed on a page that is long enough, so that it does not
get lost or discarded by the recipient. The unit of measurement
is 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 this
data is not sent. To remove this data from the fax, select the
Trim trailing white space check box.
Sending Basic FCL Jobs
The complete list of FCL commands is in alphabetic order in
Appendix B, “FCL Commands”. The following examples
demonstrate how to use the FCL commands in combination to
send single faxes, to broadcast faxes, and to use cover sheets.
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 FCL
document that is addressed to 503-555-4489.
{{begin}}
{{fax 503-555-4489}}
Body of the document to be sent.
{{end}}
You can insert the {{altfax}} command as a backup fax number if the
primary number fails:
{{begin}}
{{fax 503-555-4489}}
{{altfax 503-555-5240}}
Body of the document to be sent.
{{end}}
Sending One Document to Many Recipients
Sending the same document to more than one recipient is called
broadcasting. Broadcasting with FCL is accomplished by including
additional {{fax}} commands just before the end of the FCL
document. Open Text recommends that each {{fax}} command be
followed by a {{company}} command for tracking purposes. Each
broadcast document is issued its own document number and is
treated as a separate entity for tracking and retry purposes.
Note Some restrictions exist for using cover sheets when you send
documents to multiple recipients. See ”Using Cover Sheets in a
Broadcast” on page 130..
When the Integration Module encounters a second fax number in a
document, it determines that the document is complete, writes the
current page to the disk and schedules it to be sent to the
preceding fax number. This process continues for each subsequent
fax number, and the Integration Module makes links between
documents to keep disk usage at a minimum. An {{end}} command
completes the loop for the final fax number.
128
Place the {{fax}} command first in each command on each line in an
FCL document.
Correct
Figure 10.3 Broadcast Documents with an {{Include}} Command
{{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 FCL
commands that are listed in a line.
Correct
{{fax 503-555-3829}}{{company Acura of Salem}}
Incorrect {{fax 503-555-3829}} {{company Acura of Salem}}
The following example shows a single-page document to be
broadcast to three recipients.
{{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}}
Broadcast Faxing With an Include File
A list of fax numbers can be associated with a document by using
an include file. An include file can contain a list of FCL commands
or data, and it is linked to a document with the {{include}}
command.
“Figure 10.3: Broadcast Documents with an {{Include}}
Command” shows the same broadcast document with an
{{include}} command that inserts multiple addresses, instead of the
addresses themselves.
Chapter 10
Creating FCL Documents
129
OpenText RightFax 10.5 Integration Module Guide
In “Figure 10.3: Broadcast Documents with an {{Include}}
Command”, the {{include}} command in the original data is
replaced by the list of addresses found in the file
WestCoastCustomers.inc. By having multiple broadcast include
files stored on the Integration Module, you can easily broadcast a
document to whatever group of numbers you choose.
Example To create a file called dealers.inc in the
RightFax\Production\Include folder, send the following
document to the Integration Module,
{{begin}}{{list dealers.inc}}
{{fax 503-555-0912}}{{company ABSOLUTE
WHOLESALE}}
{{fax 503-555-7609}}{{company ACURA OF SALEM}}
{{fax 555-8985}}{{company ACURA OF PORTLAND}}
{{fax 541-555-8160}}{{company ACURA OF
EUGENE}}
{{fax 503-555-4911}}{{company HUTCHISON CO.}}
{{end}}
Example The following example sends the same fax to all fax
numbers stored in the file called dealers.inc.
{{begin}}
{{include dealers.inc}}
{{form invoice.tif}}
Host data.
{{end}}
The resulting file Dealers.inc contains the following
information:
Creating a broadcast list
{{fax 503-555-0912}}{{company ABSOLUTE
WHOLESALE}}
{{fax 503-555-7609}}{{company ACURA OF SALEM}}
{{fax 555-8985}}{{company ACURA OF PORTLAND}}
{{fax 541-555-8160}}{{company ACURA OF
EUGENE}}
{{fax 503-555-4911}}{{company HUTCHISON CO.}}
There are two ways to create an include file that contains a
broadcast list:
z
z
Create a list of FCL commands in any word processor,
spreadsheet, or database program that can produce plain text,
then manually copy the text file to the
RightFax\Production\Include folder. The text file must have the
extension .inc or errors will occur
Create an FCL document that uses either {{file}} or {{list}} to
create an include file, and then send the FCL document to the
Integration Module. This method automatically stores the file in
the RightFax\Production\Include folder.
Note Both {{file}} and {{list}} create and store files in the same
folder. {{list}} removes all white space, blank lines, etc. from the input
file, while {{file}} does not.
Using Cover Sheets in a Broadcast
Production cover sheets cannot be used when broadcasting. To
broadcast a fax with a cover sheet, use a .pcl or .doc cover sheet
and keywords. For information and instructions on .pcl and .doc
cover sheets, see the RightFax Administrator’s Guide.
A list of keyword equivalents is provided in the following table.
Table 10a Cover Sheet Keyword Equivalents
.cov keyword
.pcl or .doc
keyword
Notes
billing
billinfo1
15 characters maximum.
billing2
billinfo2
15 characters maximum.
130
Table 10a Cover Sheet Keyword Equivalents (Continued)
.cov keyword
.pcl or .doc
keyword
Notes
comment
to_citystate
59 characters maximum.
company
to_company
59 characters maximum.
contact
to_name
59 characters maximum.
covertext
notetext
21 lines, each with each
containing 69 characters
maximum.
csi
from_phone
31 characters maximum.
fax
to_faxnum
31 characters maximum.
Can contain alphabetical
characters for macros.
onerror delete
faxflag_autodeleteall
Deletes successful
documents.
onsuccess
delete
faxflag_autodelete
owner
from_name
59 characters maximum.
priority
ucPriority
Can be low (0), medium
or normal (1), or high (2)
priority. The default is low.
quality
finemode
voice
to_contactnum
31 characters maximum.
winsecid
owner_id
The RightFax user ID of
the originator of the fax.
The cover sheet is not cleared between broadcast fax numbers, so
one {{cover}} command carries forward from document to
document. You can turn on or off individual cover sheets inside the
broadcast by using the {{cover none}} command.
Sending Documents to a Printer or File with FCL
Sending documents to a printer
To send a document to a printer, add the {{type print}} command to
the FCL. The document will print at the default printer specified in
the Integration Module Configuration program. You can change the
printer with the {{lp}} command. The following example shows an
FCL document that will be printed.
{{begin}}
{{type print}}
Body of the document to be sent.
{{end}}
Sending documents to a file
The Integration Module can print documents to two different kinds
of files: plain text (ASCII) files or .tif files. The {{type file}} command
creates a .tif image of the host document and stores it in a folder
that you specify. In the following example, the file MyDocument.tif
would be saved in the RightFax\Production folder.
{{begin}}
{{type file RightFax\Production\MyDocument}}
Body of the document to be sent.
{{end}}
The {{file}} and {{list}} commands create a plain text (ASCII) file
with an .inc extension in the RightFax\Production\Include folder.
{{List}} strips all leading white space and blank lines, but {{file}}
does not. In the following example, the file MyDocument.inc would
be saved in the RightFax\Production\Include folder.
{{begin}}
{{file MyDocument}}
Body of the document to be sent.
{{end}}
Chapter 10
Creating FCL Documents
131
OpenText RightFax 10.5 Integration Module Guide
You can also specify a full path to another folder:
Figure 10.4 Host data Merged with a Background Form
{{begin}}
{{list c:\Marketing Files\Reports\MyDocument}}
Body of the document to be sent.
{{end}}
For more information on the {{file}} and {{list}} commands,
including syntax and examples see Appendix B, “FCL Commands”.
Creating and Linking Background Forms
Background forms are graphic files that are merged with a
document from the host application to create a finished document
that looks like it was printed on a preprinted form. Linking a
background form to a host document is different from inserting or
attaching a graphic file.
Understanding Background Forms
Typically, background forms are used to replace documents that
would normally be printed on preprinted forms and then mailed or
manually faxed. The Integration Module merges an electronic
background form with the host data and then sends the finished
document per your specifications.
The following figure shows a simple example of how the Integration
Module merges the data from the host application with a
background form.
Creating Background Forms
You can create background forms by scanning an existing paper
form, or you can use a drawing application to create a form. If you
are duplicating an existing form, scan it at 200 dpi. If you are using
a drawing package, you can use any graphic program that outputs
a TIF file. In either case, all background forms must be in class F,
group 3 or 4 TIF format and stored in the
RightFax\Production\Forms folder.
Linking Background Forms
Use the {{form}} FCL command to link a background form to a
document.
Example
{{begin}}
{{fax 503-555-9023}}
{{form invoice.tif}}
Host data.
{{end}}
This example would merge the host data with a background form
called invoice.tif, which resides in the RightFax\Production\Forms
folder.
132
Example FCL Documents
Figure 10.5 Other Files Can Be Added to the Document
The following figure (“Figure 10.5: Other Files Can Be Added to
the Document”) illustrates how other documents—such as cover
sheets, background forms, and attachments—can be included in a
document with the use of FCL commands.
1. The Integration Module receives the document data stream from
the host. It contains the source document data and FCL
commands. In the example here, the original host data is shown
in bold text. It will become part of a purchase order. The FCL
commands precede and follow the host data.
2. The {{cover}} command specifies that the file Sales.cov will be
used as the fax cover sheet. The example cover sheet creates a
0.5-inch left margin ({{lm}}) and starts the text “Fax Transmission
from Smith Hardware” at the x- and y-coordinates 0.5 and 1.0
inches from the top-left corner. The cover sheet is attached as
the first page of the document.
3. The {{attach}} command specifies that the file
Januaryinvoices.doc will be attached. Januaryinvoices.doc will
be attached following the body of the fax.
4. The {{include}} command specifies that the file
Februaryorders.inc will be referenced. The include file specifies
the measurements for top and left margins ({{tm}} and {{lm}})
and the font.
5. The {{form}} command specifies that the file Purchorder.tif will
be added as the background for the fax.
6. The finished fax includes the background form and the
document data, as if the document has been printed on a
pre-printed form.
7. The cover sheet, document, and attachment are faxed to
503-555-1234 in one transmission.
The following figure (“Figure 10.6: FCL Document for an Invoice”)
illustrates the FCL-encoded document for an invoice. The finished
document is illustrated in “Figure 10.7: Finished Invoice”.
Chapter 10
Creating FCL Documents
133
OpenText RightFax 10.5 Integration Module Guide
1. The {{form}} command specifies that the file Invoice.tif will be
added as the background for the fax. “Figure 10.7: Finished
Invoice” shows the finished document merged with the
Invoice.tif background form.
2. The {{attach}} command retrieves a file named Ptc6mos.xls.
This file is a six-month history of items purchased by Portland
Trading Company. It is a Microsoft® Excel spreadsheet that is
populated with data from a database. The spreadsheet will be
sent as an attachment.
3. These four commands format the document. {{Tm}} specifies a
top 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 landscape
orientation.
4. These three commands will populate the variables in a
notification message that will notify the sender when the
document is sent.
5. The {{onerror}} command specifies that the Integration Module
take a particular action if a document fails to send properly. If an
error occurs in transmission, the document will be faxed to
503-555-4592, which is a fax machine in the sender’s office.
6. The {{notifyhost}} command specifies that the sender will
receive a notification message when the document is sent.
Figure 10.6 FCL Document for an Invoice
134
Figure 10.7 Finished Invoice
Chapter 10
Creating FCL Documents
135
OpenText RightFax 10.5 Integration Module Guide
136
Chapter 11
Programming for the RightFax API for Java
The RightFax API for Java converts Java to XML on the host
computer and then transmits it to the RightFax Integration Module.
The RightFax XML Interface converts the XML to FCL. The
RightFax Integration Module can then process and send the
document from the RightFax server.
The RightFax API for Java can submit an outbound document,
query the RightFax server for the status of a document, and
perform actions (forward, delete, or create a library document) on
previously sent documents.
The RightFax API for Java requires the Sun Microsystems, Inc. Java
Developer’s Kit version 1.1.8 or later.
The API for Java provides access to the following functions and
methods of transport in the RightFax XML Interface.
Table 11a XML Interface Transport Methods and Functions
Function
HTTP or
HTTPS
File
IBM
WebSphere
MQ
Action
Yes
Yes
Yes
Action Reply
Yes
Yes
No
Notification
Yes
Yes
Yes
Query
Yes
Yes
No
Query Reply
Yes
Yes
No
Table 11a XML Interface Transport Methods and Functions
Function
HTTP or
HTTPS
File
IBM
WebSphere
MQ
Submit
Yes
Yes
Yes
Submit Reply
Yes
Yes
No
For specifics about the RightFax API for Java classes, fields, and
methods, see the RightFax html Help files that are installed with the
API in the folder RightFax\Production\XML\Java\Docs.
Installing the API for Java
Note RightFax provides programming interfaces for both Java and XML.
These interfaces are both installed when you run the Java installation.
Minimum System Requirements
In addition to the minimum system requirements for the RightFax
server and RightFax Integration Module, Microsoft Internet
Information Server (IIS) version 6.0 or later must be installed on the
RightFax server.
137
OpenText RightFax 10.5 Integration Module Guide
If you are installing the XML interface on a server running IIS
version 6.0, Active Server Pages and ISAPI Extensions must be
enabled. Parent Paths must also be enabled, either for the Default
Web Site as a whole, or for the RFXML virtual directory which
appears after the installation of the Java/XML API.
If you are installing the XML interface on a server running IIS
version 7.0, you must enable CGI modules and ISAPI modules.
Parent Paths must also be enabled, either for the Default Web Site
as a whole, or for the RFXML virtual directory which appears after
the installation of the Java/XML API.
Installing the Java Interface
Follow the instructions for installing the RightFax server in the
RightFax Installation Guide and use the following specific steps:
On the Setup Type screen, select Custom and then click Next.
z On the Setup Features screen, expand the RightFax Server
heading in the components tree and select the Java/XML API
component to install. Click Next.
Complete the remaining instructions in the RightFax Installation
Guide for installing the RightFax server. After the RightFax server
and Java/XML API component are installed and activated, you
must configure an SMTP host and an IIS user account.
z
SMTP Host. Open the RightFax Server Module and click the
e-transport tab. Enter the name of the SMTP server on your
network that will transport all SMTP alerts and notifications
regarding the RightFax server. If you will not be using SMTP to
deliver RightFax alerts and notifications, you can leave this option
blank.
IIS User Account. In IIS, configure the rfxml website with an IIS
user account that RightFax will use to access the IIS server. This
account is required for Java development.
Additional Java development tools are located in the
Program Files\RightFax\Production\XML\Java folder.
Configuring the Java development computer to use the
RightFax Java interface
Copy RFJavaInt.zip from the
Program Files\RightFax\Production\XML\Java folder on the
RightFax server to the development computer or the computer that
will be running the Java interface. If you already have Java classes
located on this computer, you should copy this file to the same
location. When the file has been copied, you must modify the
CLASSPATH environment variable to include this .zip file.
Example If the RFJavaInt.zip file is located in the C:\Proj\Java
folder on the development computer, then set the
following CLASSPATH environment variable:
CLASSPATH=%CLASSPATH%;C:\Proj\Java\RFJavaI
nt.zip
Finally, when using the RightFax Java class library, you must import
the RightFax class package by including this line in your Java code:
import RightFax.*;
Important Because Java is case-sensitive, this line must be included
in your Java code using the exact capitalization in this example. Incorrect
capitalization will fail to import the RightFax Java class library.
Sending Outbound Documents
To submit an outbound document, you must set sender information,
recipient information, and add the content for the primary
document (if any). These are encapsulated in an RFDoc object, in
the RFaxSubmit object. Then you can add any attachments. The
following list describes the basic steps.
1. Create an RFaxSubmit object.
2. Set the target URL for the RightFax server, using the
setTargetURL method. This takes a String, NOT a URL object
(it will create the URL object).
138
3. Use the RFDoc object m_FaxDocument in the RFaxSubmit
object to set all the non-attachment information about the
document.
z
z
Call m_FaxDocument.setSenderInfo (…) to set the
information about the person sending the document. This
method has been overloaded, with a version that takes all
information as parameters, a version that only takes the
minimum information (RFUser ID), and versions that take the
more common information. If there is not an overloaded
version with exactly what you want, use one that takes more,
and set the parameters you don't want to use to empty
strings (””).
Call m_FaxDocument.addRecipient (…) for each recipient.
Each time you call this, a recipient will be added to the list.
This method has been overloaded, with a version that takes
all information as parameters, a version that only takes the
minimum information (Fax Number), and versions that take
the more common information. If there is not an overloaded
version with exactly what you want, use one that takes more,
and set the parameters you don't want to use to empty
strings (””).
5. When all the data is set, call the method. You will get back a
Vector of RFStatus objects. Each object will contain the status
for one recipient, stating whether it was passed on for sending
or if there was an error.
Note You can call the submitEx method in place of submit. This will
return a string containing the unparsed XML returned by RightFax.
The XML contains the status of each recipient in the form of the
following example.
Note New to version RightFax 8.0, methods have been added to
set e-mail and printer recipients. See the JavaDocs for details.
z
z
Call m_FaxDocument.setBody (…) to set the contents of the
fax body (if any). If the body data is not plain text, make sure
to set the type as well.
Call m_FaxDocument.setCoverText (…) to set the contents
of the fax cover sheet text (if any). If the cover text is a data
type other than plain text, then use
m_FaxDocument.setCoverTextType (…) to set the type.
4. If you have any attachments, make a call to addAttachment (…)
for each attachment. Each time you call this, an attachment is
added to the list. This method takes a fully qualified path as its
parameter, not the contents of the file to be attached.
Chapter 11
Programming for the RightFax API for Java
139
OpenText RightFax 10.5 Integration Module Guide
Sample code for creating an outbound document
import RightFax.*;
import java.net.MalformedURLException;
import java.net.UnknownHostException;
import java.io.IOException;
import java.util.*;
class FaxSubmit
{
//Create an outbound fax object
RFaxSubmit obFS = new RFaxSubmit();
//Set the URL of the RightFax server
obFS.setTargetURL (“http://www.company.com/”);
//Set the information on who is sending the fax
obFS.m_FaxDocument.setSenderInfo (“Bill Smith”, “”, “Acme,Co.”, “”, “”, “”, “”, “”, “”, “BillS”);
//Add 2 recipients
try {
obFS.m_FaxDocument.addRecipient (“PRODXML:0001”, “555-1234”, “”, “Jim Jackson”, “”, “”, “”, “”, “”, “”, “”, “”);
} catch (RFNoFaxNumberException nfne) {
System.out.println (nfne.toString());
} catch (RFInvalidIDException iide) {
System.out.println (iide.toString());
}
//Add an e-mail and a printer recipient
try {
obFS.m_FaxDocument.addRecipient_email (“EMAIL:00000001”, “[email protected]”, “”, “Here is the document”, “”);
obFS.m_FaxDocument.addRecipient_printer (“PRNT:000000001”, “MyPrinter”, (short)1);
} catch (RFNoDestinationException nde) {
System.out.println (nde.toString());
} catch (RFInvalidIDException iide) {
System.out.println (iide.toString());
}
//Set the body text
obFS.m_FaxDocument.setBody ( “Here is some body text”, “TXT”, -1, -1, -1, “Arial”, -1, -1);
//Set the cover text
obFS.m_FaxDocument.setCoverText (“Here is some cover text”);
//Add attachments
140
obFS.addAttachment (“c:\\documents\\mydoc.doc”);
obFS.addAttachment (“c:\\documents\\license.pdf”);
//Send the document, and get back the results.
Vector obRetList = null;
try {
obRetList = obFS.submit();
} catch (MalformedURLException mue) {
System.out.println (mue.toString());
} catch (UnknownHostException uhe) {
System.out.println (uhe.toString());
} catch (IOException ioe) {
System.out.println (ioe.toString());
} catch (RFNoDataException nde) {
System.out.println (”Error:” + nde.toString());
}
//Output the results
int nSize = obRetList.size();
for (int i = 0; i < nSize; i++)
{
RFStatus obStat = (RFStatus)(obRetList.get(i));
System.out.println ((i+1) + ”-”);
System.out.println (”\tID: ” + obStat.getID());
System.out.println (”\tStatusCode: ” + obStat.getStatusCode());
System.out.println (”\tStatusMessage: ” + obStat.getStatusMsg());
}
}
Chapter 11
Programming for the RightFax API for Java
141
OpenText RightFax 10.5 Integration Module Guide
Querying Documents
To perform a query on the status of a document (or group of
documents), you must set the criteria for each query. The following
list describes the basic steps.
1. Create an RFaxQuery object.
2. Set the target URL for the RightFax server, using the
setTargetURL method. This takes a String, not a URL object (it
will create the URL object).
3. Call addQuery (…) for each query you want to add to the
request. This method has been overloaded, with a version that
takes all information as parameters, and versions that take the
more common information. If there is not an overloaded version
with exactly what you want, use one that takes more, and set
the parameters you don't want to use to empty strings (””) or
NULL for CALENDAR objects. You must set at least one query
criteria parameter.
4. When all the queries are set, call the submit method. You will
get back a Vector of RFStatus objects. Each object will contain
the status of one document (not one query—a query could return
many fax statuses).
Sample code for querying a document
import RightFax.*;
import java.net.MalformedURLException;
import java.net.UnknownHostException;
import java.io.IOException;
import java.util.*;
class FaxQuery
{
//Create a RFaxQuery object
RFaxQuery obQ = new RFaxQuery();
//Set the URL of the RightFax server
obQ.setTargetURL (“http://www.company.com/”);
//Criteria for one query.
try {
obQ.addQuery (“PRODXML:0001”, null, null, “”, “”, “”);
}catch (RFEmptyQueryException eqe) {
System.out.println (eqe.toString();
}catch (RFInvalidIDException iide) {
System.out.println (iide.toString());
}
//Send the query, and get back the results
Vector obQRetList = null;
try {
obQRetList = obQ.submit();
}catch (MalformedURLException mue) {
System.out.println (mue.toString());
}catch (UnknownHostException uhe) {
System.out.println (uhe.toString());
}catch (IOException ioe) {
System.out.println (ioe.toString());
}catch (RFNoDataException nde) {
System.out.println (nde.toString());
}
//Output the results
int nQSize = obQRetList.size();
for (int i = 0; i < nQSize; i++)
{
RFStatus obStat = (RFStatus)(obQRetList.get(i));
System.out.println ((i+1) + ”-”);
System.out.println (”\tID: ” + obStat.getID());
System.out.println (”\tStatusCode: ” + obStat.getStatusCode());
System.out.println (”\tStatusMessage: ” + obStat.getStatusMsg());
}
}
142
Performing Actions on Documents
To perform an action on a document, you need the unique ID for
that document. Once you have that, you can either delete the
document, forward it to another recipient, or use it to create a
library document. If you don’t have the unique ID, you can obtain it
by doing a query on the information that you do have (see
“Querying Documents” on page 142).
When you submit a document, you have the option of creating a
unique ID for that document or letting the RightFax server assign a
unique ID for you.
Note If you create your own unique ID, it must be 15 characters or less.
For unique IDs that the software creates, the format is:
z
z
The first seven characters are the name of the RightFax server.
The last eight characters are a number unique to a document.
1. Create an RFaxAction object.
2. Set the target URL for the RightFax server, using setTargetURL
method. This takes a String, NOT a URL object (it will create
the URL object).
3. Call addForwardAction (…) for each forward action you want
to perform. This method has been overloaded, with a version
that takes all information as parameters and a version that only
takes the minimum information (ID and fax number). If there is
not an overloaded version with exactly what you want, use one
that takes more, and set the parameters you don’t want to use
to empty strings (“”).
4. Call addDeleteAction (…) for each delete action you want to
perform. The ID parameter is required.
5. Call addLibDocAction (…) for each create library document
action you want to perform The ID, LibDocID, and
LibDocDescription parameters are all required.
6. When all the actions are set, call the submit method. You will
get back a Vector of RFStatus objects. Each object will contain
the status of one action, stating whether or not the action was
successful.
Chapter 11
Programming for the RightFax API for Java
143
OpenText RightFax 10.5 Integration Module Guide
Sample code for performing an action on a document
import RightFax.*;
import java.net.MalformedURLException;
import java.net.UnknownHostException;
import java.io.IOException;
import java.util.*;
class FaxAction
{
//Create a RFaxAction object
RFaxAction obA = new RFaxAction();
//Set the URL of the RightFax server
obA.setTargetURL (“http://www.company.com/”);
//Create a forward action
try {
if (!obA.addForwardAction(”PRODXML:0001”, ”555-6789”, ”Mike Michell”, ””, ””, ””, ””)) {
System.out.println (”Add Forward Action Failed”);
}
} catch (RFNoFaxNumberException nfne) {
System.out.println (nfne.toString());
} catch (RFNoIDException nide) {
System.out.println (nide.toString());
} catch (RFInvalidOpException ioe) {
System.out.println (ioe.toString());
}
//Create a delete action
try {
if (!obA.addDeleteAction(”PRODXML:0002”)) {
System.out.println (”Add Delete Action Failed”);
}
} catch (RFNoIDException nide) {
System.out.println (nide.toString());
} catch (RFInvalidOpException ioe) {
System.out.println (ioe.toString());
}
//Send the action requests, and get back the results
Vector obARetList = null;
144
try {
}
}
}
}
obARetList = obA.submit();
catch (MalformedURLException mue) {
System.out.println (mue.toString());
catch (UnknownHostException uhe) {
System.out.println (uhe.toString());
catch (IOException ioe) {
System.out.println (ioe.toString());
catch (RFNoDataException nde) {
System.out.println (nde.toString());
}
//Output the results
int nASize = obARetList.size();
for (int i = 0; i < nASize; i++)
{
RFStatus obStat = (RFStatus)(obARetList.get(i));
System.out.println ((i+1) + ”-”);
System.out.println (”\tID: ” + obStat.getID());
System.out.println (”\tStatusCode: ” + obStat.getStatusCode());
System.out.println (”\tStatusMessage: ” + obStat.getStatusMsg());
}
}
Using Debug Mode
The method setDebug is part of the RFax class and is therefore
callable from any RFaxSubmit, RFaxAction, or RFaxQuery object.
By turning on debug mode, you can get more information sent to
the standard out. This includes information such as the XML
generated for sending to the RightFax server and the XML returned
from the RightFax server.
To turn on debug mode, call the setDebug method, passing it true.
Chapter 11
Programming for the RightFax API for Java
145
OpenText RightFax 10.5 Integration Module Guide
Error and Status Codes for XML- and Java-Based
Documents
The RightFax API for Java will return status information (as a vector
of RFStatus objects or as a string containing XML) for all
operations, unless an error occurs in the API, in which case an
exception will be thrown.
Each RFStatus object or XML node will contain a status code,
status message, and document ID.
Table 11b XML Interface Error and Return Codes (Continued)
Code
Message
Explanation
-2
Failed to load XSL into DOM
tree.
The XSL file could not be
loaded into the DOM tree. This
is usually caused by the file not
being found or syntax error in
the XSL file.
-4
Failed to get XSL file info.
The XML file did not contain
information on the XSL file to
use, and the default (in the
registry) could not be found.
0
Submit failed.
Unable to perform the submit
requested. The message will
contain the reason.
1
Document has been
successfully submitted for
sending.
The document has been
passed on for sending. If
notifications are set up, you
will be informed of the success
or failure of the send via that
notification type.
-99
No information found.
The query returned no
documents matching your
criteria.
0
Query failed.
Unable to perform the query
requested. The message will
contain the reason.
0-n
N/A
If you receive a message not
listed in this table, it is a code
universal to all RightFax
software. These are listed in
the RightFax Administrator’s
Guide.
The following table lists all possible codes, their associated
messages, and an explanation for what each indicates.
Table 11b XML Interface Error and Return Codes
Code
Message
Explanation
General
-1
-3
-5
Submit
Failed to load XML into DOM
tree. XML file copied to err dir.
The XML file could not be
loaded into the DOM tree. This
is usually caused by the file not
being found, a syntax error in
the XML file, or the XML file
not conforming to the schema.
Failed to connect to RF Server. The production software was
unable to connect to the
RightFax server. This is usually
caused by the RFServer
service not running.
Unknown XML operation type.
The operation was not
XML_FAX_SUBMIT,
XML_FAX_QUERY, or
XML_FAX_ACTION.
Query
146
Table 11b XML Interface Error and Return Codes (Continued)
Code
Message
Explanation
6
Deleted
If the document had previously
been sent successfully, but
has since been deleted.
-99
No such fax found.
The document you wish to
perform the action on could
not be found.
0
Action failed.
Unable to perform the action
requested. The message will
contain the reason.
1
Fax (<ID>) has been deleted.
Success
1
Fax (<ID>) has been submitted
for forwarding to: <recipient>.
Success
1
A Library Document has been
created from fax: <ID>.
Success
Action
Notification
0-n
N/A
If you receive a message that
is not listed in this table, it is
listed in the RightFax
Administrator’s Guide.
Chapter 11
Programming for the RightFax API for Java
147
OpenText RightFax 10.5 Integration Module Guide
148
Chapter 12
Creating FCL Documents with InternetLink Commands
The RightFax InternetLink Module is a component of the RightFax
Enterprise Integration Module. The InternetLink Module enables the
Integration Module to build documents in Multipurpose Internet
Mail Extensions (MIME) or text format and send them via Simple
Mail Transfer Protocol (SMTP) through the Internet.
You can use the InternetLink Module to send documents in native
mode or filter mode.
System Requirements
The InternetLink Module requires the following:
z
z
z
z
RightFax Enterprise Server and Integration Module already
installed.
Network connection to the Internet.
SMTP gateway on the network.
TCP/IP connection from the RightFax Integration Module to the
network
Activating the InternetLink Module
The files required by the InternetLink Module are installed on all
RightFax servers during the server installation. However, the
InternetLink Module must be licensed and activated before its
functionality will be enabled.
To activate the InternetLink Module, you must have licensed a
RightFax server type that includes this connector, or purchased and
licensed this connector separately. For information on activating
new components on the RightFax server, refer to the RightFax
Installation Guide.
Before you begin sending documents with the InternetLink Module,
verify the name of your e-mail server.
To verify the name of your e-mail server
1. On the RightFax server, select Start > Programs > Enterprise
Fax Manager. The Enterprise Fax Manager window opens.
2. Select the RightFax server in the list of servers in the left pane of
the window. A list of services appears in the lower-right pane.
3. In the Service Name list, double-click RightFax Server
Module. The Server Configuration dialog box opens.
4. Click the eTransport tab.
149
OpenText RightFax 10.5 Integration Module Guide
5. Verify that the fully qualified domain name of your SMTP server
Table 12a Required FCL Commands (Continued)
appears in the SMTP Hostname box. If the name of your server
is not correct, enter the correct name.
To create and send documents with the InternetLink Module, use
the InternetLink FCL commands.
Understanding the InternetLink FCL Commands
Documents sent via the InternetLink Module require six FCL
commands. Without all of these commands, the document will not
be sent. The required commands are listed in the following table.
Table 12a Required FCL Commands
Command
Description
{{begin}}
Indicates the beginning of a document.
The Integration Module will process all the data
that appears between a {{begin}} and {{end}}
command as a discreet document. Data that does
not appear between the {{begin}} and {{end}}
commands is ignored.
This command must appear as the first command
in each InternetLink document.
{{end}}
Command
Description
{{to}}
Recipient’s e-mail address.
{{type email}}
or
{{type email}} sends a document as the editable
body of an e-mail message.
{{type mime}}
{{type mime}} sends a document as an attachment
to an empty e-mail message.
The commands {{begin}} and {{type}} can be replaced with a
“shortcut” command, {{begin mime}} or {{begin email}}.
Choosing document types
The document type determines the type of document that the
recipient receives via e-mail. The type of document is specified with
the {{type}} command.
z
z
{{type email}} converts the document to the editable body text of
an e-mail message. This is plain text; it has no formatting.
{{type mime}} converts the document to an un-editable,
MIME-encoded graphic attachment to an empty e-mail message.
This retains all formatting and graphics. Sending documents in
MIME format is best when the document must not be editable or
when it must be an exact replica of a pre-printed, hardcopy form.
Indicates the end of a document.
The Integration Module will process all the data
that appears between a {{begin}} and {{end}}
command as a discreet document. Data that does
not appear between the {{begin}} and {{end}}
commands is ignored.
This command must appear as the last command in
each InternetLink document.
{{from}}
Sender’s e-mail address.
{{subject}}
Subject line of the e-mail message.
Choosing image types
The image type refers to the type of graphic file that is created
when you use the {{type mime}} command, PDF, TIF, or PCX. To
specify an image type, use the {{imagetype}} command (see
“IMAGETYPE” on page 177).
The default graphic format for {{type mime}} documents is Group 4
TIFF.
150
Using include files with the InternetLink Module
When you activate the InternetLink Module, an empty include file
called Mime.inc is created in the RightFax\Production\Include
folder. You can insert plain text (but not FCL, formatted text, or
graphics) in Mime.inc, and this text will become the body of a
{{type mime}} document.
Mime.inc is linked by default to all InternetLink documents.
Because it is empty, Mime.inc has no function unless you add
information to it. If you add information to Mime.inc, then that
information will appear in the body of each {{type mime}} message
that is sent using the InternetLink Module.
Attaching Native Files to InternetLink Documents
Without the InternetLink Module, the Integration Module converts
all attachments to fax format (a TIF image) before sending. The
InternetLink Module gives you the option to attach documents in
native file format. For example, a Microsoft Word document can be
sent as a Word document.
To attach a file, use the {{attach}} or {{beginnative}} commands. For
a description of both commands, see “FCL Commands”.
In the following example, Program.xls will be attached in its native
format (as a Microsoft Excel document) to the host document.
Use the native option to the {{attach}} command when the file must
be editable or when fax format cannot adequately represent the
content of a file. For example, fax format cannot adequately
represent the content of an audio file.
You can attach multiple documents by inserting multiple {{attach}}
commands. The {{attach}} command cannot be used with the
{{type email}} command.
Example FCL for InternetLink documents that have
attachments
The following examples illustrate FCL documents with attachments
created for the InternetLink Module. In each example, the FCL (on
the left) yields different final results (on the right).
In the following example, the host data (“Here are last week’s
programs.”) is converted to PDF and is saved as the attachment
called 5816.pdf (the file name is generated automatically by the
system) through the use of the {{type mime}} and {{imagetype pdf}}
commands. The attached document (Programs.xls) is also attached
in its native format (a Microsoft Excel file) through the use of the
{{attach}} command with the native option.
The example includes text that was added to Mime.inc, “This
message comes to you from Oswego Corporation”. For more
information, “Using include files with the InternetLink Module” on
page 151.
Example {{attach c:\\IST Files\Programs.xls native}}
If you create a {{type mime}} document that contains the {{attach}}
command with the native option, then the attached document
becomes the second attachment to an empty e-mail message.
If you use the {{attach}} command without the native option, then
the attached document and the host document are merged into
one graphic file that is attached to an empty e-mail message. You
determine the image type of this graphic file with the {{imagetype}}
command “Choosing image types” on page 150.
Chapter 12
Creating FCL Documents with InternetLink Commands
151
OpenText RightFax 10.5 Integration Module Guide
Figure 12.1 Attaching a File in its Native Format
{{begin}}
{{type mime}}
{{imagetype pdf}}
Here are last week’s programs.
{{attach “c:\\IST Files\Programs.xls” native}}
{{to [email protected]}}
{{subject Weekly programs}}
{{from [email protected]}}{{end}}
In the following example, the host data (“Here are last week’s
programs.”) is converted to PDF and becomes page 1 of the
attachment called 5816.pdf through the use of the {{type mime}}
and {{imagetype pdf}} commands.
Because the native option of the {{attach}} command was not
used, Programs.xls is converted to PDF and becomes page 2 of
5816.pdf.
Figure 12.2 Attaching a File Converted to PDF Format
{{begin}}
{{type mime}}
{{imagetype pdf}}
Here are last week’s programs.
{{attach “c:\\IST Files\Programs.xls”}}
{{to [email protected]}}
{{subject Weekly programs}}
{{from [email protected]}}
{{end}}
152
Sending Documents as E-mail if Faxes Fail
With the InternetLink Module, you can an e-mail documents if fax
numbers fail. To do this, use the {{onerror}} command.
The {{onerror}} usage options relevant to the InternetLink Module
are:
{{onerror {email|mime e-mail address}}}
Unlike the {{type}} command, the e-mail and mime options for the
{{onerror}} command do the same thing. With either option, the
document is sent as a graphic image attached to an empty e-mail
message. With both options, you must use the {{imagetype}}
command to specify the type of graphic image to create.
In the following example, if the document fails to send as a fax, then
it will be sent as a PDF file attached to an empty e-mail message to
[email protected]
{{begin}}
{{fax 503-555-4489}}
{{onerror email [email protected]}}
{{imagetype pdf}}
Body of the document to be sent.
{{end}}
When a fax fails and is sent as an e-mail, all e-mail addressing
options (such as {{to}} and {{cc}}) in the original document are
replaced with the e-mail address specified in the {{onerror}}
command. The content of the {{contact}} command is replaced
with “To whom it may concern.” All other fields, such as {{subject}}
or {{from}}, are retained as they were in the original document.
Receiving Notification When a Fax Fails and Is
Sent as an E-mail
To create a notification that a fax has failed and has been sent as an
e-mail, include the ^type^ keyword in the notification template. See
”Creating Notification Messages with FCL” on page 72.
Chapter 12
Creating FCL Documents with InternetLink Commands
153
OpenText RightFax 10.5 Integration Module Guide
154
OpenText RightFax Connector for Oracle Purchasing 11i
With the OpenText RightFax Connector for Oracle Purchasing 11i,
you can send purchase orders, releases, and change orders from
the Oracle Purchasing 11i application, a component of the Oracle
E-Business Suite, via your RightFax server.
Activating the Oracle Purchasing 11i Connector
The files required by the Connector for Oracle Purchasing 11i are
installed on all RightFax servers during the server installation. The
RightFax Integration Module must be licensed and activated before
its the Oracle functionality will be enabled.
For information on activating new components on the RightFax
server, refer to the RightFax Installation Guide.
Sending documents from Oracle 11i
The Oracle Purchasing 11i user interface contains a Fax Number
text box where a user can type a recipient fax number. The user can
also enter an email address in this text box. The Oracle Purchasing
11i Connector uses this fax number or email address to send the
document to a recipient.
Understanding document templates
The RightFax Connector for Oracle Purchasing 11i includes
customizable Integration Module templates that have been created
for Oracle Purchasing 11i:
z
z
z
How the Oracle Purchasing 11i Connector Works
The Connector for Oracle Purchasing 11i fax- and email-enables
Oracle Purchasing 11i by intercepting data from the print stream
sent from Oracle. The connector affixes elements of the RightFax
Facsimile Command Language (FCL) to the document data,
checks FCL syntax, and then faxes or emails the document.
purchase order
release
change order
These templates define the layout of each type of document,
including information such as text margins and fonts.
The following is an outline of the data flow process between the
Oracle and RightFax servers
1. Print output is sent from Oracle Purchasing 11i to the RightFax
server.
2. RightFax detects the {{doctype}} FCL command and accesses
the relevant document template.
3. FCL in the document template is added to original Oracle
document.
OpenText RightFax Connector for Oracle Purchasing 11i
155
OpenText RightFax 10.5 Integration Module Guide
4. RightFax re-formats and transmits the document based on
FCL-defined parameters in the document template.
You can customize the default document templates by:
z
z
z
z
z
z
z
z
Placing graphics, such as logos, on the template.
Including background forms, such as a purchase order form.
Specifying a cover sheet to send with each document.
Setting margins and fonts, choosing a printer, and changing the
page orientation.
Configuring documents to be printed, faxed, or e-mailed.
Specifying a notification method and notification templates.
Adding FCL to the template.
Re-naming the templates.
To edit a document template
1. On the RightFax server in Windows Explorer, navigate to
RightFax\Production\Bin and run ERPConnector.exe. This
opens the Oracle Purchasing 11i Connector window.
Figure 12.1 The Oracle Purchasing 11i Connector Window
Editing the Default Templates
The default settings in the templates are the default values
established in the Integration Module. When you edit the Oracle
Purchasing 11i templates, the settings you make override the
defaults. For more information about defining the appearance of
documents, see “Defining Fax Page Appearance” on page 59.
Do not create new templates. Only the default templates for a
change order, a purchase order, and a release are supported.
2. To re-name a template in the Template Name list, select the
Warning Although you can edit the default document templates, do not
delete them.
name, click Rename, and enter the new name. This changes the
name that appears in the display only. It does not change the file
name.
3. In the Template Name list, select the template to edit.
156
4. Click Edit. The edit dialog box appears in the right pane of the
window. You have the following options:
z
z
z
z
z
z
z
“Adding a graphic image or a background form” (described
on page 157.)
“Adding a cover sheet” (described on page 158.)
“Configuring the layout” (described on page 158.)
“Faxing a copy of a document that was transmitted”
(described on page 159.)
“Faxing a copy of a document that cannot be transmitted”
(described on page 160.)
“Specifying the notification method” (described on
page 160.)
“Adding FCL code to the template” (described on
page 161.)
Adding a graphic image or a background form
1. Click the Forms tab.
Figure 12.2 The Forms tab
5. After making your changes, click Save on the File menu, or click
the Save icon on the toolbar.
2. In the Form File box, enter the path to the background form to
include with the document.
3. To specify the position of the upper-left corner of the
background form, select the Place at Position check box. The
default is 0,0 from the top-right corner of the document.
4. In the Horizontal Shift and Vertical Shift boxes, enter the x-
and y-coordinates for the upper-left corner of the background
form.
5. In the Logo File box, enter the path to a graphic to appear in the
document.
6. To specify the position of the upper-left corner of the logo,
select the Place at Position check box. The default is 0,0.
OpenText RightFax Connector for Oracle Purchasing 11i
157
OpenText RightFax 10.5 Integration Module Guide
7. In the Horizontal Shift and Vertical Shift boxes, enter the x-
and y-coordinates for the upper-left corner of the graphic.
Adding a cover sheet
Configuring the layout
1. Click the Layout tab.
Figure 12.4 The Layout tab
1. Click the Cover Page tab.
Figure 12.3 The Cover Page tab
2. In the Name list, click the font name.
3. In the Points of Leading box, enter the value for the vertical
spacing of the font.
2. In the Cover File box, enter the path to the cover sheet file to
include with the fax.
4. In the Pitch box, enter the value (in 1000ths of an inch) for the
horizontal spacing of the font.
5. In the Top, Left, and Bottom boxes, enter the width of the page
margins.
6. Click Default, Portrait, or Landscape to specify the orientation
of the page.
158
7. In the RightFax Printer box, enter the name of the a printer
defined in Enterprise Fax Manager. This creates a default printer
for documents that use the document template that you are
creating.
2. Select one of the following options.
Option
Description
Default
Performs the default action specified in the
Integration Module Configuration program.
Nothing
No action will be taken.
Fax
Fax the document to another recipient.
Faxing a copy of a document that was transmitted
1. Click the On Success tab.
Figure 12.5 The On Success tab
To send the fax to the default number
specified in the Integration Module
Configuration program, click Fax to Default
Fax Number.
z To specify the fax number, click Fax to
Number. Enter the fax number. If you are
using the Enterprise Integration Module, you
can enter an e-mail address.
z To send only the first page of the document,
select the Fax First Page Only check box.
z To delete the fax image from the fax server
after transmission, select the Delete Fax
when Finished check box.
z
OpenText RightFax Connector for Oracle Purchasing 11i
159
OpenText RightFax 10.5 Integration Module Guide
Faxing a copy of a document that cannot be transmitted
2. Select one of the following options.
1. Click the On Error tab.
Figure 12.6 The On Error tab
Option
Description
Default
Performs the default action specified in the
Integration Module Configuration program.
Nothing
No action will be taken.
Fax
Fax the document to another recipient.
To send the fax to the default number specified
in the Integration Module Configuration
program, click Fax to Default Fax Number.
z To specify the fax number, click Fax to
Number. Enter the fax number. If you are using
the Enterprise Integration Module, you can
enter an e-mail address.
z To send only the first page of the document,
select the Fax First Page Only check box.
z To delete the fax image from the fax server
after transmission, select the Delete Fax
when Finished check box.
z
Specifying the notification method
Methods for sending notification messages to a host application
are configured in the Integration Module. For information and
instructions, see “Document Transmission and Notifications” on
page 71.
Notification messages, including templates, are determined by the
{{notifyhost}} FCL code. For more information on notification
messages, see “Creating Notification Messages with FCL” on
page 72.
160
1. Click the Notify tab.
Figure 12.7 The Notify tab
2. In the Notification Method list, select a notification option. The
options in this list are created in the Integration Module
Configuration program.
3. In the Successful Template list, select the template for
1. Click the Custom FCL tab.
Figure 12.8 The Custom FCL tab
2. In the FCL commands to be inserted before document text
box, type the FCL codes.
3. In the FCL commands to be inserted after document text
box, enter FCL codes.
notification messages about successful transmissions.
4. In the Unsuccessful Template list, select the template for
notification messages about failed transmission attempts.
Adding FCL code to the template
You can extend the template by adding FCL code. The complete
list of FCL codes, their syntax, and the placement of codes within
documents is provided in “FCL Commands” on page 165.
Sending Documents by Email
The user can enter an email address in the Oracle 11i Fax Number
box. When a document is sent as email, it is attached as a TIFF
image to an empty email message. The subject line of the email
OpenText RightFax Connector for Oracle Purchasing 11i
161
OpenText RightFax 10.5 Integration Module Guide
message is “E-Document,” and the sender’s e-mail address is
[email protected]/ip domain, where tcp/ip domain is the following value
in the Windows Registry:
HKLM\System\CurrentControlSet\Services\Tcpip\Parameters
\Domain
or
HKLM\System\CurrentControlSet\Services\Tcpip\Parameters
\DhcpDomain
To notify an administrator or the sender when an email address is
invalid, you have the following options:
z
z
Send a message that notifies the sender that the email address is
invalid.
Print or fax the document to another recipient.
162
Appendix A
RightFax Integration Module Programs
The following table lists the programs that are installed with the
RightFax RightFax Integration Module in the
RightFax\Production\Bin folder. You can use them to help you
configure and fax-enable your system. To see a list of the command
line options for each program, type -h at the command prompt to
view online help.
Table A1 Programs Installed With the RightFax Integration Module
Command line
syntax
Program
Description
Bufdir.exe
Reads a directory and executes a
command on each file that is
placed in the directory.
bufdir [options]
directory
Capture.exe
Reads input from a serial port at
different rates and in different
modes and executes a command
on data that is received.
capture [options] input
Dbnotify.exe
Updates databases from a Win32
command line.
dbnotify [options] Data
Source Name
Diagtiff.exe
Diagnoses TIFF image files and
diagtiff [options] infile
provides the contents of their tags. [infile ...]
Encode64.ex
e
Encodes files using base64
encoding.
encode64 [options]
infile outfile
Table A1 Programs Installed With the RightFax Integration Module (Continued)
Program
Description
Command line
syntax
Fax2mapi.exe Sends MAPI32 messages from the
Win32 command line.
fax2mapi [options]
Fax2note.exe
Sends messages to Lotus Notes.
fax2note [options]
Hd.exe
Displays files in hexadecimal
format.
hd [options] input file
Hf.exe
Sends data to a TCP/IP port.
hf [options]
Hlpisend.exe
Sends data via HLLAPI. Requires
emulation software that supports
HLLAPI. Capable of using a log-on
script to log in to a 3270 session
prior to transmitting data.
hlpisend [options]
Makedoc.exe
Submits an FCL-encoded file to
the Buffer.exe program. Buffer.exe
reads the file, parses it for syntax,
notes any errors, and passes the
file to Parse.exe. Parse.exe
prepares the document to be sent.
makedoc [options]
filename
Multitif.exe
Breaks one multiple-page TIFF
image into a document consisting
of single-page TIFF images.
multitif [options]
documentnumber
startingpage
163
OpenText RightFax 10.5 Integration Module Guide
Table A1 Programs Installed With the RightFax Integration Module (Continued)
Command line
syntax
Program
Description
Nplisten.exe
Creates a named pipe and
executes a command on data
received via the named pipe.
nplisten [options]
Portlstn.exe
Executes a command on a data
stream received via a TCP/IP port.
portlstn [options]
command
Pssplit.exe
Splits a PostScript file to create
separate pages.
pssplit [options] infile
outputdirectory
Tee.exe
Transcribes standard input to
standard output and makes copies
in the file.
tee [options] outputfile
Tiffbind.exe
Combines single-page TIFF
images into one multiple-page TIFF
image.
tiffbind [options]
outputtiff inputtiff {input
tiff ...}
Tog3.exe
Converts differing file formats of
black and white TIFF images to
Group 3, Group 4, PCX, and GIF
images.
tog3 [options] infile
outfile
Uuencode
Encodes files using uuencode.
uuencode [options]
infile outfile
164
Appendix B
FCL Commands
This appendix provides a list of the facsimile command language
(FCL) commands used to create FCL documents. This list provides
detailed information on the command syntax and usage.
ABORT
Causes the software to ignore a document before it is faxed. You
can place this command anywhere in the FCL document.
Syntax
{{abort}}
Example {{abort}}
ADDCOPIES
Increments the number of copies to print. This affects documents
with the {{type print}} command.
Syntax
{{addcopies number}}
ALTFAX
Stores an alternate fax number for document if the primary fax
number fails.
The {{altfax}} argument is cleared when a document is broadcast or
the {{execute}} command is used. To broadcast each document
with an alternate fax number, add an {{altfax}} command after every
new {{fax}} or {{execute}} command.
Syntax
{{altfax fax number}}
Example {{altfax 503-555-5458}}
The example sets the alternate fax number for the document to
(503) 555-5458.
APPROVAL
Holds the document for approval in a FaxUtil mailbox.
Example {{addcopies 3}}
Syntax
The example increments the number of printed copies of the
current document by three.
Example {{approval}}
See also “TYPE” on page 192
{{approval}}
ATTACH
Ends the current page (unless it is blank) and attaches one or more
files, optionally deleting them after they have been added to the
document.
165
OpenText RightFax 10.5 Integration Module Guide
You can specify the full path to the file with the file name. The full
path must be surrounded by quotation marks. The default is
RightFax\Production\Forms.
rounds to the nearest number of minutes, rather than adding a
specified number of minutes to the scheduled time. Specify the
number of minutes to round to.
You can use a wildcard with the file name. If the file name ends in .*
(such as sales.*), files matching the name and ending with any
extension would be attached to the current document. This is
useful for creating multiple page attachments.
Syntax
If a document contains a {{quality}} command, it should be placed
in the document before the {{attach}} command. The {{attach}}
command cannot be used in {{type email}} documents.
The command can delete the attached file(s) after the fax is
generated.
Syntax
{{attach filename [delete] [native]}}
Examples {{attach PoInv.doc delete}}
{{attach “C:\Program
Files\RightFax\Production\MyDocs.doc” native}}
The first example converts PoInv.doc to fax format (.tif) and
attaches it to the document. After the fax is generated, PoInv.doc is
deleted. Because no path is specified, PoInv.doc is located in the
folder RightFax\Production\Forms.
The second example can be used with the InternetLink Module to
send the document via e-mail. The base document would be sent
as an e-mail, and PoInv.doc would be attached to that e-mail as a
native file—it would be left as a Microsoft Word (.doc) file and not
converted to fax format.
BATCH
Alters the scheduled time to the next round number of minutes.
This is useful for keeping a document to send with a batch of other
documents. The {{batch}} command differs from {{delay}} in that it
{{batch minutes}}
Example {{batch 5}}
The example batches to the next nearest five minutes. Therefore, if
it is now 1:02 P.M., the batch time would be 1:05 P.M.
See also “DATE” on page 172
“DELAY” on page 173
“TIME” on page 191
BEGIN
Starts an FCL document. Any text between this command and an
{{end}} command is rendered as a single page for faxing or
printing.
This command is required in every FCL document. FCL documents
may contain multiple {{begin}} and {{end}} commands, but the FCL
between each set of commands will be rendered as a separate
page.
If you have licenced the InternetLink Module, you can use the
{{begin}} command to specify either mime or email format when
sending documents by email. Email format sends the contents as
an editiable body text of the email message. Mime format sends the
content as an uneditable graphic attachment to an empty email
message. If you place the email type in the {{begin}} command, you
do not need to use the {{type}} command.
Syntax
{{begin emailtype}}
Examples {{begin}}
{{begin email}}
{{begin mime}}
See also “END” on page 173
166
BEGINCVT
This command embeds a document in an FCL document. The fax
server converts the document to a TIF image using server side
application (SSA) conversion. For more information on SSA, see
the RightFax Administrator’s Guide. This command must be used
with the command {{endcvt}}.
You can also encode the embedded document using BASE64 (for
any type of binary files) or QUOTEDPRINTABLE (for files that use
only the human-readable character set). If no encoding sequence is
specified, the data is assumed to be 8-bit binary.
Syntax
{{begincvt FileName [base64|QuotedPrintable]}}
Examples {{begincvt proposal.doc}}
{{begincvt proposal.doc base64}}
The first example establishes that binary data (in this case, a
document called Proposal.doc) is included in the FCL data stream
and must be converted.
The second example does the same as the first example but
specifies to encode the data using BASE64 encoding.
Along with the required {{endcvt}} command, the FCL might look
like this:
Data entered between the {{beginnative}} command and the
{{endnative}}command eill be processed into an attachment. You
may specify a filename, body text, format, encoding, and other
parameters as described in the following table.
Table 2a: Parameters for use with {{beginnative}} command
Parameter
Description
“filename”
File name for the data. You need not supply a path with
this file name because the data is stored between the
{{beginnative}} and {{endnative}} commands.
Example
{{beginnative “File.pdf” inline
mediatype=application/pdf}}
Here are the files you wanted
{{endnative}}
In this example, RightFax will suggest to the recipient
e-mail client that “Here are the files you wanted” be
displayed as an embedded object in the body of the
e-mail message. If the recipient e-mail client cannot
perform this task, then an icon labeled File.pdf will appear
in the e-mail message. The content of File.pdf will be
“Here are the files you wanted.”
{{begincvt proposal.doc base64}} nnnnnnnn {{endcvt}}
In this example, nnnnnnnn is the actual binary data—the content of
Proposal.doc—embedded in the FCL data stream. This data would
be unreadable and undoubtedly much longer than the example
here.
See also “ENDCVT” on page 174
BEGINNATIVE
{{Beginnative}} is part of a set of commands that insert data as an
attachment to an email message. This is only available if you have
licensed the InternetLink module.
167
OpenText RightFax 10.5 Integration Module Guide
Table 2a: Parameters for use with {{beginnative}} command
Table 2a: Parameters for use with {{beginnative}} command
Parameter
Description
Parameter
Description
body
This sends the data that appears between the
{{beginnative}} and {{endnative}} commands as text in the
body of the e-mail message.
mediatype=
Specifies the nature of the data between {{beginnative}}
and {{endnative}} commands. The content type (which is
required if you use the mediatype option) is represented
by a top-level mediatype, a slash, and a subtype.
Using the body option, you can specify alternative file
formats when you want to give the recipient's e-mail
software a choice of how to display the message.
Example
text/plain
For example, you can send a text file and an HTML file.
Generally, the recipient's e-mail software will display the
file in the format that it supports. It will not display both
files.
The top-level media type identifies a general type of data,
and the subtype identifies a specific format for that type of
data. Thus, a media type of image/tif is enough to tell a
recipient e-mail client that the data is an image, even if the
recipient e-mail client cannot interpret the specific image
format of .tif.
The sequence of the file formats determines the format
that the recipient's e-mail software will display. Generally,
it will display the first file format that it supports. For
example, if you specify text and HTML format, a software
program that supports both formats will display text first.
The default mediatype for native documents with the
body option is text/plain. Without the body option, the
default mediatype is application/octet-stream. Other
common mediatypes are (but are not limited to):
To specify alternative formats, use multiple {{beginnative}}
commands with the body option.
inline
application/ms-word
This suggests to the recipient e-mail client that the data
between {{beginnative}} and {{endnative}} commands be
displayed as an embedded object in the body of the
e-mail message. If the recipient e-mail client cannot
display the host data in this way, then the data will be sent
as an attachment that is represented by an icon in the
body of the e-mail message. The icon can be opened with
the appropriate application.
application/pdf
audio/mid
audio/wav
image/gif
text/html
text/xml
video/mpeg
If you do not supply a media type, the document most
likely will not fail because most current e-mail clients can
detect the media type.
encoding
You can specify either BASE64 or QUOTEDPRINTABLE
for encoding the attachment. The data between
{{beginnative}} and {{endnative}} commands will be
encoded using the specified scheme. If these options are
not specified, then the data will not be encoded (8 bit).
168
works , include is similar to the {{attach}} command with the native
option. Both commands let you send documents in native format.
The {{beginnative}} command also lets you specify advanced
configuration options that {{attach}} does not support. The key
difference between {{beginnative}} and {{attach}} is that
{{beginnative}} requires you to put the content of the
to-be-attached file in the FCL itself, while {{attach}} attaches a file
from a different location.
Example To send a document that contains both HTML and text,
you might use the following FCL:
{{begin mime}}
{{to [email protected]}}
{{from [email protected]}}
{{subject Sample of text and HTML in the body of the
message}}
{{beginnative “body.txt” body mediatype=text/plain}}
Drew,
Here are the files that you asked for.
{{endnative}}
{{beginnative “body.htm” body mediatype=text/html}}
<HTML><HEAD><TITLE></TITLE><META
content=”text/html; charset=iso-8859-1”
http-equiv=Content-Type></HEAD>
<BODY><HR><STRONG>Drew,</STRONG><BR>
Here are the files that you asked for.<HR>
</BODY></HTML>
{{endnative}}
{{end}}
The body option of {{beginnative}} inserts the data (which appears
between {{beginnative}} and {{endnative}} commands in your host
data stream) into the body of an e-mail message.
The inline option suggests to the recipient e-mail client that the
data between {{beginnative}} and {{endnative}} commands be
displayed as an embedded object in the body of the e-mail
message. If the recipient e-mail client cannot display the host data
in this way, then the data will be sent as an attachment that is
represented by an icon in the body of the e-mail message. The icon
can be opened with the appropriate application.
{{Beginnative}} requires {{endnative}}.
Syntax
{{beginnative “filename” [body] [inline]
[mediatype=type] [encoding]}}
Example {{beginnative “Body.txt” body mediatype=text/plain}}
See also “ENDNATIVE” on page 174
BILLING
Specifies the billing code of the fax owner.
Syntax
{{billing code}}
Example {{billing 1234}}
The example specifies that the billing code associated with this fax
is 1234.
See also “BILLING2” on page 170
{{Billing}} translates to the RightFax server field billinfo1. See
”Using Cover Sheets in a Broadcast” on page 130.
169
OpenText RightFax 10.5 Integration Module Guide
BILLING2
If both coordinates are specified, you can specify a line of text to
appear in the box. The text must be surrounded by quotation marks
and is limited to one line. The text is placed in the box according to
the current placexy settings, which default to the upper-left corner
of the document.
Specifies a secondary billing code of the fax owner.
Syntax
{{billing2 code}}
Example {{billing2 4567}}
Syntax
The example specifies that the billing code associated with this fax
is 4567.
Examples {{box (0,y) (7,7) “Hi There”}}
{{box 5 5 7 7}}
See also “BILLING” on page 169
The first example draws a box from the left side of the page at the
current line to 7 units over, and 7 units down the current page,
placing the text “Hi There” within it.
{{billing2}} translates to the RightFax server field billinfo2. See
”Using Cover Sheets in a Broadcast” on page 130.
BM
The second example draws a 2 by 2 unit box at the coordinates
(5,5) to (7,7) in current units.
Sets the bottom margin for the current and subsequent pages. The
size of the margin is specified in the current units from the bottom
of the page.
Syntax
See also “FILLBOX” on page 175
“LINEWIDTH” on page 178
“PLACEXY” on page 185
“RBOX” on page 186
“RFILLBOX” on page 187
“UNITS” on page 193
{{bm margin}}
Example {{bm 0.5}}
The example sets the bottom margin to 1/2 a unit from the bottom
of the page.
See also “LM” on page 179
“TM” on page 191
“UNITS” on page 193
BOX
Draws a box in the current line width at the specified coordinates,
optionally filling it with text. The coordinates can be formatted (x,y)
or (x y). The coordinates can be specified values, or you can
specify a position relative to the current cursor position.
If only one coordinate pair is specified, the other coordinate pair is
assumed to be the current position. Therefore, {{box (5,5)}} is
equivalent to {{box (x,y) (5,5)}}.
{{box coord1 coord2 [“text”]}}
CC
Stores the SMTP address for a carbon copy recipient of a
document sent by email. To store multiple addresses, repeat this
command for each recipient. This command is only available if you
have licensed the InternetLink Module.
Syntax
{{cc address}}
Example {{cc [email protected]}}
{{cc [email protected]}}
The examples send a copy of the e-mail message to both
[email protected] and [email protected]
See also “TO” on page 191
“FROM” on page 177
“SUBJECT” on page 190
170
CLEARTABS
Removes all tab stops from the document.
Syntax
{{cleartabs}}
Example {{cleartabs}}
See also “SETTAB” on page 189
“TAB” on page 190
COMMENT
Stores a user-defined message specific to the document.
Syntax
{{comment comments}}
Example {{comment Inv# 12345}}
The example associates the comment “Inv# 12345” with the
document.
{{Comment}} translates to the RightFax server field to_citystate.
See ”Using Cover Sheets in a Broadcast” on page 130.
COMPANY
Stores a company name for the document.
Syntax
{{company name}}
Example {{company ABC Incorporated}}
The example associates the company name “ABC Incorporated”
with the document.
The example associates the contact name “Kim Boston” with the
document.
{{Contact}} translates to the RightFax server field to_name. See
”Using Cover Sheets in a Broadcast” on page 130.
COVER
Specifies a cover sheet template for the current document. You can
specify the file name of a cover sheet template, or you can specify
that a cover sheet should not be included.
The file name can be either a full path or a path relative to
RightFax\Production\Covers (this path is for RightFax Integration
Module cover sheets; RightFax server cover sheets are stored in a
different folder on the RightFax server). If the complete file name is
not found, the RightFax RightFax Integration Module tries to open
the file by adding a .cov extension. If this fails, the cover sheet is
assumed to be a RightFax .pcl or .doc cover sheet. If no cover
command is specified in a document, the default cover sheet
defined in the RightFax RightFax Integration Module Configuration
program is used.
Syntax
{{cover template}}
Example {{cover sales}}
The example specifies the sales or Sales.cov file in
RightFax\Production\Covers should be used as a template for the
cover sheet of the current document.
{{Company}} translates to the RightFax server field to_company.
See ”Using Cover Sheets in a Broadcast” on page 130.
CONTACT
Stores the contact name for the document.
Syntax
{{contact name}}
Example {{contact Kim Boston}}
171
OpenText RightFax 10.5 Integration Module Guide
Specific cover names
The {{cover}} command can contain the following special cover
names:
z
z
None. No cover sheet is generated, even if you have defined a
default cover sheet in the RightFax RightFax Integration Module
Configuration program.
Rfdefault. The default cover sheet action associated with the
user is performed.
Examples If a cover sheet is not defined for the user sending the
fax:
{{COVER NONE}} — No cover sheet is sent.
{{COVER RFDEFAULT}} — No cover sheet is sent.
{{COVER FCS.PCL}} — Specified RightFax server (.pcl)
cover sheet is sent.
{{COVER PROD.COV}} — Specified RightFax
Integration Module (.cov) cover sheet is sent.
If a cover sheet is defined for the user sending the fax:
{{COVER NONE}} — No cover sheet is sent.
{{COVER RFDEFAULT}} — Default cover sheet is sent.
{{COVER FCS.PCL}} — Specified RightFax server (.pcl)
cover sheet is sent.
{{COVER PROD.COV}} — Specified RightFax
Integration Module (.cov) cover sheet is sent.
COVERTEXT
This command creates text that should appear on the cover sheet.
Input between {{covertext}} and {{endcovertext}} (page 173) will
be displayed a text block in the document cover sheet.
The RightFax Integration Module extracts the text between
{{covertext}} and {{endcovertext}} commands. If PostScript
commands appear in the text, they will not be stripped out.
Therefore, do not embed PostScript between {{covertext}} and
{{endcovertext}}.
{{Covertext}} translates to the RightFax server field notetext. See
”Using Cover Sheets in a Broadcast” on page 130.
An index number is used to create a block of text within a single
cover sheet. Each instance of a ^covertext keyword in the cover
sheet template will be replaced by the corresponding text enclosed
between {{covertext}} and {{endcovertext}} commands. If no index
number is specified, the text will be linked to the ^covertext 0
keyword.
Each instance of {{covertext}} must use a different index number (0
in the example), corresponding to a numbered ^covertext field. 0 is
the most frequently used number.
Note 0 (zero) is the only option for RightFax server (.pcl or .doc) cover
sheets. See ”Using Cover Sheets in a Broadcast” on page 130.
Syntax
{{covertext indexnumber}}
Example {{covertext 0}}
CSI
Places text on the cover sheet. This text usually is the general fax
number for the enterprise. This command is valid only in cover
sheets.
Syntax
{{csi string}}
Example {{csi 503-555-5481}}
This example prints “503-555-5481” on the cover sheet.
{{Csi}} translates to the RightFax server field from_phone. See
”Using Cover Sheets in a Broadcast” on page 130.
DATE
Sets the month, day, and optionally the year in which to send the
current document. {{Date}} can be combined with {{time}} to
establish both a day and time to send a document.
172
The slashes between the month, day, and year are required. If no
{{date}} command is specified, the RightFax Integration Module
uses the date the FCL input file was received from the host.
Syntax
{{date month/day/year}}
Examples {{date 11/2}}
{{date 11/20/2004}}
The first example specifies that the current document is to be
transmitted on November 2.
The second example specifies that the document is to be
transmitted on November 20, 2004.
See also “TIME” on page 191
EMAIL
Stores the sender’s e-mail address. This is usually used for routing
a notification back to the sender that the document has been
processed, has transmitted, or has failed to transmit
Syntax
Example {{email [email protected]}}
The example stores the email address [email protected] for use in
notifications.
EMPID
Specifies the employee ID of the fax owner.
Syntax
DELAY
Schedules the document to be sent at a later time by the specified
number of minutes.
Syntax
{{delay minutes}}
Example {{delay 10}}
The example adds 10 minutes to the scheduled send time of the
document.
See also “BATCH” on page 166
“DATE” on page 172
“TIME” on page 191
{{empid ID}}
Example {{empid 555-111-2222}}
The example specifies that the employee ID associated with this fax
is 555-111-2222.
END
Terminates the current document. This command is required in
every FCL document. FCL documents may contain multiple
{{begin}} and {{end}} commands, but the FCL between each set of
commands will be rendered as a separate page.
Syntax
{{end}}
Example {{end}}
DEPT
This string can be used to specify the department of the fax owner
or the recipient’s department.
Syntax
{{email address}}
{{dept department}}
Example {{dept Sales}}
The example specifies that the department associated with this fax
is “Sales”.
See also “BEGIN” on page 166
ENDCOVERTEXT
Ends the storing of cover sheet text and tells the RightFax RightFax
Integration Module to again interpret incoming data.
Syntax
{{endcovertext}}
Example {{endcovertext}}
173
OpenText RightFax 10.5 Integration Module Guide
ENDCVT
Ends the conversion of an embedded foreign document that was
begun with the {{begincvt}} command.
Syntax
{{endcvt}}
Example {{endcvt}}
See also “BEGINCVT” on page 167
If document processing is performed on a RightFax WorkServer,
and if the FCL document contains a print command, then the
{{execute}} command will force printing to occur from the
WorkServer whether or not the Print service is enabled.
Syntax
Example {{execute}}
See also “END” on page 173
“FAX” on page 174
ENDNATIVE
Ends the processing of an attached native document that was
begun with the {{beginnative}} command.
Syntax
{{endnative}}
Example {{endnative}}
See also “BEGINNATIVE” on page 167
ENDPOLY
Ends the current polygon, drawing a line from the current position
to the first vertex of the polygon, using the current line width.
{{Endpoly}} is used in conjunction with {{startpoly}}.
{{execute}}
FAX
Assigns the fax number where the document will be sent. If this is
not the first fax number specified for this document, the document
is ended, and a new document begins with all the images of the
original. The last page can be updated and new pages can be
added, but prior pages will remain the same as in the original. By
specifying multiple fax numbers, broadcasts to many different
destinations can be made. If you have the InternetLink Module, then
you can also insert an e-mail address into the fax command and
documents will be e-mailed.
{{endpoly}}
{{fax number}}
{{fax email address}}
Example {{endpoly}}
Example {{fax 555-555-5458}}
See also “LINEWIDTH” on page 178
The example assigns the fax number 555- 555-5458 to the
document.
Syntax
“STARTPOLY” on page 189
Syntax
See also “TYPE” on page 192
EXECUTE
Ends the current document, executes the commands to this point
and begins a new document without clearing the previous image.
Most of the attributes of the original document are preserved,
except for the following, which are cleared: {{altfax}}, {{company}},
{{contact}}, {{cover}}, and {{fax}}.
{{Fax}} translates to the RightFax server field to_faxnum. See
”Using Cover Sheets in a Broadcast” on page 130.
174
FF
Acts as a form feed in the FCL input file. It begins a new page at
the current left and top margins, just as if an ASCII form feed
character had come from the host application.
Syntax
{{ff}}
Example {{ff}}
Syntax
{{fillbox coord1 coord2 color}}
Examples {{fillbox (0,y) (7,7) white}}
{{fillbox 5 5 7 7)
FILE
Stores all subsequent input (until an {{end}} command) into the
specified file name. You can specify the full path to the file. The
default is RightFax\Production \Include. {{File}} differs from {{list}}
in that it does not strip leading white space or blank lines.
Syntax
If only one coordinate pair is specified, the other coordinate pair is
assumed to be the current position. Therefore, {{fillbox (5,5)}} is
equivalent to {{fillbox (x,y) (5,5)}}. If both coordinate pairs are
specified, you can specify a fill color. The color can be black or
white; the default is black.
{{file name}}
Example {{file test.inc}}
The example writes all subsequent input until an {{end}} command
is encountered to the file RightFax\Production \Include\test.inc.
Note: Newly-created include files may not be immediately available
due to Windows delays. If this occurs, try placing the {{file}} command in
a separate document, and submit it before the document that uses the
{{include}} command to reference the file.
The first example draws a box from the left side of the page at the
current line to 7 units over, and 7 units down the current page,
filling it in with white. This could be useful for covering up
information after an {{execute}} command.
The second example draws a 2 by 2 unit filled black box at the
coordinates (5,5) to (7,7) in current units.
See also “BOX” on page 170
“LINEWIDTH” on page 178
“RBOX” on page 186
“RFILLBOX” on page 187
“UNITS” on page 193
See also “LIST” on page 178
FILLBOX
Draws a box in the current line width at the specified coordinates,
filling it with black or white (the default is black). The coordinates
can be formatted (x,y) or (x y). The coordinates can be specified
values, or you can specify a position relative to the current cursor
position.
175
OpenText RightFax 10.5 Integration Module Guide
FONT
Table Bb Font Attributes (Continued)
Changes the font currently in use and, optionally, the attributes of
the font. The available font attributes are described in the following
table.
Attribute
Description
Italic
Italicize a Windows font.
Strikeout
Draw a horizontal line through the text.
Table Bb Font Attributes
Attribute
Description
Name
The name of the font. This can be one of the fonts
installed with the RightFax Integration Module, a
TrueType font, or any font supported by Microsoft
Windows.
Fonts are installed in Rightfax\Production\Fonts.
The font name is used for all subsequent text until
another {{font}} command appears in the
document or until the end of the document.
Size
The size of a Windows font in points. The default is
12. The size can range from 3 to 288.
This attribute is not available for the installed fonts.
Leading
The vertical spacing for the lines of text in points.
This indicates the number of points to move down
from the baseline of the current line to the baseline
of the following line. A higher number increases the
amount of vertical space used. One inch is 72
points. Thus, a leading of 12 points is 6 lines per
inch (72 divided by 12 equals 6). You can enter
leading in decimals.
Pitch
The horizontal spacing in characters per inch. A
higher number decreases the amount of horizontal
space used. A pitch of 10 is 10 characters per
horizontal inch. You can enter pitch in decimals.
Weight
The weight of a Windows font. Weights are thin,
extralight, light, regular, medium, semibold, bold,
extrabold, and heavy.
This attribute is not available for the installed fonts.
For more information on the installed fonts and support for
TrueType fonts, see “Selecting and Configuring Fonts” on page 67.
Syntax
{{font name [size=##] [leading=##] [pitch=##]
[weight] [italic] [strikeout]}}
Examples {{font courb12 leading=14 pitch=10}}
{{font timbi10}}
{{font “times new roman” size=24 extrabold italic}}
The first example sets the current font to Courier Bold 12-point,
with 14 points of leading and 10 characters per inch.
The second example sets the current font to Times Bold Italic
10-point, with default leading. Without specifying leading and
pitch, this font will be proportional and vertical columns will not line
up.
The third example uses the Microsoft Windows TrueType font
Times New Roman, size 24, extra bold, and italic.
FORM
Specifies a Class F TIF file to be overlaid on the current and
subsequent pages. The specified form name can include the full
path to the file or a path that is relative to
RightFax\Production\Forms. The form is normally placed with the
upper-left corner at (0,0) on the page. You can specify the location
176
with x- and y-coordinates. Placement is relative to the upper-left
corner of the current orientation, regardless of the current
{{placexy}} value.
Alternatively, you can use this code to specify that no form should
be overlaid.
Syntax
{{form name coord}}
Examples {{form order 0.5 0.2}}
{{form none}}
IMAGETYPE
Selects the graphic format of a {{type mime}} document. This
command is only available if you have licensed the InternetLink
Module. The default graphic format for {{type mime}} documents is
Group 4 TIFF.
Syntax
{{imagetype {pdf|group3|group4|pcx}}}
Example {{imagetype pdf}}
The first example sets the form to
The example identifies PDF as the graphic format for a {{type
mime}} document.
RightFax\Production\Forms\order
See also “TYPE” on page 192
or
RightFax\Production\Forms\order.tif
and places it at (0.5, 0.2) on the page in current units.
The second example specifies that there is no form to be overlaid.
See also “PLACE” on page 184
“UNITS” on page 193
FROM
The sender’s email address. This command is only available if you
have licensed the InternedLink Module.
Syntax
{{from emailaddress}}
Examples {{from [email protected]}}
See also “TO” on page 191
“CC” on page 170
“SUBJECT” on page 190
INCLUDE
Includes an FCL input file in the input stream. Input from an include
file is interpreted just as if it came from the host application. Include
files are useful when the same input is needed in many files. You
can specify the full path to the file. The default is
RightFax\Production\Include. If the include file cannot be found, the
RightFax Integration Module tries again, adding .inc to the file
name.
Syntax
{{include filename}}
Example {{include setup}}
The example includes input from the file
RightFax\Production\Include\setup. If that file does not exist, then it
would include input from the file
RightFax\Production\Include\setup.inc.
Note: Newly-created include files may not be immediately available
due to Windows delays. If this occurs, try placing the {{include}}
commands in a separate document, and submit it after the document that
uses the {{file}} or {{list}} command to create the file.
177
OpenText RightFax 10.5 Integration Module Guide
LIBDOC
LINETO
Attaches the specified RightFax library document.
Syntax
{{libdoc ID}}
Example {{libdoc InfoPack1}}
The example attaches the library document called InfoPack1 to the
end of the base document.
Library documents are frequently faxed documents (such as
company literature, credit applications, and employment forms) that
you create with FaxUtil. RightFax stores these in the
RightFax\Image folder. For more information on library documents,
see the RightFax Administrator’s Guide.
Draws a line in the current line width on the current page from the
current position to the specified coordinates in current units. The
coordinates can be formatted (x,y) or (x y). The coordinates can be
specified values, or you can specify a position relative to the
current cursor position.
Syntax
Example {{lineto (3,5)}}
The example draws a line from the current cursor position to (3,5)
in current units.
See also “LINETO” on page 178
“LINEWIDTH” on page 178
“RLINE” on page 187
“RLINETO” on page 188
“UNITS” on page 193
LINE
Draws a line in the current line width on the current page at the
specified coordinates in the current units. The coordinates can be
formatted (x,y) or (x y). The coordinates can be specified values, or
you can specify a position relative to the current cursor position. If
both pairs of coordinates are not specified, {{line}} draws a
horizontal line across the page under the baseline in the current
font.
Syntax
{{line [coord1] [coord2]}}
Examples {{line (2,3) (4,5)}}
{{line}}
The first example draws a line from coordinates (2,3) to (4,5) in
current units.
The second example draws a line under the current font baseline.
See also “LINETO” on page 178
“LINEWIDTH” on page 178
“RLINE” on page 187
“RLINETO” on page 188
“UNITS” on page 193
{{lineto (coord)}}
LINEWIDTH
Sets the width to draw lines in points. A point is 1/72nd of an inch.
A {{linewidth}} command with zero as the number of points
indicates that no line is to be drawn. Any other line width will be
rendered at least one pixel wide (approximately 1/200th of an inch).
The default line width is one pixel (approximately 1/3 point).
Syntax
{{linewidth points}}
Example {{linewidth 1}}
The example sets the line width to 1 point, or 1/72nd of an inch
(about 3 pixels).
See also “LINE” on page 178
LIST
Writes subsequent input (until an {{end}} command) to the
specified file name. You can specify the full path to the file. The
default is RightFax\Production\Include. This process will replace a
178
file of the same name. {{List}} differs from {{file}} only in that it will
strip any leading white space or blank lines from the input. {{List}}
is useful in creating and replacing broadcast lists.
Syntax
{{list filename}}
The lookup FCL code uses the specified criteria to look up
information in a table contained in a lookup file and then associate
that information with other information.
Syntax
{{lookup criteria table}}
Example {{list bcast.inc}}
Example {{lookup AC123}}
The example writes subsequent input (until an {{end}} command) to
RightFax\Production\Include\bcast.inc.
The example instructs the software to find the entry AC123 in a
lookup table. A lookup table might look like this:
Note: Newly-created include files may not be immediately available
due to Windows delays. If this occurs, try placing the {{list}} command in
a separate document, and submit it before the document that uses the
{{include}} command to reference the file.
See also “FILE” on page 175
LM
Sets the current left margin for rendering text, immediately
changing the current position to reflect the new value. The width of
the margin is specified in current units from the left edge of the
page.
Syntax
{{lm margin}}
AC123{{company ACME Corp}}{{contact John Doe}}
OC456{{company Oregon Corp}}{{contact Jane Doe}}
Default{{company Arizona Corp}}{{contact Mary Doe}}
If you use {{lookup AC123}}, the software would insert “ACME
Corp” and “John Doe” into the document. If you made an error,
such as {{lookup AC234}} (which does not exist in the lookup
table), then the software would insert the default information. If you
do not specify the path to the lookup table, the default is
RightFax\Production\Include.
LP, LPR, or PRINTER
Sets the default printer for the print FCL commands such as {{type
print}} and {{printnow}}.
Example {{lm 0.5}}
Syntax
The example sets the left margin to 1/2 a unit from the left edge of
the page, and moves to that location.
Example {{lp local}}
See also “BM” on page 170
See also “PRINTNOW” on page 186
“TM” on page 191
“UNITS” on page 193
{{lp|lpr|printer name}}
The example sets the printer name to local.
“TYPE” on page 192
LOOKUP
A lookup table can provide information that is not contained in the
document that is sent from the host application, such as the
recipient company name, fax number, e-mail address, and contact
name.
179
OpenText RightFax 10.5 Integration Module Guide
MOVETO
Changes the current position to the specified coordinates in units.
The coordinates can be formatted (x,y) or (x y). The coordinates can
be specified values, or you can specify a position relative to the
current cursor position.
Syntax
{{moveto coord}}text
Examples {{moveto 3,4}}Put this here.
{{moveto x,5}}Put this here.
The first example changes the position to (3,4) in current units.
The second example maintains the x position and moves vertically
to 5 units down the page.
To specify a position relative to the current x- or y-coordinate, enter
x or y in the command line. X is not a valid y-coordinate, and y is
not a valid x-coordinate.
See also “POSITION” on page 185
“RMOVETO” on page 188
“UNITS” on page 193
Using the {{moveto}} command in a Unix system
If you are using the {{moveto}} command in a Unix system that
generates FCL documents, you must add a value to the Windows
registry in order to support the command. On the RightFax server,
edit the Windows registry. Navigate to the subkey
HKEY_LOCAL_MACHINE\Software\RightFax\Parse. Add the
REG_MULTI_SIZE registry value UnixSpecials. Enter the string
MoveTo in the multi-string editor.
NOCOVER or NO_COVER
Same as {{cover none}} (page 171). No cover sheet is generated,
even if you have defined a default cover sheet in the RightFax
Integration Module Configuration program.
Syntax
{{nocover}}
Example {{nocover}}
The example allows the document to be processed with no cover
sheet.
NOTE
Same as {{REM}} (page 187). Inserts any information; is commonly
used for troubleshooting. It has no effect on the document.
Syntax
{{note text}}
Example {{note This came from the PO system}}
The example inserts “This came from the PO system” into the FCL
but not into the finished document.
NOTIFYHOST
Specifies the templates to be used to format the success or failure
of the transmission of the document. It also can specify which
channel ID to use to send the notifications. The template files (in
the syntax below, these are Successtemplate.inc for successful
documents and Failuretemplate.inc for failed documents) describe
the notification that should be sent to the host application.
If a template name is not specified, then no notification will be sent.
The channel specifies the notification channel that will send the
notification message. The channel can be specified with an ID
number (from 1 to 128) or the name assigned to the channel. If no
channel is specified, the default channel will be used, number 16.
Syntax
{{notifyhost successtemplate failuretemplate
[channel]}}
Example {{notifyhost mysucc myfail mynotify}}
The example shows that, if the document is sent successfully, the
RightFax RightFax Integration Module generates a notification
message using the RightFax\Production\Include\Mysucc
or
180
RightFax\Production\Include\Mysucc.inc notification templates.
Similarly, the Myfail template will be used if the fax is not
successfully sent. Notifications spool to the Mynotify channel.
See also “ONERROR” on page 181
“ONSUCCESS” on page 182
Table Bc Onerror Options (Continued)
Option
Description
Email or
mime
If a transmission error occurs in faxing, the document
will be sent via e-mail. This option requires that you have
licensed the InternetLink Module.
See ”Creating FCL Documents with InternetLink
Commands” on page 149.
ONERROR
Describes what the RightFax RightFax Integration Module does in
the event the document fails during transmission. This command
overrides the settings you establish in the RightFax Integration
Module Configuration program for each document in which you
use the {{onerror}} command. See ”Creating Notification
Templates” on page 73.
Fax
If you don’t enter a fax number, the software uses the
default number specified in the RightFax Integration
Module Configuration program . See ”Setting
Defaults for FCL Documents” on page 126.
Note: This command specifies actions based on transmission failures
only. It does not apply to transmissions that are blocked by a dialing rule.
Options for {{onerror}} are fax, delete, email (or mime), certified,
nothing, or print.
Nothing
Table Bc Onerror Options
Option
Description
Certified
If a transmission error occurs in faxing, the document
will be sent as a certified e-mail document. This option
requires that you have licensed the SecureDocs
Module.
You can configure a notification to alert you that a
document failed as a fax and was sent as a certified
e-mail. See ”Creating Notification Messages with
FCL” on page 72.
Delete
If a transmission error occurs in faxing, the document
will be sent via fax to another fax number. Specify the fax
number and whether to delete the fax image after
transmission. The fax number you enter must be
contiguous (no spaces or tabs).
If a transmission error occurs in faxing, no special action
is taken. This overrides any defaults you set with the
RightFax Integration Module Configuration program.
See ”Setting Defaults for FCL Documents” on
page 126.
Print
If a transmission error occurs in faxing, the document
will print. Enter a printer ID defined in Enterprise Fax
Manager.
If you don’t enter a printer, the software uses the default
printer specified in the RightFax Integration Module
Configuration program. See ”Setting Defaults for FCL
Documents” on page 126.
If a transmission error occurs in faxing, the fax image will
be deleted. If you use {{onerror delete}}, then
successful faxes also will be deleted.
181
OpenText RightFax 10.5 Integration Module Guide
Syntax
{{onerror nothing}}
{{onerror delete}}
{{onerror fax number delete}}
{{onerror email|mime|certified address delete}}
Examples {{onerror fax 503-555-1234 delete}}
{{onerror email [email protected]}}
{{onerror certified [email protected]}}
Options for {{onsuccess}} are fax, delete, email (or mime), certified,
nothing, or print.
Table Bd Onsuccess Options
Option
Description
Certified
When a transmission succeeds in faxing, the document
will also be sent as a certified e-mail document. This
option requires that you have licensed the SecureDocs
Module.
The first example shows that, upon failed transmission, all pages
will be faxed to 503-555-1234 and then deleted.
You can configure a notification to alert you that a
document was sent as a certified e-mail. See
”Creating Notification Messages with FCL” on
The second example shows that, upon failed transmission, the
document will be e-mailed to [email protected] via the InternetLink
Module.
The third example shows that, upon failed transmission, the
document will be e-mailed to [email protected] as a certified
document via the SecureDocs Module.
For more information on the SecureDocs Module, see the RightFax
SecureDocs Module Guide.
page 72.
Delete
When a transmission succeeds in faxing, the fax image
will be deleted.
Email or
mime
When a transmission succeeds in faxing, the document
will also be sent via e-mail. This option requires that you
have licensed the InternetLink Module.
See also “NOTIFYHOST” on page 180
You can configure a notification to alert you that a
document was sent as an e-mail. See ”Creating
Notification Messages with FCL” on page 72.
“ONSUCCESS” on page 182
{{Onerror delete}} translates to the RightFax server field
faxflag_autodeleteall. See ”Creating and Attaching Cover Sheets
and Other Files” on page 49.
Fax
ONSUCCESS
Describes what the RightFax RightFax Integration Module does in
the event the document transmits successfully. This command
overrides the settings you establish in the RightFax Integration
Module Configuration program for each document in which you
use the {{onsuccess}} command. See ”Setting Defaults for FCL
Documents” on page 126.
When a transmission succeeds in faxing, the document
will be sent via fax to another fax number. Specify the
fax number and whether to delete the fax image after
transmission. The fax number you enter must be
contiguous (no spaces or tabs).
If you don’t enter a fax number, the software uses the
default number specified in the RightFax Integration
Module Configuration program. See ”Setting Defaults
for FCL Documents” on page 126.
Nothing
When a transmission succeeds in faxing, no special
action is taken. This overrides any defaults you set with
the RightFax Integration Module Configuration
program. See ”Setting Defaults for FCL Documents”
on page 126.
182
Table Bd Onsuccess Options (Continued)
Option
Description
Print
When a transmission succeeds in faxing, the document
will print. Enter a printer ID defined in Enterprise Fax
Manager.
If you don’t enter a printer, the software uses the default
printer specified in the RightFax Integration Module
Configuration program. See ”Setting Defaults for
FCL Documents” on page 126.
Syntax
{{onsuccess nothing}}
{{onsuccess delete}}
{{onsuccess fax number delete}}
{{onsuccess email|mime|certified address delete}}
Examples {{onsuccess fax 503-555-1234 delete}}
{{onsuccess email [email protected]}}
{{onsuccess certified [email protected]}}
The first example shows that, upon successful transmission, all
pages of the document are faxed to 503-555-1234 and then
deleted.
The second example shows that, after successful fax transmission,
the document will be e-mailed to [email protected] via the
InternetLink Module.
The third example shows that, after successful fax transmission, the
document will be e-mailed to [email protected] as a certified
document via the SecureDocs Module.
For more information on the SecureDocs Module, see the RightFax
SecureDocs Module Guide.
ORIENT
Sets the page orientation for subsequent text and moves the
current position to (0,0) on the page. Text specified prior to the
{{orient}} command will be rendered in the prior page orientation.
Syntax
{{orient {portrait|landscape}}}
Example {{orient portrait}}
The example sets the page orientation to portrait for subsequent
text and graphic blocks.
OWNER
Specifies the document owner’s name.
Syntax
{{owner name}}
Example {{owner Jane Doe}}
The example specifies the owner of this document as “Jane Doe.”
{{Owner}} translates to the RightFax server field from_name. See
”Using Cover Sheets in a Broadcast” on page 130.
PDFUSER
For use when sending an encryped PDF through the SecureDocs
module, this command specifies the password and permission levels
for the PDF.
Syntax
{{pdfuser name p}}
Example {{pdfuser “#MNid4” 31}}
In the example, “#MNid4” is the user’s password, and the user has
full permissions.
See also “NOTIFYHOST” on page 180
“ONERROR” on page 181
{{Onsuccess delete}} translates to the RightFax server field
faxflag_autodelete. See ”Using Cover Sheets in a Broadcast” on
page 130.
183
OpenText RightFax 10.5 Integration Module Guide
Permission is an integer bit-wise value that grants certain
permissions for the user as described in the following table.
Table 0a Bit Values for PDF Permissions
By default, the graphic is placed in the upper-left corner. The
placement can be specified with the {{placexy}} command.
{{Place}} is also affected by the current page orientation and
measurement units.
{{place graphic coord}}
Bit Permission Notes
Syntax
1
Print
The user can print the PDF.
Example: {{pdfuser “#MNid4” 1}}
Example {{place yoyodyne.tif 5 4}}
2
Edit
The user can edit the PDF.
4
Select
Example: {{pdfuser “#MNid4” 3}}
This example sets print and edit permissions.
The example places the graphic image Yoyodyne.tif on the page at
(5,4) in specified units that you set in the RightFax Integration
Module Configuration program. See ”Setting Defaults for FCL
Documents” on page 126.
The user can select and copy text.
See also “PLACEXY” on page 185
Example: {{pdfuser “#MNid4” 7}}
This example sets print, edit, and select
permissions.
8
Annotate
The user can add annotations.
Example: {{pdfuser “#MNid4” 15}}
This example sets print, edit, select, and
annotate permissions.
16
Save As
The user can save the PDF to a new file name.
Example: {{pdfuser “#MNid4” 31}}
This example sets print, edit, select, annotate,
and save as permissions.
PLACE
Positions the specified Class F TIF image on the page. The file can
be specified using the full path or relative to
RightFax\Production\Forms. You can specify the placement of the
image using x- and y-coordinates. If no coordinates are specified,
the graphic is placed at the current cursor location.
“PLACEALL” on page 184
PLACEALL
Places the specified graphic image on the current and all
subsequent FCL pages (but not on file attachments). The file can
be specified using the full path name or a path relative to
RightFax\Production\Forms. Optionally, x- and y-coordinates can
be specified in current units. If no coordinates are specified, the
graphic is placed at the current x and y location.
You can use multiple {{placeall}} commands.
By default, the graphic block is placed in the upper-left corner. The
position can be specified with the {{placexy}} command.
{{Placeall}} is also affected by the current page orientations and
measurement units.
Syntax
{{placeall graphic x y}}
Example {{placeall yoyodyne.tif 5 4}}
See also “PLACE” on page 184
“PLACEXY” on page 185
184
The example places the file Yoyodyne.tif in the current and all
subsequent pages at the location 5 4 (in units, such as inches or
centimeters, that you set in the RightFax Integration Module
Configuration program. See ”Setting Defaults for FCL Documents”
on page 126.
PLACELAST
Places the specified graphic image on the last page. The file can
be specified using the full path name or a path relative to
RightFax\Production\Forms. Optionally, x- and y-coordinates can
be specified in current units. If no coordinates are specified, the
graphic is placed at the current x and y location.
to the current position of the cursor. When adding text in a box,
{{placexy}} describes the location of the text in the box. If no
{{placexy}} command is specified, left and top are used.
Syntax
{{placexy horizontal vertical}}
Example {{placexy center center}}
The example instructs the RightFax RightFax Integration Module to
interpret coordinates in subsequent {{place}} commands as the
horizontal and vertical center of the graphic block and to
horizontally and vertically center text in subsequent {{box}} or
{{rbox}} commands.
See also “PLACE” on page 184
You can issue multiple {{placelast}} commands.
By default, the graphic block is placed in the upper-left corner. The
placement can be specified with the {{placexy}} command.
{{Placelast}} is also affected by the current page orientations and
measurement units.
Syntax
{{placelast graphic x y}}
POSITION
Changes the current location on the page according to the
currently selected font. The coordinates can be formatted (x,y) or
(x y).
Syntax
{{position coord}}
Example {{placelast yoyodyne.tif 5 4}}
Example {{position 5, 20}}
See also “PLACE” on page 184
The example moves the position to the fifth column of the twentieth
row of the page (using the specified font as the guide to the
character size).
“PLACEXY” on page 185
The example places the file Yoyodyne.tif in the last page at the
location 5 4 (in units, such as inches or centimeters) that you set in
the RightFax Integration Module Configuration program. See
”Setting Defaults for FCL Documents” on page 126.
See also “MOVETO” on page 180
“RMOVETO” on page 188
PREVIEW
PLACEXY
Specifies how graphic images and box text should be placed on
the page. Horizontal placement can be left, center, or right. Vertical
placement can be top, center, or bottom. When placing graphic
images, {{placexy}} denotes the placement of the graphic relative
Holds the document for preview in the FaxUtil mailbox.
Syntax
{{preview}}
Example {{preview}}
PRINTER
See
“LP, LPR, or PRINTER” on page 179
185
OpenText RightFax 10.5 Integration Module Guide
PRINTNOW
QUALITY
Prints a copy of the current document immediately. You can specify
the number of copies to print. If the number of copies is not
specified, the default is one copy.
Syntax
{{printnow print copies}}
Example {{printnow print 2}}
The example immediately prints two copies of the document.
See also “TYPE” on page 192
“LP, LPR, or PRINTER” on page 179
Specifies the fax resolution at which the document will send.
Standard resolution is 204 x 98 dots-per-inch (dpi). Fine resolution
is 204 x 196 dpi. {{Quality}} only affects the vertical resolution.
{{Quality}} should be set on the first page of a document and
maintained throughout the document. Otherwise, pages will stretch
or compress when sent. If no {{quality}} command is specified, the
default transmission quality in RightFax Integration Module
Configuration program is used.
Syntax
{{quality {standard|fine}}}
Example {{quality fine}}
PRIORITY
Specifies the priority at which the document is to be processed
and scheduled. High priority documents will be processed and
sent before low priority documents of the same scheduled time. If
no {{priority}} command is specified, low priority is assumed.
Priority can be 0, 1, or 2, representing low, medium, or high.
Normal is the same as medium. If you do not insert a priority
command, the default is low (0) priority.
Syntax
{{priority {low|0|medium|normal|1|high|2}}}
Example {{priority high}}
{{priority 2}}
Both examples specify a high priority, because “2” is equivalent to
“high.”
See also “DATE” on page 172
“TIME” on page 191
{{Priority}} translates to the RightFax server field ucPriority.
The example sets the fax quality for the document to fine (204 x
196 dpi).
{{Quality}} translates to the RightFax server field finemode.
RBOX
Draws a box in the current line width at the specified coordinates,
optionally filling it with the specified text. The coordinates can be
formatted (x,y) or (x y). The coordinates can be specified values, or
you can specify a position relative to the current cursor position. If
only one coordinate pair is specified, the other coordinate pair is
assumed to be the current position. Therefore, {{rbox (5,5)}} is
equivalent to {{rbox (0,0) (5,5)}}. If both coordinate pairs are
specified, you can embed a line of text. The text must be
surrounded by quotation marks and is limited to one line. The text is
placed in the box according to the current {{placexy}} settings,
which default to the upper-left corner.
Syntax
{{rbox coord1 coord2 “text”}}
Examples {{rbox (0,3) (2,4) “Hi There”}}
{{rbox -1 -1 1 1}}
The first example draws a box 3 units down from the current
position to 2 units across and 4 units down, placing the text “Hi
There” within it.
186
The second example draws a 2-by-2-unit box one unit back and
one unit up from the current position, centering it on the current
position.
Therefore, {{rfillbox (5,5)}} is equivalent to {{rfillbox (0,0) (5,5)}}. If
both coordinate pairs are specified, you can specify a fill color. The
color can be black or white.
See also “BOX” on page 170
Syntax
Example {{rfillbox (3,3) white}}
REM
{{rfillbox -1 -1 1 1}}
Same as “NOTE”. Inserts any information; is commonly used for
troubleshooting. It has no effect on the document.
Syntax
{{rem text}}
Example {{rem This came from the PO system}}
The example inserts “This came from the PO system” into the FCL,
but not into the finished document.
REPLYTO or REPLY_TO
Specifies a recipient for a notification. You can request that an
HTTP post be sent back to the host as a notification when you use
the RightFax XML Interface. REPLYTO is the field in the submit
post that the XML Interface populates to determine where to send
the notification.
Syntax
{{rfillbox coord1 coord2 color}}
{{replyto recipient}}
Example {{replyto www.opentext.com}}
The example specifies that the XML notification should return to
www.opentext.com.
The first example draws a box from the current position to 3 units
over and 3 units down from the current position, filling it in with
white. This could be useful for covering up information after an
{{execute}} command.
The second example draws a 2-by-2-unit filled black box at
coordinates (-1,-1) to (1,1) relative to the current position in current
units.
See also “BOX” on page 170
“FILLBOX” on page 175
RLINE
Draws a line in the current line width on the current page at the
specified relative coordinates in current units. The coordinates can
be formatted (x,y) or (x y). The coordinates can be specified values,
or you can specify a position relative to the current cursor position.
If either coordinate pair is not specified, {{rline}} draws a horizontal
line across the page just under the baseline of the current font.
Syntax
{{rline [(coord1) (coord2)]}}
Examples {{rline (2,3) (4,5)}}
RFILLBOX
Draws a box in the current line width at the specified relative
coordinates, filling it black or white (black if none is specified). The
coordinates can be formatted (x,y) or (x y). The coordinates can be
specified values, or you can specify a position relative to the
current cursor position. If only one coordinate pair is specified, the
other coordinate pair is assumed to be the current position.
{{rline}}
The first example draws a line from coordinates (2,3) to (4,5)
relative to the current position in the current units.
The second example draws a line under the current font baseline.
See also “LINE” on page 178
“UNITS” on page 193
187
OpenText RightFax 10.5 Integration Module Guide
RLINETO
Draws a line in the current line width on the current page from the
current position to the specified relative coordinates in current
units. The coordinates can be formatted (x,y) or (x y). The position is
relative to the current cursor position in the current units.
at a point 4,5 units from the upper-left corner of the fax. The
command {{rstartpoly 4,5}} would begin a polygon at a point 4,5
units from the current cursor location.
The example draws a line from the current cursor position to (3,5)
in current units.
By itself, {{rstartpoly}} does not create a polygon; it establishes the
starting point. Without the two {{lineto}} commands that create the
lines of the polygon (see example), {{rstartpoly}} creates nothing.
{{Endpoly}} closes the polygon by connecting the lines created by
the {{lineto}} commands. If you do not specify coordinates, the
polygon starts at the position in the document where the command
appears.
See also “LINE” on page 178
Syntax
Syntax
{{rlineto (coord)}}
Example {{rlineto (3,5)}}
“LINETO” on page 178
“LINEWIDTH” on page 178
“RLINE” on page 187
“UNITS” on page 193
RMOVETO
Changes the current cursor position to the specified relative
coordinates in the specified units. The coordinates can be
formatted (x,y) or (x y).
Syntax
Example {{rstartpoly 0,1}}{{lineto 7,y}}{{lineto 7,10}}{{endpoly}}
The example uses {{rstartpoly}} to begin a polygon at a point 0,1
units, relative to the current cursor location. Establish units, such as
inches or centimeters, in the RightFax Integration Module
Configuration program. See ”Setting Defaults for FCL
Documents” on page 126.
See also “ENDPOLY” on page 174
“LINETO” on page 178
“RLINETO” on page 188
“STARTPOLY” on page 189
“UNITS” on page 193
{{rmoveto coord}}
Example {{rmoveto 3,4}}
The example changes the position to (3,4) from the current position
in the specified units.
See also “MOVETO” on page 180
“POSITION” on page 185
“UNITS” on page 193
{{rstartpoly coord}}
RTI
Places text on the cover sheet. This usually is the name of the
sending company. This command is valid only in cover sheets.
Syntax
{{rti string}}
Example {{rti ABC Company}}
RSTARTPOLY
Moves the current cursor position to the relative coordinate
specified and starts a polygon. The coordinates can be formatted
(x,y) or (x y). This command is different from {{startpoly}} on
page 189. The command {{startpoly 4,5}} would begin a polygon
This example prints “ABC Company” on the cover sheet.
188
SETTAB
SIGNATURE
Creates a tab stop specified by identifiers in the command. The
identifiers are:
z
z
z
Any whole number starting with zero to identify a tab group. You
can specify up to 20 tabs in a document, numbered 0 through
19.
Any measurement to define the size (in inches) of the tab.
Alignment of the tab (C for center, L for left, R for right, D for
aligning decimals in a group of numbers).
Syntax
{{settab tab coord {l|r|c|d}}}
Examples {{settab 0 1.5 L}}
{{settab 1 2.5 C}}
The first example creates a global tab stop labeled group 0 at 1.5
inches, aligned left.
The second example creates a global tab stop labeled group 1 at
2.5 inches, aligned center.
See also “CLEARTABS” on page 171
“TAB” on page 190
SIGN, SIGNED, or @
Places the file specified by the {{signature}} command after you
have predefined a file name for {{signature}}. These three
commands insert a signature in the document.
After you have predefined {{signature}}, you can insert one of these
three commands to insert the signature in the document.
Syntax
{{{sign|signed|@}}}
Example {{sign}}
See also “SIGNATURE” on page 189
Specifies the name of a graphic file of a signature that should
appear in the document. The signature must be created and saved
as a graphic file.
Syntax
{{signature filename}}
Example {{signature FredJones.tif}}
See also “SIGN, SIGNED, or @” on page 189
SMS
Specifies the phone number of the SMS-capable device that will
receive notifications about the fax transmittion
Syntax
{{sms pagerID}}
Example {{sms 520-555-1212}}
See also “TYPE” (SMS) on page 192 and “SMSMSG” on
page 189
SMSMSG
Specifies the text of the SMS notification to send
Syntax
{{smsmsg text}}
Example {{smsmsg Fax was sent successfully}}
See also “TYPE” (SMS) on page 192 and “SMS” (SMS) on
page 189
STARTPOLY
Moves the current position to the coordinates specified and starts
a polygon. The coordinates can be formatted (x,y) or (x y). The
coordinates can be specified values, or you can specify a position
relative to the current cursor position.
189
OpenText RightFax 10.5 Integration Module Guide
{{Startpoly}} is different from {{rstartpoly}} (page 188).
z
z
{{Startpoly}} starts a polygon at coordinates that are relative to
the upper-left corner of the document. (You establish units, such
as inches or centimeters, in the RightFax Integration Module
Configuration program. See ”Setting Defaults for FCL
Documents” on page 126.
{{Rstartpoly}} starts a polygon at coordinates that are relative to
the location that the command appears in the document.
By itself, {{startpoly}} does not create a polygon; it establishes the
starting point. Without the two {{lineto}} commands that create the
lines of the polygon (see example), {{startpoly}} creates nothing.
{{Endpoly}} closes the polygon by connecting the lines created by
the {{lineto}} commands. If you do not specify coordinates, the
polygon starts at the position in the document where the command
appears.
Subsequent calls to {{lineto}} or {{rlineto}} specify the vertices of
the polygon, and {{endpoly}} is used to close the polygon. If no
coordinates are specified, the current position is used for the start
of the polygon.
Syntax
{{startpoly coord}}
Example {{startpoly (3,4)}}{{lineto 7,y}}{{lineto 7,10}}{{endpoly}}
The example starts a polygon at (3,4) in current units.
See also “ENDPOLY” on page 174
“RSTARTPOLY” on page 188
“UNITS” on page 193
SUBJECT
The subject line for an email. This command is only available if you
have licensed the InternedLink Module.
Syntax
{{subject topic}}
Examples {{subject January invoices}}
See also “TO” on page 191
“CC” on page 170
“FROM” on page 177
TAB
Creates a single tab stop based on the information you create with
the {{settab}} command.
Syntax
{{tab tab stop text|number}}
Examples {{tab 3 1048.01}}
{{tab 3 16.8575}}
{{tab 1 Hello world}}
The first two examples are of tab stops for a tab labeled group 3
(you defined this tab group with the {{settab}} command). For
these examples, if you defined group 3 tabs as {{settab 3 4.5 D}},
then the numbers 1048.01 and 16.8575 would appear with their
decimal points aligned vertically at 4.5 inches from the left margin.
The third example is of a tab stop for a tab labeled group 1. If you
defined group 1 tabs as {{settab 1 1.5 L}}, then the words “Hello
world” would appear aligned left at 1.5 inches from the left margin.
See also “CLEARTABS” on page 171
“SETTAB” on page 189
TERMID
Specifies the terminal identification from which the document
originated.
Syntax
{{termid ID}}
Example {{termid A3}}
190
The example specifies that the current document came from
terminal A3.
TIME
The recipient’s email address. This command is only available if you
have licensed the InternedLink Module.
Syntax
Sets the time today when the document should be transmitted. If
you enter a time that is earlier than the current time, the document
will be sent immediately. You can combine the {{time}} with {{date}}
commands to schedule the document.
The colon is required if hours and minutes are specified. If no
{{time}} command is specified, the time at which the document was
received by the RightFax RightFax Integration Module is used.
If you enter a time that is in the past, the document is transmitted
immediately. Documents are also transmitted immediately with the
time 0.
Syntax
TO
{{time hour:minute}}
Example {{time 22:45}}
{{to emailaddress}}
Examples {{to [email protected]}}
See also “FROM” on page 177
“CC” on page 170
“SUBJECT” on page 190
TRANID
Sets the identification of the transaction that produced the
document.
Syntax
{{tranid ID}}
Example {{tranid BR549}}
The example sets the transaction ID for this document to “BR549”.
The example sets the time to transmit the current document to
10:45 P.M. today
See also “DATE” on page 172
TM
Sets the top margin for the current and subsequent pages in the
specified units. Text will not render above this margin on the page
after this command. By default, there is no top margin (in other
words, the top margin is zero).
Syntax
{{tm margin}}
Example {{tm 0.25}}
The example sets the top margin for the current document to 1/4
inch (or current unit).
See also “BM” on page 170
“LM” on page 179
191
OpenText RightFax 10.5 Integration Module Guide
TYPE
Table Be Type Options (Continued)
This specifies the type of document. You must specify the
document type with either this command, the {{fax}} command for
faxes, or (if you have licensed the InternetLink Module) the
{{begin}} command for email. The available document types are
listed here.
Option
Description
Mime
Documents are rendered as TIF images and included
as an attachment to an e-mail message. To send
documents as e-mail, you must license the RightFax
InternetLink Module. If you choose {{type mime}}, then
you must also use the {{imagetype}} command to
specify the type of MIME-encoded graphic attachment
to create (PCX, TIF, or PDF).
Table Be Type Options
Option
Description
Fax
Documents are rendered as TIF images and
transmitted via fax.
Print
Documents are rendered as TIF images, scaled to
full-size, and then printed. You can specify the number
of copies to print. If the number of copies is not
specified, one copy prints. The printed document will
include production cover sheets (.cov files). Enterprise
cover sheets (.pcl and .doc files) are not printed.
File
Documents are rendered as TIF images. You can
specify the file and path names. This command cannot
be used when submitting Embedded or False First
Page (FFP) documents to the RightFax Integration
Module.
Email
Documents are rendered as text and included in the
body of an e-mail message. To send documents as
e-mail, you must license the InternetLink Module. Note
that if you have specified email format in the {{begin}}
command, you do not need to use the type command.
Note that if you have specified mime format in the
{{begin}} command, you do not need to use the type
command.
Certified
Documents are sent as certified e-mails. To send
documents certified delivery, you must license and
install the RightFax SecureDocs Module.
SMS
Specifies that notifications about the fax transmission
will be sent to an SMS-capable device. Use the syntax
{{type sms serviceID}} where serviceID is the
SMS/Pager service ID for an SMS service defined in
Enterprise Fax Manager. For more information on
creating Pager/SMS services in Enterprise Fax
Manager, refer to the RightFax Administrator’s Guide.
Syntax
{{type type copies filename}}
Examples {{type fax}}
{{type file c:\Program
Files\RightFax\Production\Forms\Example.tif}}
{{type print 2}}
The first example establishes that the document will be sent as a
fax, rather than a file or be sent to a printer. This is the RightFax
Integration Module default—all documents are assumed to be faxes.
You would use {{type fax}} only if you had made file or print the
default, but wanted to fax a particular document or group of
documents. See ”Setting Defaults for FCL Documents” on
page 126.
192
The second example creates a document called Example.tif in the
Forms folder.
The third example prints two copies of the document. The printer
used is the default established in the RightFax Integration Module
Configuration program (it must also be defined in Enterprise Fax
Manager). To change the printer with FCL, you can include {{lp}},
{{lpr}}, or {{printer}} (page 179).
See ”Setting Defaults for FCL Documents” on page 126.
You can also use the {{unique_id}} command in cover sheet
creation and notification templates. If you do not use this command
in a document, the ID default is prod docnum, where docnum is a
unique integer.
Syntax
{{unique_id ID}}
Examples {{unique_id test:01ea}}
{{unique_id test:01eb}}
{{Unique_id}} translates to the RightFax server field unique_id.
See also “PRINTNOW” on page 186
“LP, LPR, or PRINTER” on page 179
UNDERLINE
Sets underlining on or off for subsequent text in the current
document.
Syntax
{{underline {on|off}}}
UNITS
Sets the units of measurement to use for subsequent commands in
the current document. Units of measure can be:
z
z
z
Example {{underline on}}
The example turns on underlining.
See also “FONT” on page 176
UNIQUEID or UNIQUE_ID
Provides a tracking mechanism in FaxUtil by setting the ID field for
one destination (one fax number) within the document. (For
information on FaxUtil, see the RightFax Administrator’s Guide.)
You can use up to 15 alphanumeric characters in the {{unique_id}}
command. If you use more than 15 characters, the command is
truncated at the 15th character.
z
Inches — in
Centimeters — cm
Points (72nds of an inch) —points
Pixels (200ths of an inch) —pixels
The default is inches. You set the default unit of measurement for all
documents in the FCL processor settings in the RightFax
Integration Module Configuration program. See ”Setting Defaults
for FCL Documents” on page 126. The {{units}} command
overrides this global default for each document in which the
command is used.
Syntax
{{units measure}}
Example {{units cm}}
The example sets the units of measurement for subsequent
commands in this document to be centimeters.
USER1, USER2, or USER3
These commands can hold user-defined information.
193
OpenText RightFax 10.5 Integration Module Guide
These commands can be used only in notifications and RightFax
Integration Module (.cov) cover sheets.
Syntax
{{user1 user information}}
{{user2 user information}}
{{user3 user information}}
Example {{user1 Some important information}}
USERID
Identifies the creator of this document.
Syntax
{{userid ID}}
Example {{userid John Doe}}
The example sets the user ID for this document to “John Doe”.
Times must be represented as two digits, with leading zeros as
necessary, with the exception of the four-digit year and the TZD.
Table Bf Time Options
Option
Definition
Example
YYYY
Year
1970-2038
MM
Month
01-12 (January = 01)
DD
Day
01-31
hh
Hour
00-23
mm
Minute
00-59
ss
Second
00-59
TZD
Time zone designator (Z or
+hh:mm or -hh:mm)
UTC
To avoid confusion caused by different time zones, the UTC
command sets the date and time when a document should be sent
in Universal Coordinated Time.
Alternatively, you can use a Time Zone Designator (TZD). A TZD of
+hh:mm or -hh:mm indicates that the date/time uses a local time
zone that is a particular number of hours and minutes (specified by
hh and mm) ahead of or behind Universal Coordinated Time.
If you do not specify a TZD, then Universal Coordinated Time is
assumed.
Syntax
{{UTC YYYY{-|/}MM{-|/}DD{T| }hh:mm:ss TZD}}
Examples {{UTC 2000-01-24T22:25:00Z}}
{{UTC 2000-01-24T23:25Z+01:00}}
{{UTC 2000-01-24T14:25-08:00}}
VOICE
Sets the voice number to be associated with the current document.
This is useful for specifying a voice number on a cover sheet or
notification.
Syntax
{{voice number}}
Example {{voice 503-555-4329}}
The example sets the voice number associated with this document
to (503) 555-4329.
{{Voice}} translates to the RightFax server field to_contactnum.
See ”Using Cover Sheets in a Broadcast” on page 130.
WINSECID
Specifies the RightFax user; or, if you have not created the user yet
in Enterprise Fax Manager, {{winsecid}} creates it. Because
{{winsecid}} can create a user, it is different from “USERID”
(page 194), which is informational.
194
Place the {{winsecid}} command in the global.beg file or in the FCL
from the host. Without a {{winsecid}} command, the default user
account will be used to send documents from the RightFax
Integration Module. The settings for a default user are typically not
optimized for sending documents from the RightFax Integration
Module (notifications, cover sheet settings, etc.).
By changing the {{winsecid}} command in the global.beg file, you
can specify or change the default RightFax user account used by
the RightFax Integration Module. (Open the global.beg file using
Notepad or another text editor and change the user name in
{{winsecid}}.)
Syntax
{{winsecid user}}
Example {{winsecid John Doe}}
195
OpenText RightFax 10.5 Integration Module Guide
196
Index
Symbols
.mtd documents
FCL codes for 57
file conversion 57
in native file format 151
inline via HTTP/S for XML Interface 103
maximum number of pages 128
multipart MIME via HTTP/S for XML
Interface 103
with IBM WebSphere MQ for the XML
Interface 105
35
Numerics
3270 emulation
connection guidelines 10
notification message channel
5250 connection guidelines 11
85
A
B
abort FCL code 165
action XML Interface function 101
activate InternetLink Module 149
activate the connector 156
add FCL to document templates 161
addcopies FCL code 165
addressing documents 128
altfax FCL code 165
approval FCL code 165
ASCII text files 7
ATTACH command 151
attach FCL code 165
attachments
cover sheets 54
example document 58
examples 151
background form 157
background forms
creating 132
example 132
linking to a document 132
overview 132
BASE64
encoding a binary data file for the XML
Interface 105
for XML attachments with IBM WebSphere
MQ 105
for XML file attachments 104
batch FCL code 166
begin FCL code 166
begincvt FCL code 167
BEGINNATIVE command 151, 167
billing FCL code 169-??
binary data with XML Interface 105
bm FCL code 170
box FCL code 170
box with fill color, example in FCL
document 60
box, example in FCL document 60, 62
broadcasting
cover sheets in 130
example 130
with FCL codes 128
Bufdir.exe
creating a directory scan 19
Buffer.exe 8
C
Capture.exe
creating a serial capture 20
capturing data via a named pipe 17
capturing data via a TCP/IP port for an IBM
WebSphere MQ connection 24
CC command 170
cleartabs FCL code 171
comment FCL code 171
company name, default for cover sheet 126
connection channels
creating 15-16
197
OpenText RightFax 10.5 Integration Module Guide
directory scanning 19
named pipe 17
serial port 20
TCP/IP port 23
TCP/IP port for IBM WebSphere MQ
connection guidelines
3270 emulation 10
5250 emulation 11
FTP 11
LPR 10
TCP/IP 11
contact FCL code 171
convert XML to FCL 99
cover FCL code 171
Cover Page tab 158
cover sheet 158
cover sheets
attaching with FCL code 54
broadcasting with 50
creating 50
default 50, 126
default company name 126
default CSID 126
example 49
example FCL document 56
FCL codes for 53-54
for broadcasting 130
keywords 51-53
logic 55
with XML Interface 105
covertext FCL code 172
create InternetLink documents 150
csi FCL code 172
CSID, default for cover sheet 126
current units, setting default for FCL 127
Custom FCL tab 161
24
D
database notification channel 83
database notifications 83
date FCL code 172
dbnotify.exe 84
debug mode, Java API 145
default
company name for cover sheet 126
cover sheet 50, 126
CSID for cover sheet 126
fonts 68
image quality 127
margins 65
page length 35
page orientation 69
printer 126
tabs 67
units of measure for FCL 127
delay FCL code 173
dept FCL code 173
directory scanning 19
document data flow overview 8
document templates
adding FCL to 161
overview 155
document types, choosing 150
documents
specifying destination 128
documents, FCL requirements for 150
DTDs
XML_FAX_ACTION_REPLY.dtd 115
XML_FAX_NOTIFICATION.dtd 116
XML_FAX_QUERY_REPLY.dtd 113
XML_FAX_SUBMIT_REPLY.dtd 112
E
email FCL code 173
email messages
document content for 150
send notification when a fax fails 153
email server name 149
e-mail via the connector 155
empid FCL code 173
encoding
example using BASE64 to encode a binary
data file for the XML Interface 105
for XML file attachments 104
for XML file attachments with IBM
WebSphere MQ 105
encrypted documents
setting permissions with FCL 184
end FCL code 173
endcovertext FCL code 173
endcvt FCL code 174
ENDNATIVE command 174
endpoly FCL code 174
Event Log 127
examples
background form 132
box in FCL document 60, 62
box with fill color in FCL document 60
broadcasting 130
cover sheet with document 49, 56
document with attachment 58
document with signature 64
faxing from Java API 140
FCL documents 133
fonts in documents 68
HTTP/S post with XML Interface 103
line in FCL document 61-62
notification message 89
notification message process 72
notification message template 78
198
setting margins for document 65
tabs in documents 66
XML Interface documents 117
executable files, list of 163
execute FCL code 174
F
failed fax 153
failed transmission 160
fax
documents with FCL 128
example in Java API 140
maximum number of pages to attach 128
maximum page length 128
minimum page length 128
reduce image size 128
fax document when transmission fails 160
fax document when transmission
succeeds 159
fax FCL code 174
fax image resolution 70
fax image, indented in document 127
fax number
printing document if missing 36
fax via the connector 155
FCL code
abort 165
addcopies 165
adding graphics with 64
adding signatures with 63
altfax 165
approval 165
attach 165
attaching files with 57
background form for a document 132
batch 166
begin 166
begincvt 167
billing 169-??
bm 170
box 170
broadcasting with 128
cleartabs 171
comment 171
contact 171
converting from XML 99
cover 171
covertext 172
creating documents with 125
creating notifications with 89
creating shapes with ??-60
csi 172
date 172
delay 173
dept 173
email 173
empid 173
end 173
endcovertext 173
endcvt 174
endpoly 174
example documents 133
execute 174
fax 174
fax image quality 70
ff 175
file 175
fillbox 175
font 176
fonts for documents 68
for cover sheets 53-54
for scheduling transmission 71-72
form 176
form feed 66
in notification messages 90-91
include 177
including external files with 47
libdoc 178
line 178
lineto 178
linewidth 178
list 178
list of 165
lm 179
lookup 179
lp 179
lpr 179
moveto 180
no cover 180
note 180
notifyhost 180
onerror 181-??
onsuccess 182-??
orient 183
owner 183
page orientation 69
place 184
placeall 184
placelast 185
placexy 185
position 185
preview 185
printer 179
printing documents with
printnow 186
priority 186
quality 186
rbox 186
rem 187
replyto 187
rfillbox 187
rline 187
rlineto 188
rmoveto 188
rstartpoly 188
rti 188
131
Index
199
OpenText RightFax 10.5 Integration Module Guide
sending documents to a file with 131
sending documents with 128
sending one document to many recipients
with 128
settab 189
setting tabs with 66
sign 189
signature 189
sms 189
smsmsg 189
startpoly 189
syntax 125
tab 190
termid 190
time 191
tm 191
tranid 191
type 192
underline 193
uniqueid 193
units 193
user1 193
userid 194
utc 194
voice 194
winsecid 194
FCL documents
code format 125
creating 125
fax when recipient data is missing 97-98
print when recipient data is
missing 97-98
FCL, adding to document template 161
FCL, required in InternetLink documents 150
ff FCL code 175
field types, MapText 38-41
fields, filter template 38-41
file conversion of attachments 57
file FCL code 175
file transport command line in XML
Interface 104
file transport, with XML Interface 103
fillbox FCL code 175
filter mode 7
filter template
creating 30-37
fields 38-41
input channel for documents 42
maintaining 29
planning 29
preview 37
troubleshooting 41-42
font FCL code 68, 176
font, setting for a fax 158
fonts
default 68
example 68
FCL code for 68
strikeout 68
TrueType 67
underline 68
Windows 68
form FCL code 176
form feed FCL code 66
format
for FCL codes 125
Forms tab 157
FTP connection guidelines 11
FTP notification channel 86
G
Generate Image function 37
global include files
adding data to 47
linking to documents 47
names 46
overview 45
graphic, adding to document with FCL
code 64
H
host name 149
HTTP XML Interface transport 102
HTTP/S XML Interface transport 102
I
IBM WebSphere MQ
attachments with the XML Interface 105
creating an input 24
notification channel 87
testing notification channel 92
XML Interface transport method 104
ID, unique, in Java API 143
image quality, setting default 127
image size, reducing 128
image type 150
IMAGETYPE command 150, 177
include FCL code 177
include files 151
adding data to global 47
content of 46
creating 47
creating list of recipients for
broadcasting 129
global 45
include FCL code 47
linking to documents 47
names of global 46
overview 45
standard 45
indentation (pixels) 127
inline attachments via HTTP/S for XML
Interface 103
input channels
200
creating 15-16
for filter template documents 42
install the connector 156
installing
Java API 137
XML Interface 99
Integration Module Configuration program,
starting 126
Integration Module setup wizard, starting 12
J
Java API
action on a document 143-145
debug mode 145
fax example 140
installing 137
querying a fax 142
sending documents 138
status codes 146
K
keywords
for cover sheets 51-53
for notification message templates
L
landscape page orientation 69
Layout tab 158
libdoc FCL code 178
line FCL code 178
line, example in FCL document 61-62
lineto FCL code 178
linewidth FCL code 178
list FCL code 178
lm FCL code 179
logo, adding to a fax 157
lookup FCL code 179
74-76
lookup tables 6
Lotus Notes notification channel 88
lp FCL code 179
LPR connection guidelines 10
lpr FCL code 179
LPR, connecting with a named pipe 17
M
Makedoc.exe 8
MapText
.mtd documents 35
starting 30
MapText field types 38-41
margins
example document 65
setting default 65
margins, setting for a fax 158
maximum attached pages 128
message body 150
message body text in XML Interface 105
Microsoft Exchange notification channel 88
MIME attachments with XML Interface 103
Mime.inc 151
Mimesend.exe 8
moveto FCL code 180
Mqget.exe
command line syntax 25
creating an IBM WebSphere MQ
input 24
multipart MIME attachments 103
N
named pipe, creating a capture 17
native files, attaching to documents 151
native mode 7
new page FCL code 66
nocover FCL code 180
note FCL code 180
notification message channels
command line 81
creating 79
Notify.exe 81
overview 79
testing ??-94
testing IBM WebSphere MQ 92
notification messages 153, 160
creating communication channels 79
creating templates 73-74
example document 89
example of process flow 72
example template 78
FCL codes in 90-91
keywords for 74-76
overview 7, 72
retaining copies on RightFax server 80
notification XML Interface function 101
notifications
fax a copy of document upon
transmission 94-95
fax a copy of document upon transmission
failure 96-97
fax document when recipient data is
missing 97-98
print a copy of document upon
transmission 94-95
print a copy of document upon
transmission failure 96-97
print document when recipient data is
missing 97-98
sending notifications to a database 83
sending notifications via SMS 84
vs. submit-reply XML Interface
function 101
Notify tab 160
Notify.exe 8, 81
notifyhost FCL code 180
Index
201
OpenText RightFax 10.5 Integration Module Guide
Nplisten.exe
creating a named pipe capture 17
O
On Error tab 160
On Success tab 159
ONERROR command 153
onerror FCL code 181-??
onsuccess FCL code 182-??
opening
Integration Module Configuration
program 126
Integration setup wizard 12
MapText 30
orient FCL code 183
overview, document data flow 8
owner FCL code 183
P
page length
default 35
maximum 128
minimum 128
page orientation
default 69
page orientation, setting for a fax 158
Parse.exe 8
PCL (print control language) files 7
PCX image type 150
PDF image type 150
permissions for encrypted documents
setting with FCL 184
place FCL code 184
placeall FCL code 184
placelast FCL code 185
placexy FCL code 185
Portlstn.exe 23
portrait page orientation 69
position FCL code 185
PostScript files 7
preview a filter template 37
preview FCL code 185
print control language (PCL) files 7
print copies if no fax number 36
printer FCL code 179
printer, setting 158
printer, setting default 126
printing with FCL 131
printnow FCL code 186
priority FCL code 186
programs, list of 163
Q
quality FCL code 186
query XML Interface function 101
querying a fax with Java API 142
R
rbox FCL code 186
recipients
specifying addresses 128
rem FCL code 187
replyto FCL code 187
requirements, system 149
resolution, fax 70
rfillbox FCL code 187
rfsms.exe 84
RFWebCon.dll library in XML Interface 102
rline FCL code 187
rlineto FCL code 188
rmoveto FCL code 188
rstartpoly FCL code 188
rti FCL code 188
S
scheduling transmission 71
schemas
XML Interface schemas 106-116
XML_FAX_ACTION_REPLY.dtd 115
XML_FAX_ACTION_SCHEMA 114
XML_FAX_QUERY_REPLY.dtd 113
XML_FAX_QUERY_SCHEMA 112
XML_FAX_SUBMIT_REPLY.dtd 112
XML_FAX_SUBMIT_SCHEMA 106
send
e-mail using the connector 155
fax using the connector 155
send documents as email if faxes fail 153
sending
documents to a file with FCL 131
one document to many recipients 128
one document to many recipients with
include files 129
settab FCL code 189
shape FCL codes ??-60
sign FCL code 189
signature FCL code 189
signature, adding to document with FCL
code 63
sms FCL code 189
SMS notification channel 84
SMS notifications 84
smsmsg FCL code 189
SMTP host name 149
SMTP notification channel 82
standard include files
content of 46
creating 47
linking to documents 47
overview 45
starting
Integration Module Configuration
202
program 126
Integration Module setup wizard 12
MapText 30
startpoly FCL code 189
status codes
Java API 146
XML Interface 146
submit XML Interface function 100
successful transmission 159
syntax for FCL codes 125
system requirements 149
T
tab FCL code 190
tabs
Cover Page 158
Custom FCL tab 161
example 66
FCL code 66
Forms 157
Layout 158
Notify tab 160
On Error tab 160
On Success 159
setting default 67
TCP/IP connection guidelines 11
TCP/IP port capture 23
templates
adding FCL to 161
creating cover sheet 50
creating notification 73-74
overview 155
termid FCL code 190
text files 7
text for message body with XML
Interface 105
TIF image type 150
time FCL code 191
tm FCL code 191
tranid FCL code 191
transmission
fax a copy of document upon
failure 96-97
fax a copy of document upon
success 94-95
fax document when recipient data is
missing 97-98
print a copy of document upon
failure 96-97
print a copy of document upon
success 94-95
print document when recipient data is
missing 97-98
scheduling 71
transmission quality
setting default 127
setting with FCL 70
transports
file attachments with XML Interface 104
XML Interface 99
trim trailing white space 128
troubleshooting
filter templates 41-42
notification message channels ??-94
TrueType fonts 67
type FCL code 192
U
underline FCL code 193
unique ID
in Java API 143
in XML Interface 101
uniqueid FCL code 193
units FCL code 193
units of measure for FCL 127
user1 FCL code 193
userid FCL code 194
utc FCL code 194
V
voice FCL code
194
W
Windows Event Log 127
Windows fonts 68
winsecid FCL code 194
X
XML
converting to FCL 99
multipart MIME attachments 103
XML Interface
attachments via HTTP/S 103
attachments with IBM WebSphere
MQ 105
example documents 117
example HTTP/S post 103
file transport attachments 104
file transport command line 104
inline attachments via HTTP/S 103
installing 99
multipart MIME attachments 103
notification vs. submit-reply function 101
RFWebCon.dll library 102
schemas 106-116
status codes 146
text for cover sheet 105
text for message body 105
transport options and functions 99, 137
unique ID 101
using XSLT scripts 101
with binary data 105
XML Interface functions
Index
203
OpenText RightFax 10.5 Integration Module Guide
action 101
notification 101
query 101
submit 100
XML Interface transports
file 103
HTTP/S 102
IBM WebSphere MQ 104
XML_FAX_ACTION_REPLY.dtd 115
XML_FAX_ACTION_SCHEMA 114
XML_FAX_NOTIFICATION.dtd 116
XML_FAX_QUERY_REPLY.dtd 113
XML_FAX_QUERY_SCHEMA 112
XML_FAX_SUBMIT_REPLY.dtd 112
XML_FAX_SUBMIT_SCHEMA 106
XSLT scripts with the XML Interface 101
204
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement