Table of Contents
i-fax.com Architecture
The i-fax.com Plug-In is split into two parts:
-
The Barcode Generator
The Barcode Generator takes any value generated by your application that you want to use to uniquely identify a document (such as a transaction key or a record number) and generates a barcode that can be inserted into a web page or document generated by your application.
i-fax.com also provides 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 you by FTP file transfer or as an email.
iTextSharp PDF Version of the i-fax.com Plug-In
Description of the iTextSharp PDF Version of the i-fax.com Plug-In
The i-fax.com iTextSharp plug-in contains
"com.Ifax.Barcode.PDFMerge64.dll", which permits you to quickly
and simply add the i-fax.com barcode to your PDF
documents.
PDFMerge64 encodes a 64-bit numeric value, and is
compatible with the .GIF version of the barcode.
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 iTextSharp PDF Version of the i-fax.com Plug-In onto your Website
Place the com.Ifax.Barcode.PDFMerge64.dll file in a location where your application can find it, normally the same directory your application resides in. For an ASP .NET application, this would be the bin directory of the application. Make sure that the dll files have the correct ownership and permissions to be accessible by your application. Place the ASP .NET example file ifaxitextexample.aspx in the application's directory. To use the example, visit the aspx page in your browser and enter a transaction id -- the barcoded pdf file will be generated and returned to the browser.
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 number 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 number 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 HTML 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 com.Ifax.Barcode.itextPDF64 Class
There are three 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, the simplest way is to use the
getPDFMerge method and pass it the name of the file,
the stream to output the barcoded pdf to, 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 getPDFMerge (String filename,
OutputStream output, ulong id, String orientation,
long pagenumber)
- filename is the name of an existing PDF
file that you wish add a barcode to.
- output is a stream to direct the
newly barcoded pdf to.
- id 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 unsigned long (decimal value not greater than
18,446,744,073,709,551,615).
- orientation 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 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 (ulong id, String
orientation, long pagenumber)
- id 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 unsigned long (decimal value not greater than
18,446,744,073,709,551,615).
- orientation 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.
void getPDFMerge (String filename,
Stream output)
- filename is the name of an existing PDF
file that you wish add a barcode to.
- output is a stream to direct 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 (ulong id, String
orientation)
- id 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 unsinged long (decimal value not greater than
18,446,744,073,709,551,615).
- orientation 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.
|
Placing the PDF Barcode
The image produced by addBarcode should be inserted in your document carefully.
Placement of the PDF Barcode must follow these rules:
- The PDF Barcode must be at the top of the page, with a margin of empty space on three sides (approximately ¾ inch above, right and left).
- The PDF Barcode should appear right after the <body> tag if possible.
- There should not be any graphics, such as logos etc., above the PDF Barcode.
Warning
Failure to place the PDF Barcode in the correct area of a document may cause the Barcode to be rejected by i-fax.com's Server. |
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 barcode generator.
|
| 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). 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 3 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 file, each containing a page of the document.
-
If you have elected to receive files from i-fax.com using FTP (File Transfer Protocol), i-fax.com will send a file with a .udt extension to indicate that your document has been sent. This file will not appear on your server until the JPEG thumbnail and the document images in PDF, TIFF and/or JPEG have been delivered. Note: Your application should not start processing an FTP transfer until the .udt file is detected on your server.
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
Note:
You will find examples of the Adobe PDF, TIFF, JPEG 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 formats:
-
FTP
i-fax.com will transfer a group of files to the FTP server you specify when you sign-up for the i-fax.com service. You will be asked to provide a directory on your site that is accessible to an FTP transfer.
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 server, you can schedule a task in the Task Scheduler 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.)
- 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.
-
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).
|
