Table of Contents
i-fax.com
Architecture
The i-fax.com Plug-In is split into two
parts:
-
The Barcode Generator
The Barcode Generator accepts a value to encode and
generates a barcode that is then inserted into a
pdf document you specify.
i-fax.com also provides plug-ins in various
languages for many document formats (e.g. Microsoft
Word, HTML and GIF) as well as utilities for merging
barcodes with existing PDF documents and for creating
sheets of barcoded laser address labels for barcoding
existing paper documents. Please visit http://www.i-fax.com/plugin.html
for a full list of our plug-ins.
-
Your Website
When an end user sends a barcoded document to the
i-fax.com server (by fax or scanner), the
barcode is interpreted by i-fax.com's
server. The i-fax.com server renames the
document with the encoded identifier found in the
barcode and sends the document to your website.
Documents can be delivered in the using the following
protocols:
- FTP file transfer,
- Secure FTP file transfer,
- Secure Shell (ssh) file transfer,
- or as an Email attachement.
ColdFusion PDF Version of
the i-fax.com Plug-In
Description of the ColdFusion PDF
Version of the i-fax.com Plug-In
The i-fax.com ColdFusion PDF plug-in contains the Java class
"ColdFusionPDFMerge64.class", which permits you to quickly
and simply add the i-fax.com barcode to your PDF
documents.
ColdFusionPDFMerge64 encodes a 64-bit numeric value, and is
compatible with the .GIF version of the barcode.
The following files are for an earlier version of the
barcode plugin, now deprecated:
ColdFusionPDFMerge187.class
ColdFusionPDFMerge48.class
All versions place the transaction ID in human-readable
form above the barcode, making it easy to identify a
document's transaction ID even in hardcopy.
Installing the ColdFusion PDF
Version of the i-fax.com Plug-In onto your
Website
- The ColdFusion compatible version of the PDF Merge Utility requires
that you to use the
ColdFusionPDFMerge64 Java class.
Find the class path for your Java version and create
a subdirectory of it called /com/Ifax/Barcode/. For
instance, in a normal Windows desktop environment the
classpath is c:\windows\java\CLASSES, so you would
create a directory called
c:\windows\java\CLASSES\com\Ifax\Barcode. Other
platforms and installations will have classpaths in
different locations, please see your system or
application documentation for details.
The PDF i-fax.com Plug-In may work in
conjunction with your web application but it is not a
web application. We recommend that you keep the
i-fax.com classes in a directory outside your
web directory tree if possible. Make sure that the
class files have the correct ownership and permissions
to be accessible by your application.
-
Put the files ColdFusionPDFMerge64.class and
PDFMerge64.class in the
newly created directory.
-
The files ifaxpdfmerge64example.asp and example.pdf should be put in a test environment on your web tree.
Choosing a Value to
Encode
Prior to creating a Barcode, your application must
create a unique identifier and encode it for
inclusion in the Barcode. A unique identifier can be any
value that your application will find meaningful; a
transaction ID, a sequence number, an account number, or a
form number.
When an end user returns a document encoded with an
i-fax.com Barcode, you will use this unique
identifier to link the document image to the data on your
website or in your database.
You do not need to encode large amounts of data in the
i-fax.com Barcode. You can use a record identifier
that will link the Barcoded document or PDF page to data
that was captured while a user was on-line.
|
Warning:
This unique identifier value is leaving your
site and your control.
It is important that you use the least amount of
information necessary. For example, it is not
recommended that you use a person's account
number when you can use a transaction identifier for
a specific transaction.
|
Using the PDFMerge64
Plug-In
There are several ways of adding i-fax.com barcodes
to .pdf documents
- If you only want to put a barcode on one of the
pages of the document and want to capture the created pdf
file to a string, the simplest way is to use
the getPDFMerge method and pass it
the name of the file, the value to
encode in the barcode, where on the page you want the
barcode to appear and the page number you want to put
the barcode on.
String getPDFMerge(String pdffile, String transid, String orient, long pagenumber)
- pdffile is the name of an existing PDF
file that you wish add a barcode to.
- transid is the unique identifier you wish to
include in this barcode (see the explanation of "unique identifiers" in the section
above). The ID must be a string representation of a number
between 0 and
18,446,744,073,709,551,615).
- orient allows you to place the
barcode at the top or bottom of the page. Setting
this to "1" places it at the top,
"0" puts it at the bottom, and setting it
to "2" puts copies at both the top and
bottom.
- pagenumber is the pagenumber of the pdf
document to put the barcode on.
Important Tip
It is strongly recommended that you use the "2" value for the orienttop parameter.
Placing an i-fax.com barcode at the top and bottom of each page will significantly improve the recognition rate of the barcode and will substantially reduce your labor costs. |
- If you only want to put a barcode on one of the
pages of the document and want to output the created pdf
file to a file, the simplest way is to use
the getPDFMergeToFile method and pass it
the name of the file, the name of the file to create, the value to
encode in the barcode, where on the page you want the
barcode to appear and the page number you want to put
the barcode on.
void getPDFMergetoFile(String pdffile, String outfile, String transid, String orient, long pagenumber)
- pdffile is the name of an existing PDF
file that you wish add a barcode to.
- outfile is the name of an new PDF
file you want to create.
- transid is the unique identifier you wish to
include in this barcode (see the explanation of "unique identifiers" in the section
above). The ID must be a string representation of a number
between 0 and
18,446,744,073,709,551,615).
- orient allows you to place the
barcode at the top or bottom of the page. Setting
this to "1" places it at the top,
"0" puts it at the bottom, and setting it
to "2" puts copies at both the top and
bottom.
- pagenumber is the pagenumber of the pdf
document to put the barcode on.
Important Tip
It is strongly recommended that you use the "2" value for the orienttop parameter.
Placing an i-fax.com barcode at the top and bottom of each page will significantly improve the recognition rate of the barcode and will substantially reduce your labor costs. |
- If you want to put barcodes on more than one of the page
of the document it is a two-step process. First you
pass the information about all the barcodes you want to
create with the addBarcode method.
void addBarcode (String transid, String orient, long pagenumber)
- transid is the unique identifier you wish to
include in this barcode (see the explanation of "unique identifiers" in the section
above). The ID must be a string representation of a number
between 0 and
18,446,744,073,709,551,615).
- orient allows you to place the
barcode at the top or bottom of the page. Setting
this to "1" places it at the top,
"0" puts it at the bottom, and setting it
to "2" puts copies at both the top and
bottom.
- pagenumber is the pagenumber of the pdf
document to put this barcode on.
Important Tip
It is strongly recommended that you use the "2" value for the orienttop parameter.
Placing an i-fax.com barcode at the top and bottom of each page will significantly improve the recognition rate of the barcode and will substantially reduce your labor costs. |
Once you have used addBarcode to list all the pages
you want to have barcodes on, use the getPDFMerge
method to create the new barcoded pdf to a String or getPDFMergeToFile
to output the newly created pdf to a file.
String getPDFMerge(String pdffile)
void getPDFMergetoFile(String pdffile, String outfile)
- pdffile is the name of an existing PDF
file that you wish add a barcode to.
- outfile is the name of a file to output the
newly barcoded pdf to.
- For applications that can make use of raw PDF
graphic streams, the method "getPDFBarcode" takes the value to encode in the barcode and where on
the page you want the barcode to appear and returns a
PDF graphic stream that can be used with PDF generating
software.
String getPDFBarcode(String transid, String orient)
- transid is the unique identifier you wish to
include in this barcode (see the explanation of "unique identifiers" in the section
above). The ID must be a string representation of a number
between 0 and
18,446,744,073,709,551,615).
- orient allows you to place the
barcode at the top or bottom of the page. Setting
this to "1" places it at the top,
"0" puts it at the bottom, and setting it
to "2" puts copies at both the top and
bottom.
Important Tip
It is strongly recommended that you use the "2" value for the orienttop parameter.
Placing an i-fax.com barcode at the top and bottom of each page will significantly improve the recognition rate of the barcode and will substantially reduce your labor costs. |
|
Browser Behavior Warning
If you are using a PDF Merge Plug-In as part of a web
application to deliver barcoded PDFs to users, you
may wish to temporarily save the barcoded PDF to disk
and redirect the user's browser to the new PDF
file.
Some users running Internet Explorer and the
Acrobat plug-in may experience difficulty handling
"streamed" PDF output generated
dynamically.
|
Design Considerations for
PDF Documents
The PDF Merge Plug-In places a barcode on the top and/or
bottom of a page of the PDF document. It is
important to keep these parts of the page free from any other
graphics that may interfere with the printing of the
barcode; you will need to keep the top (and/or bottom) 2 inches
of the first page blank (5 cm). This requirement is for the
pages of the document getting barcodes only, the rest of the PDF can be
formatted as you see fit.
The PDF Merge Plug-In will not work with linearized
(optimized for streaming on the web), encrypted (secured
with password) or incrementally updated PDF's. When you
create the PDF's to be merged, please ensure that these
options are not set. To be certain that the PDF is free
from these options, you can open the PDF in Adobe Acrobat,
select File/Save As... set Security to "none" and
clear the Optimize checkbox, then save the file.
Using the PDF Merge
Utility in an ColdFusion application
The file ifaxhpdfmerge64example.cfm is a fully functional demonstration of how to use the i-fax.com PDF merge utilities in an ColdFusion environment. There are three steps required; first, the Java class must be instantiated with a call to GetObject()
<cfobject Type="Java" Action="Create" Class="com.Ifax.Barcode.ColdFusionPDFMerge64" Name="barcode">
Next, the barcoded document must be generated. You can stream it directly to the browser with:
cfset barcodestring = barcode.getPDFMerge(inputfile, transid, "2", 1)
<cfoutput>#barcodestring#</cfoutput>
Or you can save it directly to a file:
<cfset ret = barcode.getPDFMergetoFile(inputfile, outputfile, id, "2", 1)>
If you wanted to barcode more than one page in a document, you could do it this way
<cfset ret = barcode.addBarcode(inputfile, outputfile, transid_for_first_page, "2", 1)>
<cfset ret = barcode.addBarcode(inputfile, outputfile, transid_for_second_page, "2", 2)>
Then either output directly to the browser:
cfset barcodestring = barcode.getPDFMerge(inputfile)
<cfoutput>#barcodestring#</cfoutput>
or redirect it to a file:
<cfset ret = barcode.getPDFMergetoFile(inputfile, outputfile)>
The files ifaxhpdfmerge64example.cfm is a fully functional demonstration of how to use the i-fax.com PDF merge utilities in a ColdFusion environment. There are three steps required; first, the Java classes must be instantiated, either
<cfobject Type="Java" Action="Create" Class="com.Ifax.Barcode.ColdFusionPDFMerge64" Name="barcode">
or
<cfobject Type="Java" Action="Create" Class="com.Ifax.Barcode.ColdFusionPDFMerge187" Name="barcode">
depending on which version of the barcode you wish to use.
Next, the barcoded document must be generated. You can generate it as a string with:
<cfset barcodestring = barcode.getPDFMerge(inputfile, id, 1)> <!--- ColdFusionPDFMerge64 version --->
<cfset barcodestring = barcode.getPDFMerge(inputfile, id, format, 1)> <!--- ColdFusionPDFMerge187 version --->
Finally, output it with:
<cfheader name = "Content-Type" value = "application/pdf">
<cfoutput>#barcodestring#</cfoutput>
Alternatively, you can generate it directly to a file:
<cfset barcodestring = barcode.getPDFMergetoFile(inputfile, outputfile, id, "1")> <!--- ColdFusionPDFMerge64 version --->
<cfset barcodestring = barcode.getPDFMergetoFile(inputfile, outputfile, id, format, "1")> <!--- ColdFusionPDFMerge187 version --->
and redirect the browser to where it is stored.
Your Website
When an end user sends a barcoded document to the
i-fax.com server (by fax or scanner), the barcode is
interpreted by i-fax.com's server. The
i-fax.com server renames the document with the
encoded identifier found in the barcode and sends the
document to your website by FTP file transfer or as an
email.
File Types
i-fax.com will deliver files to your server by
FTP or Email. Every file sent from the i-fax.com
server will follow this naming convention:
|
i-fax.com File
Naming Convention
aaaaaaaaaaaaaaaa_bbbbbbbbbbbbbbbb_999.TTT
|
aaaaaaaaaaaaaaaa |
The unique identifier found in the
i-fax.com Barcode (created by the
i-fax.com barcode generator by your
application).
|
bbbbbbbbbbbbbbbb |
A transaction key assigned by
i-fax.com.
|
999 |
The page number (000 is reserved for the
thumbnail) for JPEG files only.
|
TTT |
The file extension of different output
formats, e.g. pdf, tif, jpg, udt.
|
| Unique Identifier |
The unique identifier is the value that your
application assigned at the time the i-fax.com
Barcode was created using the i-fax.com
Plug-In.
|
| Transaction Key |
i-fax.com assigns a unique transaction key
to every transaction that is processed by a server.
This transaction key ensures that each file that your
web server receives is unique and is not overwritten
in the event that a user sends the same document
twice.
|
| Page Number |
The JPEG standard does not support multi-page
documents. As a result, i-fax.com will deliver
a separate JPEG file for each page in the document.
These files will be numbered from 001 ... 999. Please
note that number 000 is reserved for a JPEG thumbnail
page that is explained below.
|
File Formats
The following file types are produced by the
i-fax.com server:
- The first page of the document is provided in a
miniature version in JPEG format (240 x 345 pixels).
This feature can be turned off by i-fax.com (on
your customer profile). If you want this feature turned
off, please contact service@i-fax.com.
The "thumbnail" allows your application to
display a small version of the document (e.g. as a search
result).
- When you sign-up for the i-fax.com
service you will be given the option of selecting one or
more image formats for your documents. i-fax.com
supports 4 image formats. The format you choose will
depend on your application.
Adobe
PDF
The i-fax.com server can produce a multi-page
PDF file containing the document. The document is
compressed in Group IV format to conserve storage
space.
TIFF
The i-fax.com server can produce a multi-page
Group IV TIFF file containing the document.
JPEG
The i-fax.com server will produce a series of
JPEG files, each containing a page of the
document.
PNG
The i-fax.com server will produce a series of
PNG files, each containing a page of the
document.
- If you have elected to receive documents using FTP,
SFTP or ssh, i-fax.com will
send a file with a .udt extension to indicate that
your document has been sent. Clients using earlier
versions of i-fax.com product should see the
following link fin_guide.html.
-
This file will not appear on
your server until all of the document images associated
with your transaction have been delivered (in PDF, TIFF,
JPEG or PNG format).
|
Warning
Regarding FTP, SFTP and ssh
Transactions
Your application should
not start processing files in your FTP, SFTP or ssh
directory until the .udt file is detected on your
server.
The .udt file is not
sent to your server until all of
the files related to your transaction have been
sent. So your server application should
"poll" for the .udt file. This will
ensure that your application does not start
processing files before they have been completely
transmitted to your server.
|
.udt File
Contents
The .udt file contains information about the
files received by i-fax.com.
| Field Name |
Description |
| CallerID |
The caller id of the fax machine that the
document was faxed from. If the document was not
faxed or there was no caller id then the field is set
to "Unknown". |
| TransID |
The unique identifier encoded in the barcode on
the document. This is the same unique id used in the
returned file names. |
| Pages |
The count of pages processed for the
document. |
| Orientation |
"0" if the document was scanned or
faxed with the barcode right side up, or
"1" if the barcode was upside down. When a
document is faxed or scanned in upside down, the
i-fax.com server rotates them before sending
them on for ease of handling. |
| To |
If the document was efiled instead
of faxed, the "To:" line of the email is
put here |
| From |
If the document was efiled instead
of faxed, the "From:" line of the email is
put here |
| Subject |
If the document was efiled instead
of faxed, the "Subject:" line of the email
is put here |
| Senddate |
If the document was efiled instead
of faxed, the "Date:" line of the email
header is put here |
A two-page document encoded with a "unique
identifier" of 639787744 that is faxed upside down
would have the following in the .udt file:
CallerID=Unknown
TransID=63978744
Pages=2
Orientation=1
If you have elected to use i-fax.com's
OCR service then the .udt file will
contain the ocr'd text. Each page of text will start
with a page identifier in the form [Page 1]
followed by the text found on that page. A two-page
document encoded with a "unique identifier" of
639787744 that is faxed upside down would have the
following in the .udt file:
CallerID=Unknown
TransID=63978744
Pages=2
Orientation=1
[Page 1]
...text found on page 1...
[Page 2]
...text found on page 2...
Note:
You will find examples of the Adobe PDF, TIFF, JPEG, PNG
and .udt files with the files you receive when you
Download the Plug-In.
File Transfer
Options
i-fax.com can deliver files to your server in one of two
methods, using a file transfer protocol (such as FTP, SFTP
or ssh) or using Email:
FTP, SFTP
(Secure Socket Layer) and ssh (Secure Shell)
i-fax.com will transfer a group of files to
the server you specify when you sign-up for the
i-fax.com service. You will be asked to provide an
FTP, SFTP or shh account and a directory on your site that
is accessible to a file transfer from
i-fax.com.
It is recommended that you design your application to
poll this directory looking for files with the .udt
extension. i-fax.com always sends a .udt file
when a transaction has been fully transferred.
A number of strategies can be used to initiate the
polling process. The strategy you chose will depend on the
tools available to you on the web server you are using for
your website:
- On Unix or Linux servers, you can schedule a job in
the crontab that will capture transactions in your FTP
directory and incorporate them with your web database.
(This will not be possible in most hosted web
environments.)
- On a Windows
NT®/2000/XP® server, you
can schedule a task in the Task Scheduler that will
capture transactions in your FTP, SFTP or ssh home
directory and incorporate them with your web database.
(This will not be possible in most hosted web
environments.)
- You can imbed a CGI script in a web page
that is executed when the page is accessed. The CGI
script can be designed to detect the arrival of a
.udt file in the FTP directory and process the
incoming document. The CGI script can be placed within a
page that runs when users wish to access a document or in
a page that is run frequently.
|
Note:
For clients that require additional security,
i-fax.com provides 128 bit encryption
(Secure Socket Layer or Secure Shell) free of
additional charge. i-fax.com's
service is HIPAA compliant.
|
Email
i-fax.com will email a group of files to the email
address you specify when you sign-up for the
i-fax.com service.
Each email sent by the i-fax.com server will
contain all of the files pertaining to a specific document.
In the event that an end user sends multiple documents in
one fax or scan (each document having a unique
i-fax.com Barcode), the i-fax.com server will
transmit each document and its associated files in a
separate email.
Emails sent by the i-fax.com server will contain
the relevant files for a given document as attachments.
Each email will contain the following entry in the
"subject" line:
Document
for transaction #{unique identifier from i-fax.com
Barcode}
A number of strategies can be used to incorporate
documents that have arrived by email. These include
programs such as Procmail (for Unix and Linux environments)
and Microsoft Exchange (for Windows
NT®/2000/XP®).
|
