Table of Contents
i-fax.com Architecture
The i-fax.com Plug-In is split into two parts:
-
The Email Tag Generator
The Email Tag Generator takes a value to encode and generates a email tag that can be inserted into a
document generated by your application.
i-fax.com also provides plug-ins in various languages for many document types as well as
utilities for merging barcodes and email tags 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.
PHP Version of the i-fax.com Plug-In
Installing the PHP Version of the i-fax.com Plug-In onto your Website
- Put the .pl files in a directory where your application can find them (e.g. a directory with execution
permission).
-
These perl scripts may work in conjunction with your web application but they are not a cgi application.
We recommend that you keep the i-fax.com scripts in a directory outside your web directory tree if
possible. Make sure that the files have the correct ownership and permissions to be accessible by your
application.
The following is a the script files provided by i-fax.com:
ifaxudt.pl
ifaxpdfmergeudt.pl
-
Put the example PHP and .pdf in a testing area of your website:
example.pdf
ifax_pdfmerge_udt_example.php
- When you have signed up with i-fax.com you will be given an encryption key file. This key is used
to encrypt the contents of the tags you generate to ensure that the tag was generated by your account. Since
this is an encryption key, it must be kept in a secure location.
Description of the PHP Version of the i-fax.com Plug-In
The i-fax.com Plug-In encodes any identifying text that you wish to represent as a email tag and
generates an Email Tag to insert in an Adobe PDF document .
Prior to creating an Email Tag, your application must select a unique identifier and encode it for
inclusion in the Email Tag. A unique identifier can be any number or text 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 Email Tag, you will use this unique
identifier to link the returned documents 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 Email Tag. You can use a
record identifier that will link the tagged document or Adobe 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 PHP version of the PDF Email Tag Utility
The PHP compatible version of the PDF Merge Utility requires that you to use the
ifaxpdfmergeudt.pl Perl Script.
The default method for this script takes the full path and filename of the public encryption key file
provided by i-fax.com, The value you want to encode in the barcode, and the full path and filename of
the pdf file to add the tag to and outputs the tagged document to STDOUT. Your
application must capture this output. If you're developing your application in Perl or a Perl-like
language (such as PHP), you should use "backticks" which redirects STDOUT to a variable
in your code. C code should use popen() to redirect STDOUT.
Syntax: ifaxpdfmergeudt publickeypath transactionid pdffile
- publickeypath is the full path and file name of the public encryption key file provided by
i-fax.com.
- transactionid is the unique identifier explained above.
- pdffile is the full path and file name of the existing PDF you want to add the email tag to.
For example, to put an i-fax.com email tag with a value "12345" in a document named
"example.pdf", you would do the following:
$pdffilecontent = `ifaxpdfmergeudt.pl public_key.pem 12345 example.pdf`;
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®).
|
